Download FAQ History

API Search Feedback

General Usage Instructions

This section provides general usage instructions for the examples used in this chapter, including how to build and run the applications using the Ant build tool, and provides details about the default schema-to-JAXB bindings used in these examples.

Description

This chapter describes ten examples; the basic examples (Unmarshal Read, Modify Marshal, Create Marshal, Unmarshal Validate, Validate-On-Demand) demonstrate basic JAXB concepts like ummarshalling, marshalling, and validating XML content, while the customize examples (Customize Inline, Datatype Converter, External Customize, Fix Collides, Bind Choice) demonstrate various ways of customizing the binding of XML schemas to Java objects. Each of the examples in this chapter is based on a Purchase Order scenario. With the exception of the Bind Choice and the Fix Collides examples, each uses an XML document, po.xml, written against an XML schema, po.xsd.

Table 2-1 Sample JAXB Application Descriptions

Example Name	Description
Unmarshal Read Example	Demonstrates how to unmarshal an XML document into a Java content tree and access the data contained within it.
Modify Marshal Example	Demonstrates how to modify a Java content tree.
Create Marshal Example	Demonstrates how to use the ObjectFactory class to create a Java content tree from scratch and then marshal it to XML data.
Unmarshal Validate Example	Demonstrates how to enable validation during unmarshalling.
Validate-On-Demand Example	Demonstrates how to validate a Java content tree at runtime.
Customize Inline Example	Demonstrates how to customize the default JAXB bindings by means of inline annotations in an XML schema.
Datatype Converter Example	Similar to the Customize Inline example, this example illustrates alternate, more terse bindings of XML simpleType definitions to Java datatypes.
External Customize Example	Illustrates how to use an external binding declarations file to pass binding customizations for a read-only schema to the JAXB binding compiler.
Fix Collides Example	Illustrates how to use customizations to resolve name conflicts reported by the JAXB binding compiler. It is recommended that you first run ant fail in the application directory to see the errors reported by the JAXB binding compiler, and then look at binding.xjb to see how the errors were resolved. Running ant alone uses the binding customizations to resolve the name conflicts while compiling the schema.
Bind Choice Example	Illustrates how to bind a choice model group to a Java interface.

---

Note: These examples are all located in the $JWSDP_HOME/jaxb/samples directory.

---

Each example directory contains several base files:

po.xsd is the XML schema you will use as input to the JAXB binding compiler, and from which schema-derived JAXB Java classes will be generated. For the Customize Inline and Datatype Converter examples, this file contains inline binding customizations. Note that the Bind Choice and Fix Collides examples use example.xsd rather than po.xsd.
po.xml is the Purchase Order XML file containing sample XML content, and is the file you will unmarshal into a Java content tree in each example. This file is almost exactly the same in each example, with minor content differences to highlight different JAXB concepts. Note that the Bind Choice and Fix Collides examples use example.xml rather than po.xml.
Main.java is the main Java class for each example.
build.xml is an Ant project file provided for your convenience. Use Ant to generate, compile, and run the schema-derived JAXB classes automatically. The build.xml file varies across the examples.
MyDatatypeConverter.java in the inline-customize example is a Java class used to provide custom datatype conversions.
binding.xjb in the External Customize, Bind Choice, and Fix Collides examples is an external binding declarations file that is passed to the JAXB binding compiler to customize the default JAXB bindings.
example.xsd in the Fix Collides example is a short schema file that contains deliberate naming conflicts, to show how to resolve such conflicts with custom JAXB bindings.

Using the Examples

As with all applications that implement schema-derived JAXB classes, as described above, there are two distinct phases in using JAXB:

Generating and compiling JAXB Java classes from an XML source schema
Unmarshalling, validating, processing, and marshalling XML content

In the case of these examples, you perform these steps by using Ant with the build.xml project file included in each example directory.

Configuring and Running the Samples

The build.xml file included in each example directory is an Ant project file that, when run, automatically performs the following steps:

