JAXB takes XML to Java

by David Morris

[The code for this article is available for download.]

Until recently, there was no standard way to convert XML content to Java objects. The recently released Java Architecture for XML Binding (JAXB) specification changes that by providing a standard API to map XML documents to Java objects. The JAXB 1.0 specification went through the Java Community Process as a Java Specification Request (JSR) and reached final release status on March 3. It provides a standard and efficient way of mapping between XML and Java objects.

The JAXB API provides an easy way for Java to work with XML documents. For example, you can read an XML document, build Java objects, change those objects, validate the changes against an XML schema, and write the changed objects back out as an XML document. Java code that uses the JAXB API is efficient and simpler to write than Java code that uses alternative APIs like JDOM or Java API for XML Parsing (JAXP).

During the development of the JAXB specification, Sun Microsystems periodically released reference implementations that let developers give feedback on the API while the JAXB specification was being written. This feedback improved the JAXB specification and enabled Sun to deliver a JAXB 1.0 reference implementation as soon as the JAXB specification was final. In this article I will walk you through the steps necessary to download, install, and use Sun's reference implementation on your iSeries system.

Coming to Terms

When I first started working with JAXB, I was thrown off by some of the technical jargon. For example, with JAXB, you don't load, read, or even import an XML document, you unmarshal a content tree. The following list of JAXB terms should help you get up to speed quickly:

• Binding Compiler--generates a set of Java classes that represent XML content described by an XML schema.
• Binding Declarations--special binding directives added to a source schema that override the default binding rules.
• Binding Framework--the runtime JAXB APIs used to create Java objects from XML content.
• Content Tree--a structured set of Java objects representing XML input.
• Marshal--the process of traversing a content tree of Java objects and writing that tree to an XML document.
• Schema--an XML specification that describes the form and content of XML documents.
• Unmarshal--the process of reading an XML document and creating a content tree of Java objects; the opposite of marshal.
• Validation--the process of applying schema rules against the content tree.

The terminology associated with JAXB helps to discern some of the subtle differences between JAXB and other Java related XML APIs, like JAXP. The terms unmarshal and marshal, in general, mean load and write XML documents to and from Java objects.

I have found that the JAXB specification is very flexible. It specifies a minimal level of support but doesn't impose specific implementations. It is likely that support will develop for alternative schemas like RELAX NG, which is simpler and more intuitive than the W3C XML Schema 1.0 Recommendation.

How JAXB Works

To use JAXB, you need a schema that describes the XML content you want to bind to Java. There are several types of schema, but Sun's JAXB 1.0 implementation only supports the W3C XML Schema 1.0 Recommendation. You can create a schema by hand or use tools to generate one from a DTD (document type definition) or an XML document. I use WebSphere Development Studio client (WDSc) to generate a base schema. WDSc is available at no additional cost to iSeries customers who have the WebSphere Development Studio package, which is the iSeries host package that includes the various compilers.

Figure 1 presents an overview of the JAXB generation and runtime process. You start with a schema that you feed to the JAXB binding compiler to generate Java source files that are compiled into Java classes. You use those classes in your applications to build a content tree containing Java objects that represent XML documents based on the original schema. You can change the content tree and add new objects; when you are done you can validate those changes to ensure the content tree conforms to the original schema. Finally, you write the content tree back out to an XML document.

Figure 1: Classes are generated from a schema and used to create objects

Installing JAXB

There are several ways to install JAXB on the iSeries, and the first decision you need to make is whether to install Sun's complete Java Web Services Developer Pack (JWSDP) or just JAXB. You will also want to install JAXB support on your PC if you use some sort of IDE like WDSc or Eclipse. The complete Java Web Services Developer Pack is huge and contains support for JAXB; Java API for XML Messaging (JAXM), Java API for XML Processing (JAXP), Java API for XML Registries (JAXR), Java API for XML-based RPC (JAX-RPC), SOAP with Attachments API for Java (SAAJ), JavaServer Pages Standard Tag Library (JSTL), Java WSDP Registry Server, and the Apache Software Foundation Ant build tool and Tomcat servlet engine.

