XML Binding with JAXB 2.0 - Tutorial

Java Architecture for XML Binding (JAXB) is an API/framework that binds XML schema to Java representations. Java objects may then subsequently be used to marshal or unmarshal XML documents. Marshalling an XML document means creating an XML document from Java objects. Unmarshalling means creating creating a Java representation of an XML document (or, in effect, the reverse of marshaling). You retrieve the element and attribute values of the XML document from the Java representation.

The JAXB 2.0 specification is implemented in JWSDP 2.0. JAXB 2.0 has some new features, which facilitate the marshalling and unmarshalling of an XML document. JAXB 2.0 also allows you to map a Java object to an XML document or an XML Schema. Some of the new features in JAXB 2.0 include:

• Smaller runtime libraries are required for JAXB 2.0, which require lesser runtime memory.
• Significantly, fewer Java classes are generated from a schema, compared to JAXB 1.0. For each top-level complexType, 2.0 generates a value class instead of an interface and an implementation class. For each top-level element, 2.0 generates a Factory class method instead of an interface and an implementation class.
• Support for all of XML Schema constructs
• Added parameterized types
• The UnMarshaller interface method setValidating() has been deprecated and replaced with JAXP 1.3 validation.
• Support for binding Java-to-XML with the javax.xml.bind.annotation package.
  

Runtime Libraries

First, you'll need to download the Java Web Services Developer Pack 2.0, which includes an implementation of JAXB 2.0. Install JWSDP 2.0 in the C:\Sun\jwsdp-2.0, the default installation directory. JAXB 2.0 gets installed in the C:\Sun\jwsdp-2.0\jaxb directory. Add the C:\Sun\jwsdp-2.0\jaxb\bin directory to the PATH variable. Because JAXB 2.0 uses the JDK5.0 feature parameterized types, you'll need to also install JDK 5.0. Add the environment variables JAVA_HOME and JAXB_HOME. JAVA_HOME specifies the directory in which J2SE 5.0 is installed. JAXB_HOME specifies the directory in which JAXB 2.0 is installed. Table 1 lists the JAR files required for JAXB 2.0.

JAR File	Description
C:/Sun/jwsdp-2.0/jaxb/lib/jaxb-api.jar	JAXB 2.0 API classes
C:/Sun/jwsdp-2.0/jaxb/lib/jaxb-impl.jar	JAXB 2.0 implementation classes
C:/Sun/jwsdp-2.0/jaxb/lib/jaxb-xjc.jar	JAXB 2.0 Compiler classes
C:/Sun/jwsdp-2.0/jwsdp-shared/lib/activation.jar	javax.activation package classes.
C:/Sun/jwsdp-2.0/sjsxp/lib/jsr173_api.jar	StAX API classes
C:/Sun/jwsdp-2.0/sjsxp/lib/sjsxp.jar	StAX classes

Table 1. JAXB 2.0 JAR Files
In comparison, the JAXB 1.0 libraries are listed below:

 <JWSDP1.6>/jaxb/lib/jaxb-api.jar  <JWSDP1.6>/jaxb/lib/jaxb-impl.jar <JWSDP1.6>/jaxb/lib/jaxb-libs.jar  <JWSDP1.6>/jaxb/lib/jaxb-xjc.jar  <JWSDP1.6>/jwsdp-shared/lib/namespace.jar  <JWSDP1.6>/jwsdp-shared/lib/jax-qname.jar <JWSDP1.6>/jwsdp-shared/lib/relaxngDatatype.jar 

Compiling an XML Schema

Listing 1 shows an example XML schema that is compiled using the JAXB 2.0 schema binding compiler .xjc.
The schema binding compiler is used to generate Java classes from an XML schema. Run the schema binding compiler with the following command.

 >xjc catalog.xsd 

This generates Java classes in the generated package:

 parsing a schema... compiling a schema... generated\ArticleType.java generated\CatalogType.java generated\JournalType.java generated\ObjectFactory.java 

As you can see, fewer Java classes are generated. JAXB 2.0 generates a Java value class that corresponds to each top-level complexType. For example, for catalogType, 2.0 generates the Java value class CatalogType.java. CatalogType.java consists of getter and setter methods for each of the elements and attributes in the complexType. As the catalog element may have more than one journal element, the return type of getJournal() mehod is java.util.List<JournalType>.
Similarly, 2.0 generates the Java value class ArticleType.java, which corresponds to complexType articleType. It also generates JournalType.java, which further corresponds to complexType journalType. Also generated is the ObjectFactory.java class, consisting of create methods which create Java value class objects for ArticleType.java, CatalogType.java, and JournalType.java. The factory class also contains a create method corresponding to each of the top-level elements.
In contrast, JAXB 1.0 generates an interface and an implementation class for each complexType and top-level element. When the XML schema compiled in Listing 1 is compiled by JAXB 1.0, it generates all the classes shown in Listing 2—significantly more than what is generated by JAXB 2.0.

