Using JAXB

You will find the following topics covered in this article:

Java developers can invoke a SAX or DOM parser in an application through the JAXP API to parse an XML document -- that is, scan the document and logically break it up into discrete pieces. The parsed content is then made available to the application. In the SAX approach, the parser starts at the beginning of the document and passes each piece of the document to the application in the sequence it finds it. Nothing is saved in memory. The application can take action on the data as it gets it from the parser, but it can't do any in-memory manipulation of the data. For example, it can't update the data in memory and return the updated data to the XML file.

In the DOM approach, the parser creates a tree of objects that represents the content and organization of data in the document. In this case, the tree exists in memory. The application can then navigate through the tree to access the data it needs, and if appropriate, manipulate it.

Now developers have another Java API at their disposal that can make it easier to access XML documents: Java Architecture for XML Binding (JAXB). A Reference Implementation of the API is now available in the Java Web Services Developer Pack V 1.1.

Let's look at JAXB in action, and compare it to SAX and DOM-based processing.

An Example: Accessing an XML Document

Suppose you need to develop a Java application that accesses and displays data in XML documents such as books.xml. These documents contain data about books, such as book name, author, description, and ISBN identification number. You could use the SAX or DOM approach to access an XML document and then display the data. For example, suppose you took the SAX approach. In that case, you would need to:

• Write a program that creates a SAX parser and then uses that parser to parse the XML document. The SAX parser starts at the beginning of the document. When it encounters something significant (in SAX terms, an "event") such as the start of an XML tag, or the text inside of a tag, it makes that data available to the calling application.
• Create a content handler that defines the methods to be notified by the parser when it encounters an event. These methods, known as callback methods, take the appropriate action on the data they receive.

After unmarshalling, your program can access and display the data in the XML document simply by accessing the data in the Java content objects and then displaying it. There is no need to create and use a parser and no need to write a content handler with callback methods. What this means is that developers can access and process XML data without having to know XML or XML processing.

Bind the Schema

Binding an XML Schema

JAXB simplifies access to an XML document from a Java program by presenting the XML document to the program in a Java format. The first step in this process is to bind the schema for the XML document into a set of Java classes that represents the schema.

Schema: A schema is an XML specification that governs the allowable components of an XML document and the relationships between the components. For example, a schema identifies the elements that can appear in an XML document, in what order they must appear, what attributes they can have, and which elements are subordinate (that is, are child elements) to other elements. An XML document does not have to have a schema, but if it does, it must conform to that schema to be a valid XML document. JAXB requires that the XML document you want to access has a schema, and that schema is written in the W3C XML Schema Language (see the box "Why W3C XML Schema Language?").

Assume, for this example, that the books.xml document has a schema, books.xsd, that is written in the W3C XML Schema Language. This schema defines a <Collection> as an element that has a complex type. This means that it has child elements, in this case, <book> elements. Each <book> element also has a complex type named bookType. The <book> element has child elements such as <name>, <ISBN>, and <author>. Some of these have their own child elements.

Binding: Binding a schema means generating a set of Java classes that represents the schema. All JAXB implementations provide a tool called a binding compiler to bind a schema (the way the binding compiler is invoked can be implementation-specific). For example, the JAXB Reference Implementation provides a binding compiler that you can invoke through scripts. Suppose, for example, you want to bind the books.xsd schema using the binding compiler provided by the JAXB Reference Implementation. Suppose too that you're working in the Solaris Operating Environment. Here's a command you can use to run the script that binds the schema:

xjc.sh -p test.jaxb books.xsd -d work

The -p option identifies a package for the generated classes, and the -d option identifies a target directory. So for this command, the classes are packaged in test.jaxb within the work directory.

In response, the binding compiler generates a set of interfaces and a set of classes that implement the interfaces. Here are the interfaces it generates for the books.xsd schema:

• CollectionType.java Represents the unnamed complex type for the <Collection> element.
• Collection.java. Represents the <Collection> element.
• BookType.java. Represents the BookType complex type.
• ObjectFactory.java. Contains methods for generating instances of the interfaces.

Here are the classes that implement the interfaces (these are generated in an impl subdirectory). Note that these classes are implementation-specific -- in this example, they are specific to the Reference Implementation. Because the classes are implementation-specific, classes generated by the binding compiler in one JAXB implementation will probably not work with another JAXB implementation. So if you change to another JAXB implementation, you should rebind the schema with the binding compiler provided by that implementation.

• impl/CollectionTypeImpl.java. Implements the CollectionType interface described in CollectionType.java.
• impl/CollectionImpl.java . Implements the Collection interface described in Collection.java.
• impl/BookTypeImpl.java. Implements the BookType interface described in BookType.java.

In total, the generated classes represent the entire books.xsd schema. Notice that the classes define get and setmethods that are used to respectively obtain and specify data for each type of element and attribute in the schema.

You then compile the generated interfaces and classes. For example:

javac test/jaxb/*.java test/jaxb/impl/*.java

This compiles all of the interfaces and classes in the test.jaxb package generated by the binding compiler.

Unmarshal the Document

Unmarshalling

Unmarshalling an XML document means creating a tree of content objects that represents the content and organization of the document. The content tree is not a DOM-based tree. In fact, content trees produced through JAXB can be more efficient in terms of memory use than DOM-based trees.

The content objects are instances of the classes produced by the binding compiler. In addition to providing a binding compiler, a JAXB implementation must provide runtime APIs for JAXB-related operations such as marshalling. The APIs are provided as part of a binding framework. The binding framework comprises three packages. The primary package, javax.xml.bind, contains classes and interfaces for performing operations such as unmarshalling, marshalling, and validation (marshalling and validation will be covered later). A second package, javax.xml.bind.util, contains a number of utility classes. The third package, javax.xml.bind.helper, is designed for JAXB implementation providers.

To unmarshal an XML document, you:

• Create a JAXBContext object. This object provides the entry point to the JAXB API. When you create the object, you need to specify a context path. This is a list of one or more package names that contain interfaces generated by the binding compiler. By allowing multiple package names in the context path, JAXB allows you to unmarshal a combination of XML data elements that correspond to different schemas.

  For example, the following code snippet creates a JAXBContext object whose context path is test.jaxb, the package that contains the interfaces generated for the books.xsd schema:

  Copy

  
  
  import javax.xml.bind.JAXBContext;
  
  JAXBContext jc = JAXBContext.newInstance("test.jaxb");
  

• Create an Unmarshaller object. This object controls the process of unmarshalling. In particular, it contains methods that perform the actual unmarshalling operation. For example, the following code snippet creates an Unmarshaller object:
  Copy

  
  
  import javax.xml.bind.Unmarshaller;
  
  Unmarshaller unmarshaller = jc.createUnmarshaller();
  

• Call the unmarshal method. This method does the actual unmarshalling of the XML document. For example, the following statement unmarshals the XML data in the books.xml file:
  Copy

  
  
      Collection collection= (Collection)
      unmarshaller.unmarshal(new File( "books.xml"));
  

  Note that a Collection here is a test.jaxb.Collection, not a java.util.Collection.
• Use the get methods in the schema-derived classes to access the XML data. Recall that the classes that a JAXB compiler generates for a schema include get and set methods you can use to respectively obtain and specify data for each type of element and attribute in the schema. For example, the following statement gets the data in the books and book elements:
  Copy

  
  
  CollectionType.BooksType booksType = collection.getBooks();
  List bookList = booksType.getBook();
  

After obtaining the data, you can display it directly from your program. Here, for example, is a program that unmarshals the data in the books.xml file and then displays the data. If you run the program, you should see the following result:

Book  details 
Item id: 999
Book Name: Learning JAXB
Book ISBN: 123445
Book Price: 34 $
Book category: other
Book promotion: 10% on this book if purchased by March 2003
No of Authors 1
Author Name Jane Doe

Book  details 
Item id: 129
Book Name: Java Webservices today and Beyond
Book ISBN: 522965
Book Price: 29 $
Book category: magazine
Book promotion: Buy one get Learning webservices Part 1 free
No of Authors 2
Author Name John Brown
Author Name Peter T.

Validating the Source Data: Notice that the program includes the following statement:

unmarshaller.setValidating(true);

You also have the flexibility of turning the validation switch off if you don't want to incur the additional validation processing overhead.

Unmarshalling Other Sources: Although the example described in this section shows how to unmarshal XML data in a file, you can unmarshal XML data from other input sources such as an InputStream object, a URL, or a DOM node. You can even unmarshal transformed XML data. For example, you can unmarshal a javax.xml.transform.sax.SAXSource object. You can also unmarshal SAX events -- in other words, you can do a SAX parse of a document and then pass the events to JAXB for unmarshalling.

An Alternative: Accessing Data without Unmarshalling: JAXB also allows you to access XML data without having to unmarshal it. One of the classes generated from a schema, ObjectFactory, contains methods to generate objects for each of the schema-derived interfaces and classes. For example, the package generated for the books.xsd schema includes an ObjectFactory class that has methods such as createCollection to create a Collection object, and createBookType to create a BookType object. You can use these methods to create a tree of content objects without doing any unmarshalling. All your program needs is access to the ObjectFactory class that's in the package for the pertinent schema. Then you can use the appropriate methods in the ObjectFactory class to create the objects you need. After you create the objects, you need to provide their content. To do that, you use the set methods in the objects.

Another Example: Building an XML Document

Instead of accessing data in an XML document, suppose you need to build an XML document through a Java application. Here too using JAXB is easier. Let's investigate.

You could use the DOM approach to build an XML document, but not SAX. That's because you would need to build and populate the content of the document in memory -- recall that SAX does not allow you to perform any in-memory manipulation of data. Using the DOM approach, your program needs to create and use DOM objects and methods to build the document. DOM is designed to represent the content and organization of data in a document as a tree of objects. To build the document, your program uses DOM to create a Document object that represents the document. Your program then uses Document object methods to create other objects that represent the nodes of the tree. Each node contains content for the XML document. You then append the nodes in an order that reflects the organization of the tree. In other words, your program uses DOM object methods to create a root node, and append the root node to the Document object. Then it creates child nodes and appends them to the root node. If a child node has children of its own, your program uses DOM object methods to create those nodes and append them to their parent node.

Unlike the SAX approach, there is no need in DOM to write a content handler and callback methods. However the DOM approach requires you to understand the organization of the document tree. In fact, if you use DOM to access data, you create a parser that builds a tree, and then you use DOM methods to navigate to the appropriate object in the tree that contains the data you need. So an understanding of the tree's organization is a requirement. Compare this to JAXB, where you have direct access to unmarshalled XML data through objects in the content tree. As in DOM-based processing, JAXB allows access to data in non-sequential order, but it doesn't force an application to navigate through a tree to access the data. In addition, with all the creating and appending of objects that represent the nodes of the tree, the DOM approach can be tedious.

• Bind the schema for the XML document (if it isn't already bound).
• Create the content tree.
• Marshal the content tree into the XML document.

In this process, you don't deal with the intricacies of the DOM object model or even need to know XML.

Bind the Schema

This is the same operation you perform prior to unmarshalling a document. In this case, the schema is for the XML document you want to build. Of course, if you've already bound the schema (for instance, you unmarshalled an XML document, updated the data, and now want to write the updated data back to the XML document), you don't have to bind the schema again.

Create the Content Tree

The content tree represents the content that you want to build into the XML document. You can create the content tree by unmarshalling XML data, or you can create it using the ObjectFactory class that's generated by binding the appropriate schema. Let's use the ObjectFactory approach. First, create an instance of the ObjectFactory class:

ObjectFactory objFactory = new ObjectFactory();

Next, use create methods in the ObjectFactory object to create each of the objects in the content tree. For example:

Collection collection= 
   (Collection) objFactory.createCollection();
Collection.BooksType booksType = objFactory.
   createCollectionTypeBooksType();
BookType book = objFactory.createBookType();   

Then use set methods in the created objects to specify data values. For example:

book.setItemId("307");
book.setName("JAXB today and beyond"); 

Marshal the Content Tree

Marshalling

Marshalling is the opposite of unmarshalling. It creates an XML document from a content tree. To marshal a content tree, you:

• Create a JAXBContext object, and specify the appropriate context path -- that is, the package that contains the classes and interfaces for the bound schema. As is the case for unmarshalling, you can specify multiple package names in the context path. That gives you a way of building an XML document using a combination of XML data elements that correspond to different schemas.

  
  
  import javax.xml.bind.JAXBContext;
  
  JAXBContext jaxbContext = JAXBContext.newInstance("test.jaxb");
  

• Create a Marshaller object. This object controls the process of marshalling. In particular, it contains methods that perform the actual marshalling operation.

  
  
  import javax.xml.bind.Marshaller;
  
  Marshaller marshaller = jaxbContext.createMarshaller();
  
  

  The Marshaller object has properties that you can set through the setProperty method. For example, you can specify the output encoding to be used when marshalling the XML data. Or you can tell the Marshaller to format the resulting XML data with line breaks and indentation. The following statement turns this output format property on -- line breaks and indentation will appear in the output format:

  
  
  marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT,
     new Boolean(true));
  

• Call the marshal method. This method does the actual marshalling of the content tree. When you call the method, you specify an object that contains the root of the content tree, and the output target. For example, the following statement marshals the content tree whose root is in the collection object and writes it as an output stream to the XML file jaxbOutput.xml:

  
  
  marshaller.marshal(collection,
     new FileOutputStream("jaxbOutput.xml"));
  

Here, for example, is a program that creates a content tree, fills it with data, and then marshals the content tree to an XML file.

Validating the Content Tree: Notice that validation is not performed as part of the marshalling operation. In other words, unlike the case for unmarshalling, there is no setValidating method for marshalling. Instead, when marshalling data, you use the Validator class that is a part of the binding framework to validate a content tree against a schema. For example:

import javax.xml.bind.Validator;

Validator validator = jaxbContext.createValidator();
validator.validate(collection));

Validating the data as a separate operation from marshalling gives you a lot of flexibility. For example, you can do the validating at one point in time, and do the marshalling at another time. Or you can do some additional processing in between the two operations. Note that the JAXB specification doesn't require a content tree to be valid before it's marshalled. That doesn't necessarily mean that a JAXB implementation will allow invalid data to be marshalled -- it might marshal part or all of the invalid data, or not. But all JAXB implementations must be able to marshal valid data.

Marshalling to Other Targets: Although the example described in this section shows how to marshal data to an XML file, you can marshal to other output formats such as an OutputStream object or a DOM node. You can also marshal to a transformed data format such as javax.xml.transform.SAXResult. You can even marshal to a content handler. This allows you to process the data as SAX events.

A Final Example: Updating an XML Document

Here's a final example, one that logically combines elements of accessing an XML document and building an XML document. Suppose you need to update an XML document. In the DOM approach, you would create and use a DOM parser to navigate to the appropriate object in the tree that contains the data you need, update the data, and then write the updated data to an XML file. Here, for example, is a program that uses DOM to update an XML document. As discussed in Building an XML Document, the DOM approach is relatively tedious and forces you to know the organization of the content tree.

Here, by comparison, is a JAXB program that updates an XML document. Specifically, it updates an unmarshalled content tree and then marshals it back to an XML document. Notice how JAXB simplifies the process. The program has direct access to the object it needs to update. The program uses a get method to access the data it needs, and a set method to update the data.

Although it's tempting to think that the XML data can make a "roundtrip" unchanged, there's no guarantee of that. In other words, if you use JAXB to unmarshal an XML document and then marshal it back to the same XML file, there's no guarantee that the XML document will look exactly the same at it did originally. For example, the indentation of the resulting XML document might be a bit different than the original. The JAXB specification does not require the preservation of the XML information set in a roundtrip from XML document-to-Java representation-to XML document. But it also doesn't forbid the preserving of it.

Let's look at a customization example. Here is an annotated version of the books.xsd schema that was used in the previous examples. The annotations in this example are inline.

Notice the annotation element near the top of the schema:

<xs:annotation>
   <xs:appinfo>
      <jaxb:globalBindings generateIsSetMethod="true">

      bindingStyle="modelGroupBinding"
         choiceContentProperty="true" >
         
           <xjc:serializable uid="12343"/>
           <jaxb:javaType name="short" 
              xmlType="xs:long" 
              printMethod="javax.xml.bind.DatatypeConverter.printShort"   
              parseMethod="javax.xml.bind.DatatypeConverter.parseShort"/>

      </jaxb:globalBindings>
   </xs:appinfo>
</xs:annotation>

All binding declarations are in an annotation element and its subordinate appinfo element. In fact, all inline binding declarations must be made this way.

This block of code demonstrates a number of customizations that you can make to a schema:

Make global customizations: The <jaxb:globalBindings ...> element specifies binding declarations that have global scope. In JAXB, binding declarations can be specified at different levels, or "scopes." Each scope inherits from the scopes above it, and binding declarations in a scope override binding declarations in scopes above it. Global scope is at the top of the scope hierarchy. It covers all the schema elements in the source schema and (recursively) any schemas that are included or imported by the source schema. Global scope is followed in the hierarchy by Schema scope (covers all the schema elements in the target namespace of a schema), Definition scope (covers all schema elements that reference a specified type definition or a global declaration), and Component scope (applies only to a specific schema element that was annotated with a binding declaration).

Notice that the namespace prefix ( jaxb) for the <globalBindings> element is bound to http://www.oracle.com/webfolder/technetwork/jsc/xml/ns/jaxb/index.html. This URI contains the core schema for binding declarations.

Add method signatures. The declaration generateIsSetMethod="true" tells the binding compiler to generate isSet methods for the properties of all generated classes. These methods are used to determine if a property in a class is set or has a default value.

Change binding style. By default, schema components that have complex types and that have a content type property of mixed or element-only are bound with a style called element binding. In element binding, each element in the complex type is mapped to a unique content property. Alternatively, you can change the binding style to model group binding by specifying bindingStyle="modelGroupBinding" choiceContentProperty="true". In model group binding, schema components that have complex type and that are nested in the schema are mapped to Java interfaces. This gives users a way to specifically customize these nested components. For example, the following component is nested in the customized schema:

<xs:element name="promotion">

       <xs:complexType>
         <xs:choice>
           <xs:element name="Discount" type="xs:string" />
           <xs:element name="None" type="xs:string"/>

         </xs:choice>
       </xs:complexType>
    </xs:element>

As result of the global declarations made earlier, the binding compiler will generate the following methods for the elements tagged as choice:

java.lang.Object getDiscountOrNone();
void setDiscountOrNone(java.lang.Object value);
boolean is SetDiscountOrNone();

Include vendor-specific extensions. The declaration <xjc:serializable uid="12343"/> is an extension binding declaration. The xjc prefix binds to a namespace for extension binding declarations. These declarations are vendor-specific extensions to the binding declarations defined in http://www.oracle.com/webfolder/technetwork/jsc/xml/ns/jaxb/index.html. Here, the vendor-specific declaration covers the binding of classes that implement java.io.Serializable. The serial version uid 12343 will be assigned to each generated class.

Customize the binding of a simple data type. The declaration <jaxb:javaType name="short" xmlType="xs:long" binds the XML datatype xs:long to the Java data type short. This overrides the default binding behavior, which is to bind xs:long to the Java primitive data type long. The additional declaration printMethod="javax.xml.bind.DatatypeConverter.parseShort" tells the binding compiler to use the DatatypeConverter.parseShort method in JAXB's javax.xml.bind package to convert a lexical representation of the XML data type into the Java data type. The parse method is invoked by the JAXB provider's implementation during unmarshalling. The additional declaration printMethod="javax.xml.bind.DatatypeConverter.printShort" tells the binding compiler to use the DatatypeConverter.printShort method in JAXB's javax.xml.bin package to convert the Java data type into a lexical representation of the XML data type. The print method is invoked by the JAXB provider's implementation during marshalling.

Additional customizations: Other annotations in the schema illustrate additional types of customization, such as annotating a specific schema element to a Java Content Interface or Java Element Interface. This is done through a <class> binding declaration. In the annotated schema example, a <class> binding declaration is used to specify the name MyCollection for the interface bound to the <Collection> class. Another binding declaration in the annotated schema example binds the <bookCategory> element to its Java representation as a typesafe enumeration class. Although not illustrated in the annotated schema, another type of customization you can make is to specify javadoc for a generated package or class. These are only some of the many binding customizations that JAXB allows.

You can see the impact of the binding declarations by binding the annotated schema. When you do the binding, specify the -extension option, as in the following command:

xjc.sh -extension -p cust books_customization.xsd

The -extension option allows you to use vendor-provided extensions. You need this to enable the extension binding declaration in the schema. If you don't specify the -extension option, the binding compiler will run in "strict" mode. In this mode, it allows only for default bindings, and will produce an error message when it comes to the extension binding declaration.

After you run the program, examine the interfaces and classes that the binding compiler generates, and compare them to the interfaces and classes generated from the uncustomized schema. For example, here is the CollectionType.java file generated for the unnamed complex type for the <Collection> element. Notice the additional methods that have been added because of the binding customizations.

Distinct Advantages

Let's reiterate a number of important advantages of using JAXB:

• JAXB simplifies access to an XML document from a Java program:
• .
  • JAXB allows you to access and process XML data without having to know XML or XML processing. Unlike SAX-based processing, there's no need to create a SAX parser or write callback methods.
  • JAXB allows you to access data in non-sequential order, but unlike DOM-based processing, it doesn't force you to navigate through a tree to access the data.
  • By unmarshalling XML data through JAXB, Java content objects that represent the content and organization of the data are directly available to your program.
• JAXB uses memory efficiently: The tree of content objects produced through JAXB tends can be more efficient in terms of memory use than DOM-based trees.
• JAXB is flexible:
  • You can unmarshal XML data from a variety of input sources, including a file, an InputStream object, a URL, a DOM node, or a transformed source object.
  • You can marshal a content tree to a variety of output targets, including an XML file, an OutputStream object, a DOM node, or a transformed data object
  • You can unmarshal SAX events -- for example, you can do a SAX parse of a document and then pass the events to JAXB for unmarshalling.
  • JAXB allows you to access XML data without having to unmarshal it. Once a schema is bound you can use the ObjectFactory methods to create the objects and then use set methods in the generated objects to create content.
  • You can validate source data against an associated schema as part of the unmarshalling operation, but you can turn validation off if you don't want to incur the additional validation overhead.
  • You can validate a content tree, using the Validator class, separately from marshalling. For example, you can do the validating at one point in time, and do the marshalling at another time.
• JAXB's binding behavior can be customized in a variety of ways.

Java developers should find JAXB a welcome aid in developing Web services and other Java-XML applications.

Run the Examples

If you'd like to run the examples in this article with Java Web Services Developer Pack V 1.1, you need to:

1. Install Java Web Services Developer Pack V 1.1 (if you haven't already done so).
2. Set the JWSDP_HOME environment variable to the Java Web Services Developer Pack V 1.1 installation directory. For example, if you're using the C shell in the Solaris Operating Environment, enter the command:

   setenv JWSDP_HOME install_dir

   replace install_dir with the Java Web Services Developer Pack V 1.1 installation directory.

3. Set the class paths for JAXB, JAXP, and Java Web Services Developer Pack V 1.1. For example, if you're using the C shell in the Solaris Operating Environment, enter the commands:
   Copy

   
   
   setenv jaxb_lib $JWSDP_HOME/jaxb-1.0/lib
   setenv jaxp_lib $JWSDP_HOME/jaxp-1.2.2/lib/endorsed
   setenv jwsdp_lib $JWSDP_HOME/jwsdp-shared/lib
   

   and on one line:

   Copy

   
   
   setenv CLASSPATH  $jwsdp_lib/jax-qname.jar:
   $jwsdp_lib/namespace.jar:$jaxb_lib/jaxb-api.jar:
   $jaxb_lib/jaxb-libs.jar:$jaxb_lib/jaxb-ri.jar:
   $jaxb_lib/jaxb-xjc.jar:
   $jaxp_lib/dom.jar:$jaxp_lib/sax.jar:
   $jaxp_lib/xalan.jar:$jaxp_lib/xercesImpl.jar:
   $jaxp_lib/xsltc.jar:$jaxp_lib/../jaxp-api.jar:
   .:classes:work
   

4. Set the path for JAXB. For example, if you're using the C shell in the Solaris Operating Environment, enter the command:

   setenv PATH $JWSDP_HOME/jaxb-1.0/bin:$PATH

For More Information

W3C XML Schema Language

About the Authors

Ed Ort is a Java staff member. He has written extensively about Java technology and Web services.

Bhakti Mehta is a Member of Technical Staff at Sun Microsystems Inc. She is in the Web Technologies and Standards Interoperability and Quality team, and has worked with JAXP, JAXB, JAXR and JAXM.