If you are only interested in JAXB at this point, I would recommend that you only install the JAXB support on your iSeries. A complete installation of the Java Web Services Developer Pack consumes about 70 megabytes of disk space and took about 12 hours to compile on my low-end iSeries 270.

For either install option, start by going to Sun's Web Services download page and download the latest version of the Web Services Developer Pack. Next, install the complete Java Web Services Developer Pack on your PC.

If you have decided to install only JAXB, create a directory on your iSeries (I used /java/sun) and copy jaxb-1.0 and jwsdp-shared from the JWSDP install directory on your PC to this new directory. You can use the XML parsing support that comes with the Java Web Services Developer Pack, but I since I already had the Xerces parser installed, I used that instead. If you don't already have Xerces installed, see "Configuring Applications with XML" and review the Xerces installation instructions.

To install the complete Java Web Services Developer Pack, map a drive and copy the installation from your PC to your iSeries system.

If you can't map a drive, zip up the jwsdp-1.1 directory to a ZIP file named jwsdp-1.1.zip and use FTP to send that ZIP file to a temporary directory on your iSeries. Next, start Qshell (QSH) and run the following instructions:

mkdir /java/sun
cd /java/sun
jar -xf /tmp/jwsdp-1.1.zip

If you plan to generate your Java class files from a command line, you will have to edit the xjc.bat or xjc.sh file on the system to set the JAVA_HOME and JAXB_HOME environment variables that tell JAXB where the JDK and JAXB are located. In the Java Web Services Developer Pack, xjc.sh is in the jwsdp-1.1/jaxb-1.0/bin directory.

Setting up WDSc or Eclipse to work with JAXB

It is much easier to use an IDE like WDSc or Eclipse when developing Java applications. Later this month, IBM is releasing WDSc 5.0, which provides excellent support for both Java and XML development. In the meantime, you may want to use the latest version of Eclipse.

Start by creating a Java project called JAXB. Next, create a folder under that project named lib. Drag and drop the following JAXB and Xerces JAR files into this directory:

jaxb-api.jar
jaxb-libs.jar
jaxb-ri.jar
jaxb-xjc.jar
xercesImpl.jar
xmlParserAPIs.jar

If you have an older version of Xerces, you may find that xmlParserAPIs.jar was named xml-apis.jar. Either file should work fine for JAXB. The name was changed to differentiate between the xml-apis.jar file that is shipped with the Xalan XSLT project, which contains additional JAXP classes to support transformations.

Now right-click the JAXB project and click Refresh. Now set up the project class path. Right-click your JAXB project again and select Properties. Select Java Build Path and click the Libraries tab, followed by the Add Jars button. Expand your JAXB and lib folders in the next dialog, then select all the JAR files listed and click OK.

Next, set up a run target to generate JAXB classes. From the Run drop-down menu select Run, and right-click the Java Application launch configuration. Select New and enter JAXB Generation for the name, JAXB for the project, and LauncherBootstrap for the Main Class (see Figure 2).

Figure 2: Run the JAXB class generation from Eclipse

Now click the Arguments tab and specify -verbose xjc Employees.xsd -p org.iseriestoolkit.jaxb.demo, as shown in Figure 3. Specify your actual schema name, instead of Employee.xsd, and replace org.iseriestoolkit.jaxb.demo with the name of the package you want to use for the generated source.

Figure 3: Specify the schema and package names using the arguments dialog

Finally, click the classpath tab and uncheck the Use default class path option. Now click the Advanced button and select the Add external Folder radio button and click OK. Navigate to and select the jwsdp-1.1/jswsp-shared/bin directory and click OK. Your class path settings screen should look like that in Figure 4.

Figure 4: Use the classpath tab to set your generation classpath

Clicking the running man icon will run LauncherBootstrap. You can now use the run to generate your classes without further setup, other than to change your schema or package name on the Arguments tab.

Running JAXB

To demonstrate how to run JAXB, I created an Employees XML document and used WDSc to generate a simple schema. Here is what that XML document looked like:

