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.

System Requests

• Download and install the Java Web Services Developer Pack (Java WSDP) currently at version 2.0 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-2.0 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-2.0 set JWSDP_JAXB_LIB=%JWSDP_HOME%\jaxb\lib set JWSDP_SHARED_LIB=%JWSDP_HOME%\jwsdp-shared\lib set JWSDP_SJSXP_LIB=%JWSDP_HOME%\sjsxp\lib%JWSDP_HOME%\jaxb\bin;%JWSDP_HOME%\jwsdp-shared\bin;%PATH% set CLASSPATH=%JWSDP_JAXB_LIB%\jaxb-api.jar;               %JWSDP_JAXB_LIB%\jaxb-impl.jar;               %JWSDP_JAXB_LIB%\jaxb1-impl.jar;               %JWSDP_JAXB_LIB%\jaxb-xjc.jar;%CLASSPATH% set CLASSPATH=%JWSDP_SJSXP_LIB%\sjsxp.jar;               %JWSDP_SJSXP_LIB%\jsr173_api.jar;%CLASSPATH% set CLASSPATH=%JWSDP_SHARED_LIB%\activation.jar;               %JWSDP_SHARED_LIB%\resolver.jar;%CLASSPATH% set 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\Items.java
primer\po\ObjectFactory.java
primer\po\PurchaseOrderType.java
primer\po\USAddress.java
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 class is generated corresponding to each top-level xs:complexType in the example XML Schema. For example, USAddress.java is USAddress class generated corresponding to the top-level element USAddress. The USAddress.java is illustrated in the listing below:

package primer.po;

import java.math.BigDecimal;
import javax.xml.bind.annotation.AccessType;
import javax.xml.bind.annotation.XmlAccessorType;
import javax.xml.bind.annotation.XmlAttribute;
import javax.xml.bind.annotation.XmlType;
import javax.xml.bind.annotation.adapters.CollapsedStringAdapter;
import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
import primer.po.USAddress;


@XmlAccessorType(AccessType.FIELD)
@XmlType(name = "USAddress", propOrder = {
"name",
"street",
"city",
"state",
"zip"
})
public class USAddress {

protected String name;
protected String street;
protected String city;
protected String state;
protected BigDecimal zip;
@XmlAttribute
@XmlJavaTypeAdapter(CollapsedStringAdapter.class)
protected String country;

public String getName() {
return name;
}

public void setName(String value) {
this.name = value;
}

public String getStreet() {
return street;
}

public void setStreet(String value) {
this.street = value;
}

public String getCity() {
return city;
}

public void setCity(String value) {
this.city = value;
}

public String getState() {
return state;
}

public void setState(String value) {
this.state = value;
}

public BigDecimal getZip() {
return zip;
}

public void setZip(BigDecimal value) {
this.zip = value;
}

public String getCountry() {
if (country == null) {
return "US";
} else {
return country;
}
}

public void setCountry(String value) {
this.country = value;
}

}

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.GregorianCalendar;
import java.util.List;

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

import javax.xml.datatype.DatatypeFactory;
import javax.xml.datatype.XMLGregorianCalendar;
import javax.xml.datatype.DatatypeConfigurationException;

// import java content classes generated by binding compiler
import primer.po.*;

public class Main {

public static void main( String[] args ) {
try {
// 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.

            JAXBContext jc = JAXBContext.newInstance( "primer.po" );

// create an empty PurchaseOrder
PurchaseOrderType po = new PurchaseOrderType();

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

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

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

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

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

// create an empty Items object
Items items = new Items();

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

// start adding ItemType objects into it
itemList.add( createItem( "Nosferatu - Special Edition (1929)", 
new BigInteger( "5" ), 
new BigDecimal( "19.99" ), 
null,
null,
"242-NO" ) );
itemList.add( createItem( "The Mummy (1959)", 
new BigInteger( "3" ), 
new BigDecimal( "19.98" ), 
null,
null,
"242-MU" ) );
itemList.add( createItem( "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 an element for marshalling
JAXBElement<PurchaseOrderType> poElement = (new ObjectFactory()).createPurchaseOrder(po);

            // 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  poElement object to an XML document with the marshal method of the class Marshaller. 
//The poElement object is marshalled to an OutputStream.
            m.marshal( poElement, new FileOutputStream("po.xml"));
             
        }  catch( FileNotFoundException fe) {
           fe.printStackTrace();
         } catch( JAXBException je ) {
je.printStackTrace();
} 
}

public static USAddress createUSAddress(  String name, String street,
String city, String state,
String zip ) {

// create an empty USAddress objects                                             
USAddress address = new USAddress();

// 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.Item createItem( String productName,
BigInteger quantity,
BigDecimal price,
String comment,
XMLGregorianCalendar shipDate,
String partNum ) {

// create an empty ItemType object
Items.Item item = new Items.Item();

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

// return it
return item;
}


private static XMLGregorianCalendar getDate() {
try {
return DatatypeFactory.newInstance().newXMLGregorianCalendar(new GregorianCalendar());
} catch (DatatypeConfigurationException e) {
throw new Error(e);
}
}
}

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/*.javaC:\jaxb_samples\create-marshal>cd classesC:\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"?>
<purchaseOrder orderDate="1999-10-20">
<shipTo country="US">
<name>Alice Smith</name>
<street>123 Maple Street</street>
<city>Cambridge</city>
<state>MA</state>
<zip>12345</zip>
</shipTo>
<billTo country="US">
<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>