Trail: Java Architecture for XML Binding (JAXB)
Lesson: Introduction to JAXB
JAXB Examples
Home Page > Java Architecture for XML Binding (JAXB) > Introduction to JAXB

JAXB Examples

The sections that follow provide instructions for using the sample applications that are included in the JAXB RI bundle. The JAXB RI bundle is available from http://jaxb.java.net. Download and install the JAXB RI bundle. The examples are located in the jaxb-ri-install/samples/ directory. These examples demonstrate and build upon key JAXB features and concepts. Follow these procedures in the order presented.

After reading this section, you should feel comfortable enough with JAXB that you can:

This chapter describes three sets of examples:


Note: The Basic and Customize examples are based on a Purchase Order scenario. Each uses an XML document, po.xml, written against an XML schema, po.xsd. These documents are derived from the W3C XML Schema Part 0: Primer, edited by David C. Fallside.

The Basic and Customize example directories contain several base files:

The following tables briefly describe the Basic, Customize, and Java-to-Schema JAXB examples.

Table 9: Basic JAXB Examples

Example Name Description
Modify Marshal Example Demonstrates how to modify a Java content tree.
Unmarshal Validate Example Demonstrates how to enable validation during unmarshalling.

Table 10:  Customize JAXB Examples

Example Name Description
Customize Inline Example Demonstrates how to customize the default JAXB bindings by using 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 data types.
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.


Table 11:  Java-to-Schema JAXB Examples

Example Name Description
Create Marshal Example Demonstrates how to use the ObjectFactory class to create a Java content tree from scratch and marshal it to XML data. It also demonstrates how to add content to a JAXB List property.
XmlAccessorOrder Example Illustrates how to use the @XmlAccessorOrder and @XmlType.propOrder mapping annotations in Java classes to control the order in which XML content is marshalled/unmarshalled by a Java type.
XmlAdapter Field Example Illustrates how to use the interface XmlAdapter and the annotation @XmlJavaTypeAdapter to provide a a custom mapping of XML content into and out of a HashMap (field) that uses an int as the key and a String as the value.
XmlAttribute Field Example Illustrates how to use the annotation @XmlAttribute to define a property or field to be handled as an XML attribute.
XmlRootElement Example Illustrates how to use the annotation @XmlRootElement to define an XML element name for the XML schema type of the corresponding class.
XmlSchemaType Class Example Illustrates how to use the annotation @XmlSchemaType to customize the mapping of a property or field to an XML built-in type.
XmlType Example Illustrates how to use the annotation @XmlType to map a class or enum type to an XML schema type.

JAXB Compiler Options

The JAXB XJC schema binding compiler transforms, or binds, a source XML schema to a set of JAXB content classes in the Java programming language. The compiler class, xjc, is provided as: xjc.sh on Solaris/Linux and xjc.bat on Windows in the JAXB RI bundle. The xjc class is included in the JDK class library (in tools.jar). 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 as follows:

-nv
Do not perform strict validation of the input schema or schemas. 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, the XJC binding compiler strictly enforces the rules outlined in the Compatibility chapter of the JAXB Specification. 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 will be allowed to use the JAXB Vendor Extensions.
-b file
Specify one or more external binding files to process. (Each binding file must have its 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. In addition, the ordering of the 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 package
Specify an alternate output directory. By default, the XJC binding compiler will generate the Java content classes in the current directory. The output directory must already exist; the XJC binding compiler will not create it for you.
-proxy proxy
Specify the HTTP/HTTPS proxy. The format is [user[:password]@]proxyHost[:proxyPort]. The old -host and -port options are still supported by the Reference Implementation for backwards compatibility, but they have been deprecated.
-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. For more information, see the XML Entity and URI Resolvers document or examine the catalog-resolver sample application.
-readOnly
Force the XJC binding compiler to mark the generated Java sources read-only. By default, the XJC binding compiler does not write-protect the Java source files it generates.
-npa
Suppress the generation of package level annotations into **/package-info.java. Using this switch causes the generated code to internalize those annotations into the other generated classes.
-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.
-quiet
Suppress compiler output, such as progress information and warnings.
-help
Display a brief summary of the compiler switches.
-version
Display the compiler version information.
-Xlocator
Enable source location support for generated code.
-Xsync-methods
Generate accessor methods with the synchronized keyword.
-mark-generated
Mark the generated code with the -@javax.annotation.Generated annotation.

JAXB Schema Generator Option

The JAXB Schema Generator, schemagen, creates a schema file for each namespace referenced in your Java classes. The schema generator can be launched using the appropriate schemagen shell script in the bin directory for your platform. The schema generator processes Java source files only. If your Java sources reference other classes, those sources must be accessible from your system CLASSPATH environment variable, otherwise errors will occur when the schema is generated. There is no way to control the name of the generated schema files.

You can display quick usage instructions by invoking the scripts without any options, or with the -help option. The syntax is as follows:

schemagen [-d path] [java-source-files]

The -d path option specifies the location of the processor- and javac-generated class files.

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, Unmarshal Validate), the JAXB binding compiler generates a Java package named primer.po containing the classes, described in the following table.

Table 12:  Schema-Derived JAXB Classes in the Basic Examples

Class Description
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/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.

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

Table 13: Schema-to-Java Bindings for the Basic Examples

XML Schema JAXB Binding
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 
<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 sections that follow briefly explain the functions of the following individual classes generated by the JAXB binding compiler for the examples:

Items Class

In Items.java:

ObjectFactory Class

In ObjectFactory.java:

PurchaseOrderType Class

In PurchaseOrderType.java:

USAddress Class

In USAddress.java:


Problems with the examples? Try Compiling and Running the Examples: FAQs.
Complaints? Compliments? Suggestions? Give us your feedback.

Previous page: Customizing Generated Classes and Java Program Elements
Next page: Basic Examples