Updates your CLASSPATH to include the necessary schema-derived JAXB classes.
Runs the JAXB binding compiler to generate JAXB Java classes from the XML source schema, po.xsd, and puts the classes in a package named primer.po.
Generates API documentation from the schema-derived JAXB classes using the Javadoc tool.
Compiles the schema-derived JAXB classes.
Runs the Main class for the example.

Solaris/Linux

Set the following environment variables:

export JAVA_HOME=<your J2SE installation directory>
export JWSDP_HOME=<your JWSDP installation directory>

Change to the desired example directory.

For example, to run the Unmarshal Read example:

cd <JWSDP_HOME>/jaxb/samples/unmarshal-read

(<JWSDP_HOME> is the directory where you installed the Java WSDP bundle.)

Run ant:

$JWSDP_HOME/apache-ant/bin/ant -emacs

Repeat these steps for each example.

Windows NT/2000/XP

Set the following environment variables:

set JAVA_HOME=<your J2SE installation directory>
set JWSDP_HOME=<your JWSDP installation directory>

Change to the desired example directory.

For example, to run the Unmarshal Read example:

cd <JWSDP_HOME>\jaxb\samples\unmarshal-read

(<JWSDP_HOME> is the directory where you installed the Java WSDP bundle.)

Run ant:

%JWSDP_HOME%\apache-ant\bin\ant -emacs

Repeat these steps for each example.

The schema-derived JAXB classes and how they are bound to the source schema is described in About the Schema-to-Java Bindings. The methods used for building and processing the Java content tree are described in Basic Examples.

JAXB Compiler Options

The JAXB schema binding compiler is located in the <JWSDP_HOME>/jaxb/bin directory. There are two scripts in this directory: xjc.sh (Solaris/Linux) and xjc.bat (Windows).

Both xjc.sh and xjc.bat take the same command-line options. You can display quick usage instructions by invoking the scripts without any options, or with the -help switch. The syntax is as follows:

xjc [-options ...] <schema> 

The xjc command-line options are listed in Table 2-2.

Table 2-2 xjc Command-Line Options 

