Generating a JAXB Annotated Domain Model from an XML Schema

Software Requirements

• Oracle TopLink 11g Preview OTN.

• Apache ANT 1.6 or higher.

• The existing customer model (JAXBGenerated.zip).

• The existing XML Schema (Customer.xsd).

• Sample XML Document (Customer-data.xml) that will be unmarshalled using the TopLink JAXB runtime.

The following conventions are used in this document:

• <DEMO_HOME> - the directory where this How-To document will be used.

• <ANT_HOME> - the directory where Apache ANT is installed..

Introduction

Generating a domain model from an XML Schema (XSD) is the quickest way to get started when you don't have an existing domain model and you need to work with XML. This how-to describes how the JAXB 2.0 schema compiler can be used to generate a Java POJO domain model from an XSD. The generated classes can be used in any Java application and can be marshalled to and from XML.   Any changes you make to the objects will be reflected in the XML when the objects are marshalled.

Comping a Schema

In this section you'll generate a Java domain model from an XSD.

Step 1: Setup

Unzip JAXBGenerated.zip into the <DEMO_HOME> folder of your choice.  After unzipping, <DEMO_HOME> will contain the folder JAXBGenerated.  <DEMO_HOME>/JAXBGenerated/build.xml is an ANT build file that can be used to build and run this how-to.  Open build.xml in a text editor and set the property "toplink.home" to reference your TopLink install.  It should look something like:

    <property name="toplink.home" value="C:\bin\Toplink11"/>

Defining the XJC ANT Task

The ANT build defines the "xjc" task which is used to compile a schema.  If you plan to use the schema compiler as part of your build process you must do the same:

    <taskdef name="xjc" classname="com.sun.tools.xjc.XJCTask">
   <classpath refid="classpath" />
    </taskdef>

Once you have the xjc task defined you can compile a schema using it:

    <target name="compile-schema">
        ...
        <xjc schema="schemas/Customer.xsd" package="examples.jaxb.generated" destdir="${srcdir}">
            <produces dir="${gendir}" includes="**/*.java" />
        </xjc>
    </target>

The nested <produces> element specifies what files should be examined when doing an up to date check to see if the schema needs to be recompiled.

Step 3: Compiling a Schema with ANT

With the toplink.home property set, you can use the ANT build.xml file to compile the Customer.xsd into a Java domain model.  To do so you need to invoke ANT with the "compile-schema" target.  From a command prompt, with your current directory <DEMO_HOME>/JAXBGenerated (the directory that contains build.xml), you can issue the command:

<ANT_HOME>/bin/ant  compile-schema

This will generate the following classes into <DEMO_HOME>JAXBGenerated/src/examples/jaxb/generated:

    AddressType.java
    CustomerType.java
    ObjectFactory.java
    package-info.java
    PhoneNumber.java


Step 4: Unmarshalling XML to Java

The class examples.jaxb.unmarshall.UnmarshallGenerated provides an example of how to convert XML in to Java Objects using the JAXB API.  The main() method includes:

        //create our context
        JAXBContext jaxbContext = JAXBContext.newInstance("examples.jaxb.generated");

        //create our unmarshaller
        Unmarshaller unmarshaller = jaxbContext.createUnmarshaller();
        //read
        CustomerType customer = (CustomerType)unmarshaller.unmarshal(new FileInputStream("documents/Customer-data.xml"));

This is the standard JAXB 2.0 API and the UnmarshallGenerated class does not use any TopLink specific methods or imports. To identify TopLink as the JAXB runtime that should be used to perform the unmarshalling the directory "examples.jaxb.generated" (which is the name of the package used to create the context) must contain a jaxb.properties file that defines the variable "javax.xml.bind.context.factory".  In the example the jaxb.properties file contains:

javax.xml.bind.context.factory=oracle.toplink.ox.jaxb20.JAXBContextFactory

Step 5: Marshalling Java to XML

Once you have a Java object, in this case a CustomerType object, you can marshall it in to XML.  The UnmarshallGenerated example shows how changes made to the object model are reflected in XML when the object model is marshalled.  The example changes the last name of the customer and then marshalls to XML output to the console.

        //change last name to show that there's 'nothing up my sleeve'
        customer.setLastName("Trevor");
        
        //create a marshaller to pretty print
        Marshaller marshaller = jaxbContext.createMarshaller();
        marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT,Boolean.TRUE);
        marshaller.marshal(customer, System.out);        

Summary

In this how-to we've seen how to compile an XML Schema into a Java domain model using ANT, how to unmarshall a document that conforms to the source schema into objects of the domain model, and how to marshall those objects back into XML.