Evaluate Weigh the pros and cons of technologies, products and projects you are considering.

Web services with JAXB

In this tip, William Brogden discusses Sun's Java Architecture for XML Binding.

The idea that there should be a way to turn a Java object into an XML representation and back again to an object has been pursued by a number of people. As a result of all this developer activity many different approaches exist.

The formal definition of an API to "bind" Java objects to XML has been under development for some time. Due to all the competing ideas and parallel developments, such as the rise of SOAP and many different XML applications, the situation has been very confusing. Sun's "Java Architecture for XML Binding" version 1.0 as found in the "Java Web Services Developer Pack" had some problems with inconsistency between JAXB and SOAP object representation.

The latest Java Web Service Developer Pack, JWSDP 2.0, supposedly does away with inconsistencies and presents an "integrated stack" for Web services. The JAXB version 2.0 it includes uses a specification JSR-222, developed as a Java Community Process by an industry expert group. JWSDP 2.0 is now available for download, but many of the components, including JAXB, are labeled "EA" for early access. The developer pack contains 10 separate technology toolkits and numerous sample applications. Only a few of these toolkits are licensed as "redistributable" for commercial application and JAXB is not one of them. Therefore I decided to work with a JAXB version covered by an open source license.

The JAXB Reference Implementation Project and Project GlassFish

If you follow Java industry news, you know that Sun is wrestling with getting more code into "open source" release. A "reference implementation" of JAXB 2.0 is part of project GlassFish, which is building an open source Java EE Application Server. The JAXB version I downloaded from this project was just released in early May. The download included numerous samples, documentation and the source code. It is covered by Sun's "Common Development and Distribution License" version 1.0.

The intent of JAXB is to make it easy for developers to incorporate conversion of Java objects to and from an XML representation based on a schema that defines the data in the object. Since describing a Java object with a schema is a foreign concept to many Java programmers, myself included, JAXB contains a utility that can examine quite complex Java objects and create a schema file.

Automatic creation of a schema from a Java file

In order to test the automated creation of a schema from an existing Java class, I used a class representing the result of a phonetic word lookup operation. Objects of this class have two String variables named "word" and "domain" and a String array variable named "matching". Running the JAXB "SchemaGeneratorFacade" program with the Java source code for the class as input produced the following schema document:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="https://www.w3.org/2001/XMLSchema">
  <xs:complexType name="wordLookup">
      <xs:element name="word" type="xs:string" minOccurs="0"/>
      <xs:element name="domain" type="xs:string" minOccurs="0"/>
      <xs:element name="matching" type="xs:string" nillable="true" 
            maxOccurs="unbounded" minOccurs="0"/>

Note that the "minOccurs" attributes in the generated schema allow for instances without values for the three variables and for the "matching" array to have the value "null." Obviously the schema generator can't know what the programmer wants to require in a valid object. In this case I removed the minOccurs entry to use the default value of exactly 1 for the two String variables "word" and "domain."

Note that the schema does not attempt to represent the "matching" String array as a list, but as a String that may occur zero to any number of times. In modifying the schema for "matching" I removed the nillable attribute and set maxOccurs to 500. As we shall see, JAXB came up with an improvement to my class by changing the variable from a String array to a collection.

Generating Java classes from a schema

Next I tested the generation of Java classes from the schema as modified. In order to automate this process, the JAXB toolkit provides an Ant task. Ant is the build utility of choice for most Java open source projects. The XML Binding Compiler (XJC) read the schema as modified and produced Java code for a WordLookup class.

The generated WordLookup class code makes use of formal "annotations," a new feature in Java 1.5 which inserts extra metadata into source code and compiled classes. This data does not change the execution of the Java methods, instead it provides handlers for runtime libraries to extract information about the class. It is this information that JAXB uses to know how to construct an object from the XML representation.

The WordLookup class created from the schema used an ArrayList for the "matching" variable. Comments written into the code by JAXB explained the usage of the getMatching() method that gives access to the list of "matching" strings. All of the Java code written by JAXB included extensive comments, which was a big help.

Serializing a WordLookup object

Following example code provided in the JAXB distribution, I wrote a simple program to create an instance of WordLookup and serialize it to an output Stream. The following four lines of code are all that were required to write an XML document representing the WordLookup instance:

 JAXBContext jc = JAXBContext.newInstance( "com.wbrogden.phonetic" );
 Marshaller m = jc.createMarshaller();
 m.setProperty( Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE );
 m.marshal( wlinstance, out );

If you want to learn more about using JAXB to serialize Java objects, the open source JAXB Reference Implementation site contains tutorials articles and discussion groups.


Main JWSDP page at Sun. http://java.sun.com/webservices/jwsdp/

Home for GlassFish - the open source Java EE Application Server https://glassfish.dev.java.net

Home for the JAXB 2.0 Reference Implementation as an open source project. https://jaxb.dev.java.net/

Text of the Common Development and Distribution License (CDDL) Version 1.0.1 https://jwsdp.dev.java.net/CDDLv1.0.html

Java Community Process JSR 222 for JAXB http://www.jcp.org/en/jsr/detail?id=222

A guide to the use of Annnotations in Java 1.5 http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html

About the author

William Brogden is a developer who lives outside Austin, Texas. Although he has been working mainly with Java for the last ten years, he enjoys investigating new computer languages and XML applications.

Dig Deeper on Topics Archive

Start the conversation

Send me notifications when other members comment.

Please create a username to comment.