Option or Argument	Description
<schema>	One or more schema files to compile.
-nv	Do not perform strict validation of the input schema(s). By default, xjc performs strict validation of the source schema before processing. Note that this does not mean the binding compiler will not perform any validation; it simply means that it will perform less-strict validation.
-extension	By default, xjc strictly enforces the rules outlined in the Compatibility chapter of the JAXB Specification. Specifically, Appendix E.2 defines a set of W3C XML Schema features that are not completely supported by JAXB v1.0. In some cases, you may be able to use these extensions with the -extension switch. In the default (strict) mode, you are also limited to using only the binding customizations defined in the specification. By using the -extension switch, you can enable the JAXB Vendor Extensions.
-b <file>	Specify one or more external binding files to process (each binding file must have it's own -b switch). The syntax of the external binding files is extremely flexible. You may have a single binding file that contains customizations for multiple schemas, or you can break the customizations into multiple bindings files; for example:   xjc schema1.xsd schema2.xsd schema3.xsd -b bindings123.xjb xjc schema1.xsd schema2.xsd schema3.xsd -b bindings1.xjb -b bindings2.xjb -b bindings3.xjb   Note that the ordering of schema files and binding files on the command line does not matter.
-d <dir>	By default, xjc will generate Java content classes in the current directory. Use this option to specify an alternate output directory. The directory must already exist; xjc will not create it for you.
-p <pkg>	Specifies the target package for schema-derived classes. This option overrides any binding customization for package name as well as the default package name algorithm defined in the JAXB Specification.
-host <proxyHost>	Set http.proxyHost to <proxyHost>.
-port <proxyPort>	Set http.proxyPort to <proxyPort>.
-classpath <arg>	Specify where to find client application class files used by the <jxb:javaType> and <xjc:superClass> customizations.
-catalog <file>	Specify catalog files to resolve external entity references.Supports TR9401, XCatalog, and OASIS XML Catalog format.
-readOnly	Generated source files will be marked read-only. By default, xjc does not write-protect the schema-derived source files it generates.
-use-runtime <pkg>	Suppress the generation of the impl.runtime package and refer to another existing runtime in the specified package. This option is useful when you are compiling multiple independent schemas. Because the generated impl.runtime packages are identical, except for their package declarations, you can reduce the size of your generated codebase by telling the compiler to reuse an existing impl.runtime package.
-xmlschema	Treat input schemas as W3C XML Schema (default). If you do not specify this switch, your input schemas will be treated as W3C XML Schema.
-relaxng	Treat input schemas as RELAX NG (experimental, unsupported). Support for RELAX NG schemas is provided as a JAXB Vendor Extension.
-dtd	Treat input schemas as XML DTD (experimental, unsupported). Support for RELAX NG schemas is provided as a JAXB Vendor Extension.
-help	Display this help message.

The command invoked by the xjc.sh and xjc.bat scripts is equivalent to the Java command:

$JAVA_HOME/bin/java -jar $JAXB_HOME/lib/jaxb-xjc.jar 

About the Schema-to-Java Bindings

When you run the JAXB binding compiler against the po.xsd XML schema used in the basic examples (Unmarshal Read, Modify Marshal, Create Marshal, Unmarshal Validate, Validate-On-Demand), the JAXB binding compiler generates a Java package named primer.po containing eleven classes, making a total of twelve classes in each of the basic examples:

Table 2-3 Schema-Derived JAXB Classes in the Basic Examples 

Class	Description
primer/po/ Comment.java	Public interface extending javax.xml.bind.Element; binds to the global schema element named comment. Note that JAXB generates element interfaces for all global element declarations.
primer/po/ Items.java	Public interface that binds to the schema complexType named Items.
primer/po/ ObjectFactory.java	Public class extending com.sun.xml.bind.DefaultJAXBContextImpl; used to create instances of specified interfaces. For example, the ObjectFactory createComment() method instantiates a Comment object.
primer/po/ PurchaseOrder.java	Public interface extending javax.xml.bind.Element, and PurchaseOrderType; binds to the global schema element named PurchaseOrder.
primer/po/ PurchaseOrderType.java	Public interface that binds to the schema complexType named PurchaseOrderType.
primer/po/ USAddress.java	Public interface that binds to the schema complexType named USAddress.
primer/po/impl/ CommentImpl.java	Implementation of Comment.java.
primer/po/impl/ ItemsImpl.java	Implementation of Items.java
primer/po/impl/ PurchaseOrderImpl.java	Implementation of PurchaseOrder.java
primer/po/impl/ PurchaseOrderTypeImpl.java	Implementation of PurchaseOrderType.java
primer/po/impl/ USAddressImpl.java	Implementation of USAddress.java

---

Note: You should never directly use the generated implementation classes--that is, *Impl.java in the <packagename>/impl directory. These classes are not directly referenceable because the class names in this directory are not standardized by the JAXB specification. The ObjectFactory method is the only portable means to create an instance of a schema-derived interface. There is also an ObjectFactory.newInstance(Class JAXBinterface) method that enables you to create instances of interfaces.

---

These classes and their specific bindings to the source XML schema for the basic examples are described below.

Table 2-4 Schema-to-Java Bindings for the Basic Examples 

XML Schema	JAXB Binding
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="purchaseOrder" type="PurchaseOrderType"/>	PurchaseOrder.java
<xsd:element name="comment" type="xsd:string"/>	Comment.java
<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>	PurchaseOrderType.java
<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>	USAddress.java
<xsd:complexType name="Items">   <xsd:sequence>     <xsd:element name="item" minOccurs="1" maxOccurs="unbounded">	Items.java
<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>	Items.ItemType
</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>

Schema-Derived JAXB Classes

The code for the individual classes generated by the JAXB binding compiler for the basic examples is listed below, followed by brief explanations of its functions. The classes listed here are:

Comment.java
Items.java
ObjectFactory.java
PurchaseOrder.java
PurchaseOrderType.java
USAddress.java

Comment.java

In Comment.java:

The Comment.java class is part of the primer.po package.
Comment is a public interface that extends javax.xml.bind.Element.
Content in instantiations of this class bind to the XML schema element named comment.
The getValue() and setValue() methods are used to get and set strings representing XML comment elements in the Java content tree.

The Comment.java code looks like this:

package primer.po;

public interface Comment
    extends javax.xml.bind.Element
{

    String getValue();
    void setValue(String value);
} 

Items.java

In Items.java, below:

The Items.java class is part of the primer.po package.
The class provides public interfaces for Items and ItemType.
Content in instantiations of this class bind to the XML ComplexTypes Items and its child element ItemType.
Item provides the getItem() method.
ItemType provides methods for:
getPartNum();
setPartNum(String value);
getComment();
setComment(java.lang.String value);
getUSPrice();
setUSPrice(java.math.BigDecimal value);
getProductName();
setProductName(String value);
getShipDate();
setShipDate(java.util.Calendar value);
getQuantity();
setQuantity(java.math.BigInteger value);

The Items.java code looks like this:

package primer.po;

public interface Items {
   java.util.List getItem();

   public interface ItemType {
        String getPartNum();
        void setPartNum(String value);
        java.lang.String getComment();
        void setComment(java.lang.String value);
        java.math.BigDecimal getUSPrice();
        void setUSPrice(java.math.BigDecimal value);
        String getProductName();
        void setProductName(String value);
        java.util.Calendar getShipDate();
        void setShipDate(java.util.Calendar value);
        java.math.BigInteger getQuantity();
        void setQuantity(java.math.BigInteger value);
    }
} 

ObjectFactory.java

In ObjectFactory.java, below:

The ObjectFactory class is part of the primer.po package.
ObjectFactory provides factory methods for instantiating Java interfaces representing XML content in the Java content tree.
Method names are generated by concatenating:
The string constant create
If the Java content interface is nested within another interface, then the concatenation of all outer Java class names
The name of the Java content interface
JAXB implementation-specific code was removed in this example to make it easier to read.

For example, in this case, for the Java interface primer.po.Items.ItemType, ObjectFactory creates the method createItemsItemType().

The ObjectFactory.java code looks like this:

package primer.po;

public class ObjectFactory
    extends com.sun.xml.bind.DefaultJAXBContextImpl {

    /**
     * Create a new ObjectFactory that can be used to create
     * new instances of schema derived classes for package: 
     * primer.po
     */
    public ObjectFactory() {
        super(new primer.po.ObjectFactory.GrammarInfoImpl());
    }

    /**
     * Create an instance of the specified Java content
     * interface.
     */
    public Object newInstance(Class javaContentInterface)
        throws javax.xml.bind.JAXBException
    {
        return super.newInstance(javaContentInterface);
    }

    /**
     * Get the specified property. This method can only be
     * used to get provider specific properties.
     * Attempting to get an undefined property will result
     * in a PropertyException being thrown.
     */
    public Object getProperty(String name)
        throws javax.xml.bind.PropertyException
    {
        return super.getProperty(name);
    }

    /**
     * Set the specified property. This method can only be
     * used to set provider specific properties.
     * Attempting to set an undefined property will result
     * in a PropertyException being thrown.
     */
    public void setProperty(String name, Object value)
        throws javax.xml.bind.PropertyException
    {
        super.setProperty(name, value);
    }

    /**
     * Create an instance of PurchaseOrder
     */
    public primer.po.PurchaseOrder createPurchaseOrder()
        throws javax.xml.bind.JAXBException
    {
        return ((primer.po.PurchaseOrder)
            newInstance((primer.po.PurchaseOrder.class)));
    }

    /**
     * Create an instance of ItemsItemType
     */
    public primer.po.Items.ItemType createItemsItemType()
        throws javax.xml.bind.JAXBException
    {
        return ((primer.po.Items.ItemType)
            newInstance((primer.po.Items.ItemType.class)));
    }

    /**
     * Create an instance of USAddress
     */
    public primer.po.USAddress createUSAddress()
        throws javax.xml.bind.JAXBException
    {
        return ((primer.po.USAddress)
            newInstance((primer.po.USAddress.class)));
    }

    /**
     * Create an instance of Comment
     */
    public primer.po.Comment createComment()
        throws javax.xml.bind.JAXBException
    {
        return ((primer.po.Comment)
            newInstance((primer.po.Comment.class)));
    }

    /**
     * Create an instance of Comment
     */
    public primer.po.Comment createComment(String value)
        throws javax.xml.bind.JAXBException
    {
        return new primer.po.impl.CommentImpl(value);
    }

    /**
     * Create an instance of Items
     */
    public primer.po.Items createItems()
        throws javax.xml.bind.JAXBException
    {
        return ((primer.po.Items)
            newInstance((primer.po.Items.class)));
    }

    /**
     * Create an instance of PurchaseOrderType
     */
    public primer.po.PurchaseOrderType 
createPurchaseOrderType()
        throws javax.xml.bind.JAXBException
    {
        return ((primer.po.PurchaseOrderType)
            newInstance((primer.po.PurchaseOrderType.class)));
    }
} 

PurchaseOrder.java

In PurchaseOrder.java, below:

The PurchaseOrder class is part of the primer.po package.
PurchaseOrder is a public interface that extends javax.xml.bind.Element and primer.po.PurchaseOrderType.
Content in instantiations of this class bind to the XML schema element named purchaseOrder.

The PurchaseOrder.java code looks like this:

package primer.po;

public interface PurchaseOrder
extends javax.xml.bind.Element, primer.po.PurchaseOrderType{
} 

PurchaseOrderType.java

In PurchaseOrderType.java, below:

The PurchaseOrderType class is part of the primer.po package.
Content in instantiations of this class bind to the XML schema child element named PurchaseOrderType.
PurchaseOrderType is a public interface that provides the following methods:
getItems();
setItems(primer.po.Items value);
getOrderDate();
setOrderDate(java.util.Calendar value);
getComment();
setComment(java.lang.String value);
getBillTo();
setBillTo(primer.po.USAddress value);
getShipTo();
setShipTo(primer.po.USAddress value);

The PurchaseOrderType.java code looks like this:

package primer.po;

public interface PurchaseOrderType {
    primer.po.Items getItems();
    void setItems(primer.po.Items value);
    java.util.Calendar getOrderDate();
    void setOrderDate(java.util.Calendar value);
    java.lang.String getComment();
    void setComment(java.lang.String value);
    primer.po.USAddress getBillTo();
    void setBillTo(primer.po.USAddress value);
    primer.po.USAddress getShipTo();
    void setShipTo(primer.po.USAddress value);
} 

USAddress.java

In USAddress.java, below:

The USAddress class is part of the primer.po package.
Content in instantiations of this class bind to the XML schema element named USAddress.
USAddress is a public interface that provides the following methods:
getState();
setState(String value);
getZip();
setZip(java.math.BigDecimal value);
getCountry();
setCountry(String value);
getCity();
setCity(String value);
getStreet();
setStreet(String value);
getName();
setName(String value);

The USAddress.java code looks like this:

package primer.po;

public interface USAddress {
    String getState();
    void setState(String value);
    java.math.BigDecimal getZip();
    void setZip(java.math.BigDecimal value);
    String getCountry();
    void setCountry(String value);
    String getCity();
    void setCity(String value);
    String getStreet();
    void setStreet(String value);
    String getName();
    void setName(String value);
} 

Download FAQ History

API Search Feedback

All of the material in The Java(TM) Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.