1. Description

XMLBeans is a tool that allows access to the full power of XML in a Java friendly way. The idea is to take advantage of the richness and features of XML and XML Schema and have these features mapped as naturally as possible to the equivalent Java language and typing constructs. XMLBeans uses XML Schema to compile Java interfaces and classes that can then be used to access and modify XML instance data. Using XMLBeans is similar to using any other Java interface/class: with methods like getFoo or setFoo, just as when working with Java. While a major use of XMLBeans is to access XML instance data with strongly typed Java classes there are also APIs that allow access to the full XML infoset (XMLBeans keeps XML Infoset fidelity) as well as to allow reflection into the XML schema itself through an XML Schema Object model.

1.1. Characteristics of XMLBeans

1. Large XML Schema support.
2. Large XML Infoset support.

Large XML Schema support: XMLBeans fully supports XML Schema and the corresponding java classes provide constructs for all of the major functionality of XML Schema. This is critical since often one has no control over the features of XML Schema needed to work with in Java. Also, XML Schema oriented applications can take full advantage of the power of XML Schema and not have to restrict themselves to a subset.

Large XML Infoset support: When unmarshalling an XML instance the full XML infoset is kept and is available to the developer. This is critical because that subset of XML is not easily represented in Java. For example, order of the elements or comments might be needed in a particular application.

1.2. Objective

A major objective of XMLBeans has been its applicability in all non-streaming (in memory) XML programming situations. The developer should be able to compile their XML Schema into a set of Java classes and know that they will be able to:

1. use XMLBeans for all of the schemas they encounter.
2. access the XML at whatever level is necessary without other tools.

1.3. APIs

To accomplish the above objectives, XMLBeans provides three major APIs:

• XmlObject
• XmlCursor
• SchemaType

XmlObject: The java classes that are generated from an XML Schema are all derived from XmlObject. These provide strongly typed getters and setters for each of the elements within the defined XML. Complex types are in turn XmlObjects. For example, getCustomer might return a CustomerType (which is an XmlObject). Simple types turn into simple getters and setters with the correct java type. For example, getName might return a String.

XmlCursor: From any XmlObject the developer can get an XmlCursor. This provides efficient, low level access to the XML Infoset. A cursor represents a position in the XML instance. The cursor can be moved around the XML instance at any level of granularity needed from individual characters to Tokens.

SchemaType: XMLBeans provides a full XML Schema object model that can be used to reflect on the underlying schema meta information. For example, the developer might generate a sample XML instance for an XML schema or perhaps find the enumerations for an element so that they may be displayed.

2. Example

An example of a simple XML Schema Definition to describe a country is given below.

<?xml version="1.0" encoding="UTF-8"?> <xs:schema targetNamespace="http://www.openuri.org/domain/country/v1" xmlns:tns="http://www.openuri.org/domain/country/v1" xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.0"> <xs:element name="Country" type="tns:Country"/> <xs:complexType name="Country"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Population" type="xs:int"/> <xs:element name="Iso" type="tns:Iso"/> </xs:sequence> </xs:complexType> <xs:complexType name="Iso"> <xs:annotation><xs:documentation>ISO 3166</xs:documentation></xs:annotation> <xs:sequence> <xs:element name="Alpha2" type="tns:IsoAlpha2"/> <xs:element name="Alpha3" type="tns:IsoAlpha3"/> <xs:element name="CountryCode" type="tns:IsoCountryCode"/> </xs:sequence> </xs:complexType> <xs:simpleType name="IsoCountryCode"> <xs:restriction base="xs:int"> <xs:totalDigits value="3"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="IsoAlpha2"> <xs:restriction base="xs:string"> <xs:pattern value="[A-Z]{2}"/> <xs:whiteSpace value="collapse"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="IsoAlpha3"> <xs:restriction base="xs:string"> <xs:pattern value="[A-Z]{3}"/> <xs:whiteSpace value="collapse"/> </xs:restriction> </xs:simpleType> </xs:schema>

When the schema is compiled into XMLBean classes (e.g., using Ant), it is very easy to create and manipulate XML data that conforms to the schema definition. The following Java code is a simple example that illustrates how an XML document can be created and validated.

import org.openuri.domain.country.v1.Country; import org.openuri.domain.country.v1.Iso; public class CountrySample { public static void main(String[] args) { Country country = Country.Factory.newInstance(); country.setName("Denmark"); country.setPopulation(5450661); // from Wikipedia :-) // print out country XMLBean as XML System.out.println(country.xmlText()); // check if document is valid - will print "Document is invalid" // because required Iso child element in not in the object System.out.println ("Document is " + (country.validate() ? "valid" : "invalid")); // add child with complex type Iso to make the document valid Iso iso = country.addNewIso(); iso.setAlpha2("DK"); iso.setAlpha3("DNK"); iso.setCountryCode(208); // print out country XMLBean as XML System.out.println(country.xmlText()); // check if document is valid - will print "Document is valid" System.out.println ("Document is " + (country.validate() ? "valid" : "invalid")); } }

3. History

David Bau was the chief designer for the XMLBeans 1.0 project while he was working for BEA. XMLBeans started on the grounds of XMLMaps, an XML binding tool included in previous BEA WebLogic products. XMLBeans was originally developed as part of the proprietary BEA WebLogic Workshop Framework, but it was obvious from interviews conducted when it was first announced on January 27, 2003, that BEA wanted it to become an open standard. At that time it was not decided which organization BEA wanted to involve in the standardization effort. Later that year it was donated to the Apache Software Foundation. The original team included Cezar Cristian Andrei and Eric Vasilik, later the team added Cliff Schmidt and Radu Preotiuc-Pietro, Jacob Danner, Kevin Krouse and Wing Yew Poon. XMLBeans is now being developed by Apache POI.

• January 27, 2003: BEA announces XMLBeans as a technology preview.
• September 24, 2003: BEA donates XMLBeans to the Apache Software Foundation where it joins the Apache Incubator Project.
• April 23, 2004: XMLBeans Version 1.0.2 is released. This is the first release from the incubator project.
• June 25, 2004: XMLBeans graduated out of the Apache Incubator Project to become top level project.
• June 30, 2005: XMLBeans Version 2.0 is released.
• November 16, 2005: XMLBeans Version 2.1 is released.
• June 23, 2006: XMLBeans Version 2.2 is released.
• June 1, 2007: XMLBeans Version 2.3 is released.
• July 8, 2008: XMLBeans Version 2.4 is released.
• December 14, 2009: XMLBeans Version 2.5 is released.
• August 14, 2012: XMLBeans Version 2.6 is released.
• May 23, 2014: XMLBeans was officially retired and active development was ceased temporarily.
• June 29, 2018: XMLBeans was "unretired" and Apache POI took over active development.^[1]