Support for All XML Schema Constructs

JAXB 1.0 does not support key XML Schema components like any, anyAttribute, key, keyref, and unique. It also does not support attributes like complexType.abstract, element.abstract, element.substitutionGroup, xsi:type, complexType.block, complexType.final, element.block, element.final, schema.blockDefault, and schema.finalDefault. In version 2.0, support has been added for all of these schema constructs.
To see how it works, first define an XML document consisting of the xs:any and xs:anyAttribute schema constructs:

 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">  <xsd:element name="catalog" type="catalogType"/>   <xsd:complexType name="catalogType">   <xsd:sequence>    <xsd:any/>   </xsd:sequence>   <xsd:attribute name="journal" type="xsd:string"/>   <xsd:attribute name="publisher" type="xsd:string"/>   <xsd:anyAttribute/>  </xsd:complexType>  </xsd:schema> 

Next, compile the XML document using schema compiler xjc:

 >xjc catalog.xsd 

The output from the schema compilation is shown below:

 parsing a schema... compiling a schema... generated\CatalogType.java generated\ObjectFactory.java 

In the schema-derived class CatalogType.java, the xs:any element is mapped with the @XmlAnyElement annotation and the xs:anyAttribute is mapped with the @XmlAnyAttribute annotation. JAXB 2.0 provides support for all the XML schema constructs in the schema, allowing you to a wider range of schemas and documents.

Parameterized Types

You'll need the JDK 5.0 to work with parameterized types. With parametrized types, casts are not required and type checking is performed at compile time. Using casts (as in JAXB 1.0) runs the risk of incurring a runtime exception if an object is cast to a type of which is not an instance.
In marshalling an example document that conforms to the example XML Schema in Listing 1, the procedure to add a journal element to a catalog element with JAXB 1.0 is shown below:

 ObjectFactory factory=new ObjectFactory();  Catalog catalog=factory.createCatalog(); Journal journal=factory.createJournal(); java.util.List journalList=catalog.getJournal(); journalList.add(journal);  

The type of journalList List is determined at run-time. In JAXB 2.0, collection types are specified in the class and are checked at compile-time. So, the procedure to add a journal element to a catalog element with JAXB 2.0 looks like this:

 ObjectFactory factory = new ObjectFactory(); CatalogType catalog = factory.createCatalogType(); JournalType journal = factory.createJournalType(); List<JournalType> journalList = catalog.getJournal(); journalList.add(journal); 

The Collection journalList's type is specified with the parameterized types notation as JournalType.
In JAXB 1.0, a Java object representing an XML document may be marshaled using the marshal() method:

 JAXBContext jaxbContext=JAXBContext.newInstance("generated"); Marshaller marshaller=jaxbContext.createMarshaller(); Catalog catalog=factory.createCatalog(); marshaller.marshal(catalog, new FileOutputStream(xmlDocument)); 

In JAXB 2.0, you first obtain a JAXBElement object of parameter type CatalogType using the factory class method createCatalog(CatalogType). A JAXBElement object is a JAXB representation of an XML element. Subsequently, you marshal the parameterized JAXBElement with the marshal() method:

 JAXBElement<CatalogType&Gt; catalogElement=factory.createCatalog(catalog); marshaller.marshal(catalogElement, new FileOutputStream(xmlDocument)); 

In unmarshalling with JAXB 1.0, the Java object representation of an XML document is obtained with the unmarshal() method:

 Unmarshaller unMarshaller=jaxbContext.createUnmarshaller(); Catalog catalog=(Catalog)(unMarshaller.unmarshal(xmlDocument)); 

With JAXB 2.0, the unmarshal() method returns a parameterized JAXBElement object. In the example, the parameter type is CatalogType. Obtain a CatalogType object from the JAXBElement object using the getValue() method:

 Unmarshaller unMarshaller = jaxbContext.createUnmarshaller(); JAXBElement catalogElement =(JAXBElement) unMarshaller.unmarshal(xmlDocument); CatalogType catalog=catalogElement.getValue(); 

As you can see, the advantage of using parameterized types in JAXB 2.0 is that type checking is performed at compile time, which means that runtime exceptions won't be generated if type casting has an error.