<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
  <employee id="12345" name="Sponge Bob">
    <address>
      <street>1 Deep Street</street>
      <city>Bikini Bottom</city>
      <state>Hawaii</state>
      <postalCode>59937</postalCode>
    </address>
  </employee>
  <employee id="7777" name="Patrick Star"></employee>
</employees>

The generated schema I used looked like this:

<?xml version="1.0" encoding="ISO-8859-1"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <xsd:element name="address">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element ref="street"/>
        <xsd:element ref="city"/>
        <xsd:element ref="state"/>
        <xsd:element ref="postalCode"/>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="city" type="xsd:string"/>
  <xsd:element name="employee">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element maxOccurs="1" minOccurs="0" ref="address"/>
      </xsd:sequence>
      <xsd:attribute name="id" type="xsd:string" use="required"/>
      <xsd:attribute name="name" type="xsd:string" use="required"/>
   </xsd:complexType>
  </xsd:element>
  <xsd:element name="employees">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element maxOccurs="unbounded" minOccurs="1" ref="employee"/>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="postalCode" type="xsd:string"/>
  <xsd:element name="state" type="xsd:string"/>
  <xsd:element name="street" type="xsd:string"/>
</xsd:schema>

After generating the JAXB class files in WDSc from this schema, I used a simple Demoer program to try out the results. You can download the Demoer.java program, along with Employees.xml, Employees.xsd, and a shell script to run the Demoer. You can run the Demoer program in Eclipse and then upload it, along with the generated packages, to your iSeries system. After testing the Demoer in Eclipse, I exported the project to my iSeries system using a mapped drive.

Once I had the project on my iSeries system, I started Qshell (QSH) and ran the demoer.sh shell script. The first time I ran the shell script, the output reflected the initial Employees.xml file content. Running it a second time, I saw that my new employee Fred Flintstone had been added. The output of that run was the following:

ID: 12345
Name: Sponge Bob
Address: 1 Deep Street, Bikini Bottom, Hawaii 59937
ID: 7777
Name: Patrick Star
ID: 5758
Name: Fred Flintstone

After proving that JAXB does work on the iSeries, I did some profiling on my PC to see how fast JAXB ran and also how much memory it used compared with JDOM (for more information on running JDOM on the iSeries see "Configuring Applications with XML"). Overall, JDOM was about twice as fast as loading XML content to objects and it used about twice as much memory. Since memory use is generally a bigger problem than load speed, the tradeoff is reasonable.

While using JAXB is much simpler than JDOM, working with W3C schemas can be challenging. JAXB binding declarations, which are required to override XML names or to specify things like package name to the JAXB generator without command line switches, are also complex.

You might be thinking that you can get away without binding declarations, but you will inevitably run into an XML element or attribute name that is a Java reserved word or a situation where a schema defines elements and attribute names that collide. In these cases the only solution is to add inline JAXB binding declarations to your schema or to add a reference to an external binding declaration file using the -b option during generation.

Binding Arbitration

The long-awaited release of JAXB gives developers a standard way of converting XML documents to Java objects and back to XML. Once you have JAXB set up on your development workstation and iSeries, there is no easier way to read, write, and manipulate XML documents from Java. Overall, JAXB is very flexible and reasonably fast. In my limited tests, JAXB was a little slower but used about half the memory of comparable operations using JDOM, which is a reasonable trade off.

JAXB is relatively new, but I expect that it will be adopted rapidly once developers become familiar with its capabilities and see how easy it is to use. The JAXB specification leaves a lot of implementation details open, and I expect that there will be a lot effort directed toward making JAXB even faster and to simplify its use through support of more intuitive schema dialects like RELAX-NG.

David Morris is a software architect at Plum Creek Timber Company and started the iSeries-toolkit open-source project. E-mail: dmorris@itjungle.com.

Sponsored By T.L. ASHFORD

BARCODE400 by T.L. Ashford is the easiest and fastest way to create and print Compliance Labels directly from the AS/400 and iSeries. Ashford's comprehensive library of Compliance formats is available to Barcode400 users. AIAG labels for Ford and Motorcraft, GM, and many more are available. BARCODE400 is backed by the best Technical Support Team in the industry. FREE Guide to Bar Code Labeling www.tlashford.com or call 800.541.4893