The Java Tutorials have been written for JDK 8. Examples and practices described in this page don't take advantage of improvements introduced in later releases and might use technology no longer available.
See Java Language Changes for a summary of updated language features in Java SE 9 and subsequent releases.
See JDK Release Notes for information about new features, enhancements, and removed or deprecated options for all JDK releases.
The following sections describe how to use 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 document describes three sets of examples:
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: Basic JAXB Examples
Example Name | Description |
---|---|
Modify Marshal | Demonstrates how to modify a Java content tree. |
Unmarshal Validate | Demonstrates how to enable validation during unmarshalling. |
Table: Customize JAXB Examples
Example Name | Description |
---|---|
Customize Inline | Demonstrates how to customize the default JAXB bindings by using inline annotations in an XML schema. |
Datatype Converter | Illustrates alternate, more terse bindings of XML simpleType definitions to Java data types, and is similar to Customize Inline example. |
External Customize | Illustrates how to use an external binding declarations file to pass binding customizations for a read-only schema to the JAXB binding compiler. |
Table: Java-to-Schema JAXB Examples
Example Name | Description |
---|---|
Create Marshal | Demonstrates how to use the ObjectFactory class to create a Java content tree and marshal it to XML data. It also demonstrates how to add content to a JAXB List property. |
XmlAccessorOrder | Illustrates how to use the @XmlAccessorOrder and @XmlType.propOrder mapping annotations in Java classes to control the order in which XML content is marshalled or unmarshalled by a Java type. |
XmlAdapter | Illustrates how to use the interface XmlAdapter and the annotation @XmlJavaTypeAdapter to provide a custom mapping of XML content into and out of a HashMap (field) that uses an integer (int) as the key and a string (String) as the value. |
XmlAttribute | Illustrates how to use the annotation @XmlAttribute to define a property or field to be handled as an XML attribute. |
XmlRootElement | Illustrates how to use the annotation @XmlRootElement to define an XML element name for the XML schema type of the corresponding class. |
XmlSchemaType Class | Illustrates how to use the annotation @XmlSchemaType to customize the mapping of a property or field to an XML built-in type. |
XmlType | Illustrates how to use the annotation @XmlType to map a class or enum type to an XML schema type. |
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 file/URL/dir/jar>... [-b >bindinfo<] ...
If dir is specified, all schema files in the directory will be compiled. If jar is specified, /META-INF/sun-jaxb.episode binding file will be compiled.
The xjc command-line options are as follows:
The JAXB Schema Generator, schemagen, creates a schema file for each namespace referenced in your Java classes. The schema generator can be started by 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 by using the -help option. The syntax is as follows:
schemagen [-d path] [java-source-files]
The -d path option specifies the location of the processor-generated and javac-generated class files.
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: 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: 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> |
The next sections briefly explain the functions of the following individual classes generated by the JAXB binding compiler for the examples:
In Items.java:
In ObjectFactory.java:
As an example, in this case, for the Java interface primer.po.Items.ItemType, the ObjectFactory creates the method createItemsItemType().
In PurchaseOrderType.java:
In USAddress.java: