You are here: SCDJWS » JAXB


SCDJWS Study Guide: JAXB


Printer-friendly version Printer-friendly version | Send this article to a friend Mail this to a friend

Previous Next vertical dots separating previous/next from contents/index/pdf Contents

A Sample with  JAXB Binding Compiler XJC


This sample application demonstrates how to construct value classes and create a java content tree from scratch and marshal it to XML data step by step.
The new version for JWSDP 2.0 can be found here.

System Requests


  • Download and install the Java Web Services Developer Pack (Java WSDP) currently at version 1.5 from Sun Microsystem. The Java WSDP is a free, integrated toolkit that allows Java developers to build, test, and deploy XML applications, Web services, and Web applications. Assume that you install JWSDP to C:\jwsdp-1.5 directory.
  • Create a C:\jaxb_samples directory on your machine.
  • For occasional developers, it is convenient to set these variables in a batch file that you run every time you open a command-prompt window. Alternatively, these settings can be permanently added to the command-prompt shortcut. Here is what you should add to a “jaxbsetup.bat” file in C:\jaxb_samples directory (note that only “set” commands are in this listing, any line that doesn’t start with “set” is a continuation of the previous line):

    set JWSDP_HOME=C:\jwsdp-1.5
    set JWSDP_JAXB_LIB=%JWSDP_HOME%\jaxb\lib
    set JWSDP_SHARED_LIB=%JWSDP_HOME%\jwsdp-shared\lib

    set CLASSPATH=%JWSDP_JAXB_LIB%\jaxb-api.jar;%JWSDP_JAXB_LIB%\jaxb-impl.jar;
    %JWSDP_JAXB_LIB%\jaxb-libs.jar; %JWSDP_JAXB_LIB%\jaxb-xjc.jar;%CLASSPATH%
    set CLASSPATH=%JWSDP_SHARED_LIB%\namespace.jar;%JWSDP_SHARED_LIB%\jax-qname.jar;
    %JWSDP_SHARED_LIB%\relaxngDatatype.jar;%CLASSPATH%
    set PATH=%JWSDP_HOME%\jaxb\bin;%JWSDP_HOME%\jwsdp-shared\bin;%PATH%


  • Copy %JWSDP_HOME%\jaxb\samples\create-marshal directory to jaxb_smaple directory. (Note: we  will not use ant to build this project in here. You can delete build.xml file).
  • Create a subdirectory called classes under jaxb_sample\create-marshal.

JAXB Binding Compiler xjc

The Java Architecture for XML Binding (JAXB) provides a JAXB binding compiler  xjc. The JAXB binding compiler takes XML schema as input, and then generates a package of Java classes and interfaces that reflect the rules defined in the source schema. These generated classes and interfaces are in turn compiled and combined with a set of common JAXB utility packages to provide a JAXB binding framework. The Java classes generated with the JAXB binding compiler  xjc utility represent the different elements and complexType(s)  in an XML Schema. An XML document that conforms to the XML Schema may be constructed from the Java classes.

JAXB generates Java classes and interfaces corresponding to the top-level elements and top-level complexType elements. In a XML Schema, an element is represented with <xs:element/>, and a complexType is represented with <xs:complexType/>. The following example schema po.xsd has top-level element and complexType declarations (under <JWSDP installed directory>\jaxb\samples\create-marshal\):

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <xsd:element name="purchaseOrder" type="PurchaseOrderType"/>
  <xsd:element name="comment" type="xsd:string"/>
  <xsd:complexType name="PurchaseOrderType">
    <xsd:sequence>
      <xsd:element name="shipTo" type="USAddress"/>
      <xsd:element name="billTo" type="USAddress"/>
      <xsd:element ref="comment" minOccurs="0"/>
      <xsd:element name="items" type="Items"/>
    </xsd:sequence>
    <xsd:attribute name="orderDate" type="xsd:date"/>
  </xsd:complexType>

  <xsd:complexType name="USAddress">
    <xsd:sequence>
      <xsd:element name="name" type="xsd:string"/>
      <xsd:element name="street" type="xsd:string"/>
      <xsd:element name="city" type="xsd:string"/>
      <xsd:element name="state" type="xsd:string"/>
      <xsd:element name="zip" type="xsd:decimal"/>
    </xsd:sequence>
    <xsd:attribute name="country" type="xsd:NMTOKEN" fixed="US"/>
  </xsd:complexType>

  <xsd:complexType name="Items">
    <xsd:sequence>
      <xsd:element name="item" minOccurs="1" maxOccurs="unbounded">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="productName" type="xsd:string"/>
            <xsd:element name="quantity">
             <xsd:simpleType>
              <xsd:restriction base="xsd:positiveInteger">
                <xsd:maxExclusive value="100"/>
              </xsd:restriction>
             </xsd:simpleType>
            </xsd:element>
            <xsd:element name="USPrice" type="xsd:decimal"/>
            <xsd:element ref="comment" minOccurs="0"/>
            <xsd:element name="shipDate" type="xsd:date" minOccurs="0"/>
          </xsd:sequence>
          <xsd:attribute name="partNum" type="SKU" use="required"/>
        </xsd:complexType>
      </xsd:element>
    </xsd:sequence>
  </xsd:complexType>

  <!-- Stock Keeping Unit, a code for identifying products -->
  <xsd:simpleType name="SKU">
    <xsd:restriction base="xsd:string">
      <xsd:pattern value="\d{3}-[A-Z]{2}"/>
    </xsd:restriction>
  </xsd:simpleType>

</xsd:schema>

The problems with JAXB began when the JSR 31 expert group decided that they did not want to attempt full compatibility with the XML Schema standard. It is explicitly not a goal of JAXB to support all of Schema - they even have a list of key Schema constructs which they explicitly do not require. The expert group tried to assuage themselves by assuring, in the specification, that although all of XML Schema was not required, it would be permitted.  If such unsupported Schema constructs are included in a schema, an error will be generated when you try to generate Java classes from them with JAXB binding compiler xjc.


The following schema elements are not supported: xs:any, xs:anyAttribute, xs:notation, xs:redefine, xs:key, xs:keyref, and xs:unique. The following schema attributes are not supported: complexType.abstract, element.abstract, element.substitutionGroup, xsi:type, complexType.block, complexType.final, element.block, element.final, schema.blockDefault, and schema.finalDefault.


Generating Java Classes


The  xjc utility is run on the schema to bind a schema to Java classes. Run the xjc utility on the example schema with the command: "xjc po.xsd". More detail about the the options of the xjc utility, please  read  Java Architecture for XML Binding Binding Compiler (xjc).

Let's go to C:\jaxb_samples\create-marshal, run the xjc utility on the example schema po.xsd.

C:\jaxb_samples\create-marshal>xjc -p primer.po -d src po.xsd
parsing a schema...
compiling a schema...
primer\po\impl\CommentImpl.java
primer\po\impl\ItemsImpl.java
primer\po\impl\JAXBVersion.java
primer\po\impl\PurchaseOrderImpl.java
primer\po\impl\PurchaseOrderTypeImpl.java
primer\po\impl\USAddressImpl.java
primer\po\impl\runtime\NamespaceContextImpl.java
primer\po\impl\runtime\SAXUnmarshallerHandlerImpl.java
primer\po\impl\runtime\ValidationContext.java
primer\po\impl\runtime\NamespaceContext2.java
primer\po\impl\runtime\GrammarInfoFacade.java
primer\po\impl\runtime\MSVValidator.java
primer\po\impl\runtime\UnmarshallingContext.java
primer\po\impl\runtime\ValidatingUnmarshaller.java
primer\po\impl\runtime\ContentHandlerAdaptor.java
primer\po\impl\runtime\XMLSerializable.java
primer\po\impl\runtime\ValidatableObject.java
primer\po\impl\runtime\MarshallerImpl.java
primer\po\impl\runtime\UnmarshallingEventHandlerAdaptor.java
primer\po\impl\runtime\PrefixCallback.java
primer\po\impl\runtime\ErrorHandlerAdaptor.java
primer\po\impl\runtime\AbstractUnmarshallingEventHandlerImpl.java
primer\po\impl\runtime\Discarder.java
primer\po\impl\runtime\SAXMarshaller.java
primer\po\impl\runtime\SAXUnmarshallerHandler.java
primer\po\impl\runtime\UnmarshallerImpl.java
primer\po\impl\runtime\GrammarInfo.java
primer\po\impl\runtime\DefaultJAXBContextImpl.java
primer\po\impl\runtime\ValidatorImpl.java
primer\po\impl\runtime\XMLSerializer.java
primer\po\impl\runtime\InterningUnmarshallerHandler.java
primer\po\impl\runtime\GrammarInfoImpl.java
primer\po\impl\runtime\UnmarshallableObject.java
primer\po\impl\runtime\Util.java
primer\po\impl\runtime\UnmarshallingEventHandler.java
primer\po\Comment.java
primer\po\Items.java
primer\po\ObjectFactory.java
primer\po\PurchaseOrder.java
primer\po\PurchaseOrderType.java
primer\po\USAddress.java
primer\po\jaxb.properties
primer\po\bgm.ser

The primer.po is the package name  and the src is the generated codes outputing directory name.

A factory class (ObjectFactory.java), consisting of methods to create instance objects, also gets generated.

A Java interface and a Java class are generated corresponding to each top-level xs:element and top-level xs:complexType in the example XML Schema.
For example, PurchaseOrder.java is an interface generated corresponding to the top-level element PurchaseOrder which extends from javax.xml.bind.Element and primer.po.PurchaseOrderType:

package primer.po;

/**
* Java content class for purchaseOrder element declaration.
* <p>The following schema fragment specifies the expected content contained within
* this java content object. (defined at file:/C:/jaxb_sample/create-marshal/po.xsd line 2)
* <p>
* <pre>
* &lt;element name="purchaseOrder" type="{}PurchaseOrderType"/>
* </pre>
*
*/
public interface PurchaseOrder
extends javax.xml.bind.Element, primer.po.PurchaseOrderType
{


}

Each interface has one corresponding implementation class:

interface
 implementation class
Comment.java CommentImpl.java
Items.java ItemsImpl.java
PurchaseOrder.java PurchaseOrderImpl.java
PurchaseOrderType.java PurchaseOrderTypeImpl.java
USAddress.java USAddressImpl.java

For example PurchaseOrderImpl.java is the implementation class generated for the interface PurchaseOrder.java. Items.java and ItemsImpl.java is another example for the top-level complexType case.

Creating an XML Document from the Java Classes

Let's take a look the Main.java code. The original code output XML Document to console and we made a little changes to make it output to an XML Document po.xml. The bold lines are what we add or modify lines.

import java.io.FileNotFoundException;
import java.io.FileOutputStream;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.util.Calendar;
import java.util.List;

import javax.xml.bind.JAXBContext;
import javax.xml.bind.JAXBException;
import javax.xml.bind.Marshaller;

import primer.po.*;

public class Main {

// create a JAXBContext. A JAXBContext object is required
// to implement the JAXB binding framework
// operations marshal,unmarshal, and validate.
// An application creates a new instance (object) of
// the JAXBContext class with the static method

// newInstance(String contextPath).
// The contextPath specifies a list of Java package names for the
// schema-derived classes.
// The directory primer/po/ contains the JAXB-generated classes.

public static void main( String[] args ) {
try {
// create a JAXBContext
JAXBContext jc = JAXBContext.newInstance( "primer.po" );

// create an ObjectFactory instance.
// if the JAXBContext had been created with mutiple pacakge names,
// we would have to explicitly use the correct package name when
// creating the ObjectFactory.
ObjectFactory objFactory = new ObjectFactory();

// create an empty PurchaseOrder
PurchaseOrder po = objFactory.createPurchaseOrder();

// set the required orderDate attribute
po.setOrderDate( Calendar.getInstance() );

// create shipTo USAddress object
USAddress shipTo = createUSAddress( objFactory,
"Alice Smith",
"123 Maple Street",
"Cambridge",
"MA",
"12345" );

// set the required shipTo address
po.setShipTo( shipTo );

// create billTo USAddress object
USAddress billTo = createUSAddress( objFactory,
"Robert Smith",
"8 Oak Avenue",
"Cambridge",
"MA",
"12345" );

// set the requred billTo address
po.setBillTo( billTo );

// create an empty Items object
Items items = objFactory.createItems();

// get a reference to the ItemType list
List itemList = items.getItem();

// start adding ItemType objects into it
itemList.add( createItemType( objFactory,
"Nosferatu - Special Edition (1929)",
new BigInteger( "5" ),
new BigDecimal( "19.99" ),
null,
null,
"242-NO" ) );
itemList.add( createItemType( objFactory,
"The Mummy (1959)",
new BigInteger( "3" ),
new BigDecimal( "19.98" ),
null,
null,
"242-MU" ) );
itemList.add( createItemType( objFactory,
"Godzilla and Mothra: Battle for Earth/Godzilla vs. King Ghidora",
new BigInteger( "3" ),
new BigDecimal( "27.95" ),
null,
null,
"242-GZ" ) );

// set the required Items list
po.setItems( items );

 // Create a Marshaller with the createMarshaller method. The Marshaller class has overloaded marshal
// methods to marshal (that is, convert a Java object to XML data) into SAX2 events, a Document Object
// Model (DOM) structure, an OutputStream, a javax.xml.transform.Result, or a java.io.Writer object.
Marshaller m = jc.createMarshaller();
m.setProperty( Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE );

 //Marshal the po object to an XML document with the marshal method of the class Marshaller.
//The po object is marshalled to an OutputStream.
m.marshal( po, new FileOutputStream("po.xml")); } catch( FileNotFoundException fe) { fe.printStackTrace();

} catch( JAXBException je ) {
je.printStackTrace();
}
}

public static USAddress createUSAddress( ObjectFactory objFactory,
String name, String street,
String city, String state,
String zip )
throws JAXBException {

// create an empty USAddress objects
USAddress address = objFactory.createUSAddress();

// set properties on it
address.setName( name );
address.setStreet( street );
address.setCity( city );
address.setState( state );
address.setZip( new BigDecimal( zip ) );

// return it
return address;
}

public static Items.ItemType createItemType( ObjectFactory objFactory,
String productName,
BigInteger quantity,
BigDecimal price,
String comment,
Calendar shipDate,
String partNum )
throws JAXBException {

// create an empty ItemType object
Items.ItemType itemType = objFactory.createItemsItemType();

// set properties on it
itemType.setProductName( productName );
itemType.setQuantity( quantity );
itemType.setUSPrice( price );
itemType.setComment( comment );
itemType.setShipDate( shipDate );
itemType.setPartNum( partNum );

// return it
return itemType;
}
}

Let's compile Main.java with  the generated java codes and run it.
C:\jaxb_samples\create-marshal>javac -d classes src/*.java src/primer/po/*.java src/primer/po/impl/*.java  src/primer/po/impl/runtime/*.java
C:\jaxb_samples\create-marshal>copy src\primer\po\jaxb.properties classes\primer\po
C:\jaxb_sample\create-marshal>copy src\primer\po\bgm.ser  classes\primer\po
C:\jaxb_samples\create-marshal>cd classes
C:\jaxb_samples\create-marshal\classes>java Main

An XML document shall be created after runing Main. The example XML document, po.xml, is illustrated in the following listing.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<purchaseOrder orderDate="2006-02-02-05:00">
<shipTo>
<name>Alice Smith</name>
<street>123 Maple Street</street>
<city>Cambridge</city>
<state>MA</state>
<zip>12345</zip>
</shipTo>
<billTo>
<name>Robert Smith</name>
<street>8 Oak Avenue</street>
<city>Cambridge</city>
<state>MA</state>
<zip>12345</zip>
</billTo>
<items>
<item partNum="242-NO">
<productName>Nosferatu - Special Edition (1929)</productName>
<quantity>5</quantity>
<USPrice>19.99</USPrice>
</item>
<item partNum="242-MU">
<productName>The Mummy (1959)</productName>
<quantity>3</quantity>
<USPrice>19.98</USPrice>
</item>
<item partNum="242-GZ">
<productName>Godzilla and Mothra: Battle for Earth/Godzilla vs. King Ghidora</productName>
<quantity>3</quantity>
<USPrice>27.95</USPrice>
</item>
</items>
</purchaseOrder>

Notes:
  • Delete jaxb.properties and bgm.ser two files under classes\primer\po directory and run java Main again. You will get an javax.xml.bind.JAXBException exception as the following.

javax.xml.bind.JAXBException: Unable to locate jaxb.properties for package primer.po
        at javax.xml.bind.ContextFinder.searchcontextPath(ContextFinder.java:205)
        at javax.xml.bind.ContextFinder.find(ContextFinder.java:149)
        at javax.xml.bind.JAXBContext.newInstance(JAXBContext.java:281)
        at javax.xml.bind.JAXBContext.newInstance(JAXBContext.java:238)
        at Main.main(Main.java:39)

  • These two files must be stored at the contextPath which is used in i>JAXBContext.newInstance( contextPath );

Previous Next vertical dots separating previous/next from contents/index/pdf Contents

  |   |   
© Copyright 2005-2010 www.xyzws.com All rights reserved.