Validation

Validation is the process of confirming that an XML document conforms to an XML Schema. JAXB 2.0 validation's additional features make it much more flexible than JAXB 1.0's. In JAXB 1.0 validation is available only during the unmarshalling operation, and it is terminated if an error is found. In JAXB 2.0, validation is also available during the marshalling operation, which continues even if a validation error occurs when a custom ValidationEventHandler is used.
In JAXB 1.0, validation is set with the setValidating() method:

 unMarshaller.setValidating(); 

In JAXB 2.0, the setValidating() method has been deprecated. Now, schema validation is performed using the JAXP 1.3 validation API. To validate using JAXB 2.0, create a SchemaFactory object using the static method newInstance(String). The String parameter of newInstance(String) method specifies the schema language used for schema validation. Create schema object from the SchemaFactory object using the method newSchema(File). The File parameter of the newSchema() method represents a File object representation of an XML document. A schema object may also be created from a DOMSource, SAXSource, StreamSource, or a URL object representation of an XML schema file. Set the schema on the Unmarshaller object using setSchema(Schema) method. A custom ValidationEventHandler may also be specified using the setEventHandler(ValidationEventHandler handler) method.

 SchemaFactory schemaFactory=SchemaFactory.newInstance ("http://www.w3.org/2001/XMLSchema");  Schema schema=schemaFactory.newSchema(new File("catalog.xsd"));  unMarshaller.setSchema(schema);

Mapping Java to XML Using Annotations
JAXB 2.0 also allows you to marshal a Java object to an XML document using annotations. You must be familiar with JDK 5.0 to use the annotations to generate an XML document. Table 2 shows some of the most commonly used annotations, as defined in the javax.xml.bind.annotation package. 

Annotation Type

Description

Annotation Elements


XmlValue

Maps a class to an XML Schema complex type with simpleContent or an XML Schema simple type. 

-


XmlType

Maps a class to an XML Schema type, which may be a simple type or a complex type. 

name-Name of XML Schema type

namespace-Target namespace of XML Schema type.

propOrder-Specifies order of XML schema elements when a class is mapped to a complex type.


XmlSchema

Maps a package name to a XML namespace. 

attributeFormDefault-Specifies value of attributeFormDefault attribute. 

elementFormDefault-Specifies value of attribute elementFormDefault.

namespace-XML namespace

xmlns-Maps namespace prefixes to namespace URIs.


XmlRootElement

Maps a class to root element.

name-Local name of root element.

namespace-Namespace of root element. 


XmlList

Maps a property to a list simple type. 

-


XmlEnum

Maps an enum to simple type with enumeration. 

value-Enumeration value


XmlElement

Maps a JavaBean property to an element.

defaultValue-Default value of element.

name-Element name

namespace-Target namespace of element.

nillable-Specifies if element is nillable. Default is false.

Type-Element type.


XmlAttribute

Maps a JavaBean property to an attribute. 

name-Attribute name.

namespace-Attribute namespace.

required-Specifies if attribute is required. Default is false. 


Table 2. Some of the most commonly used annotations. 
Creating an annotated class can be done in five steps: 
Create a simple class called Catalog.java.   
Import the javax.xml.bind.annotation package with its annotation types.   
Create the root element of an XML document with @XmlRootElement annotation.   
Create a complexType using @XmlType annotation.   
The Root element catalog has the attributes publisher, edition, and journal. Define the attributes using @XmlAttribute annotation.  
Listing 3 shows how to create an annotated class. 
As you can see, the annotation element name is specified as an empty string, because the complexType is defined within an element. The element order is specified using propOrder annotation element. 
The corresponding schema representation for example XML document is shown below: 
 <xs:element name="catalog"> <xs:complexType> <xs:sequence> <xs:element name="title" type="xs:string"/> <xs:element name="author" type="xs:string"/> </xs:sequence> <xs:attribute name="publisher" type="xs:string"/> <xs:attribute name="edition" type="xs:string"/> <xs:attribute name="journal" type="xs:string"/> </xs:complexType> </xs:element> 
JAXB 2.0 provides bi-directional mapping with which an annotated Java class may be mapped to an XML Schema using the Schema Generator. 
A Step in the Right Direction
JAXB 2.0's new features reduce the code generated from a schema with the schema binding compiler and make use of JDK 5.0 features such as annotations and parameterized types. With it's support for annotations, JAXB 2.0 provides bi-directional mapping between XML Schema and Java objects. Parameterized types provide compile-time type checking, which means that runtime exceptions do not get generated.