18 Using the JAXB Class Generator
An explanation is given of how to use the Java Architecture for XML Binding (JAXB) class generator.
Note:
Use the Java Architecture for XML Binding (JAXB) class generator for new applications to take advantage of the object binding feature for Extensible Markup Language (XML) data. The Oracle9i class generator for Java is deprecated. Oracle Database 10g supports the Oracle9i class generator for backward compatibility.
Introduction to the JAXB Class Generator
Topics introducing the JAXB class generator include prerequisites, standards and specifications, marshalling and unmarshalling, validation, and customization.
Prerequisites for Using the JAXB Class Generator
Prerequisites for using the JAXB class generator are listed.
This chapter assumes that you have some familiarity with these topics:
-
Java Architecture for XML Binding (JAXB). For a more thorough introduction to JAXB than is possible in this chapter, consult the XML resources listed in Related Documents.
-
XML Schema language. See Using the XML Schema Processor for Java for an overview and links to suggested reading.
Standards and Specifications for the JAXB Class Generator
The Oracle JAXB processor implements JSR-31, The Java Architecture for XML Binding (JAXB), Version 1.0, which is a recommendation of the Java Community Process (JCP).
The Oracle XML Developer's Kit (XDK) implementation of the JAXB 1.0 specification does not support these optional features:
-
Javadoc generation
-
Fail Fast validation
-
External customization file
-
XML Schema concepts described in section E.2 of the specification
Related Topics
JAXB Class Generator Features
The JAXB class generator for Java generates the interfaces and the implementation classes corresponding to an XML Schema. Its principal advantage to Java developers is automation of the mapping between XML documents and Java code, which enables programs to use generated code to read, manipulate, and re-create XML data.
The Java classes, which can be extended, give the developer access to the XML data without knowledge of the underlying XML data structure.
The Oracle JAXB class generator provides these advantages for XML application development in Java:
-
Speed
Because the schema-to-code conversion is automated, you can rapidly generate Java code from an input XML schema.
-
Ease of use
You can invoke generated
get
andset
methods rather than code your own from the start. -
Automated data conversion
You can automate the conversion of XML document data into Java data types.
-
Customization
JAXB provides a flexible framework that enables you to customize the binding of XML elements and attributes.
Marshalling and Unmarshalling with JAXB
JAXB is an application programming interface (API) and set of tools that maps XML data to Java objects. JAXB simplifies access to an XML document from a Java program by presenting the XML document to the program in a Java format.
You can use the JAXB API and tools to perform these basic tasks:
-
Generate and compile JAXB classes from an XML schema with the
orajaxb
command-line utility.To use the JAXB class generator to generate Java classes you must provide it with an XML schema. Document type definitions (DTDs) are not supported by JAXB. As explained in Converting DTDs to XML Schemas, however, you can use the
DTD2Schema
program to convert a DTD to an XML schema. Afterwards, you can use the JAXB class generator to generate classes from the schema.The JAXB compiler generates Java classes that map to constraints in the source XML schema. The classes implements
get
andset
methods that you can use to get and specify data for each type of element and attribute in the schema. -
Process XML documents by instantiating the generated classes in a Java program.
Specifically, you can write a program that uses the JAXB binding framework to perform these tasks:
-
Unmarshal the XML documents.
As explained in the JAXB specification, unmarshalling is defined as moving data from an XML document to the Java-generated objects.
-
Validate the XML documents.
You can validate before or during the unmarshalling of the contents into the content tree. You can also validate on demand by invoking the validation API on the Java object. See Validation with JAXB.
-
Modify Java content objects.
The content tree of data objects represents the structure and content of the source XML documents. You can use the
set
methods defined for a class to modify the content of elements and attributes. -
Marshal Java content objects back to XML.
In contrast to unmarshalling, marshalling is creating an XML document from Java objects by traversing a content tree of instances of Java classes. You can serialize the data to a Document Object Model (DOM) tree, Simple API for XML (SAX) content handler, transformation result, or output stream.
-
Validation with JAXB
A Java content tree is considered valid with an XML schema when marshalling the tree generates a valid XML document.
JAXB applications can perform validation in these circumstances:
-
Unmarshalling-time validation that notifies the application of errors and warnings during unmarshalling. If unmarshalling includes validation that is error-free, then the input XML document and the Java content tree are valid.
-
On-demand validation of a Java content tree initiated by the application.
-
Fail-fast validation that gives immediate results while updating the Java content tree with
set
andget
methods. As specified in Standards and Specifications for the JAXB Class Generator, fail-fast validation is an optional feature in the JAXB 1.0 specification that is not supported in the XDK implementation of the JAXB class generator.
JAXB applications must be able to marshal a valid Java content tree, but they are not required to ensure that the Java content tree is valid before invoking a marshalling API. The marshalling process does not itself validate the content tree. Programs are required to throw a javax/xml/bind/MarshalException
when marshalling fails due to invalid content.
JAXB Customization
The declared element and type names in an XML schema do not always provide the most useful Java class names. You can override the default JAXB bindings by using custom binding declarations, which are described in the JAXB specification.
These declarations let you customize your generated JAXB classes beyond the XML-specific constraints in an XML schema, to include Java-specific refinements such as class and package name mappings.
You can annotate the schema to perform these customizations:
-
Bind XML names to user-defined Java class names
-
Name the package, derived classes, and methods
-
Choose which elements to bind to which classes
-
Decide how to bind each attribute and element declaration to a property in the appropriate content class
-
Choose the type of each attribute-value or content specification
Several of the demos programs listed in Table 18-2 show JAXB customizations.
See Also:
Customizing a Class Name in a Top-Level Element for a detailed explanation of a customization demo
Using the JAXB Class Generator: Overview
Topics here include the basic process of using the JAXB processor, running the XML schema processor demo programs, and using the JAXB class generator command-line utility.
Using the JAXB Processor: Basic Process
The XDK JAXB API basic process is described.
The XDK JAXB API exposes these packages:
-
javax.xml.bind
, which provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation -
javax.xml.bind.util
, which provides useful client utility classes
The most important classes and interfaces in the javax.xml.bind
package are described in Table 18-1. These form the core of most JAXB applications.
Table 18-1 javax.xml.bind Classes and Interfaces
Class/Interface | Description | Methods |
---|---|---|
|
Provides an abstraction for managing the XML/Java binding information necessary to implement the JAXB binding framework operations: unmarshal, marshal, and validate. A client application gets new instances of this class by invoking the |
The principal methods are:
|
|
Governs the process of serializing Java content trees into XML data. |
The principal methods are:
|
|
Governs the process of deserializing XML data into newly created Java content trees, optionally validating the XML data as it is unmarshalled. |
The principal methods are:
|
|
Controls the validation of content trees during run time. Specifically, this interface controls on-demand validation, which enables clients to receive data about validation errors and warnings detected in the Java content tree. |
The principal methods are:
|
Figure 18-1 depicts the process flow of a framework that uses the JAXB class generator.
The basic stages of the process shown in Figure 18-1 are:
See Also:
-
Oracle Database XML Java API Reference for details of the JAXB API
-
Processing XML with the JAXB Class Generator for detailed explanations of JAXB processing
Running the XML Schema Processor Demo Programs
Demo programs for the JAXB class generator for Java are included in $ORACLE_HOME/xdk/demo/java/jaxb
.
Specifically, XDK includes the JAXB demos listed in Table 18-2.
Table 18-2 JAXB Class Generator Demos
Program | Subdirectory within Oracle Home | Demonstrates . . . |
---|---|---|
|
|
The binding of top-level element and |
|
|
The binding of a top-level element with an inline |
|
|
The binding of a top-level |
|
|
The binding of a content model within a |
|
|
The binding of |
|
|
The binding of atomic data types. |
|
|
The binding a |
|
|
The binding of elements and types declared in two different namespaces. |
|
|
The customization of a Java package name. |
|
|
The customization of class name in a top-level element. See Customizing a Class Name in a Top-Level Element for a detailed explanation of this program. |
|
|
The customization of class name of a local element occurring in a repeating model group declared inside a |
|
|
The customization of the attribute name. |
|
|
The |
|
|
The customization of the typesafe enum class name. |
You can find documentation that describes how to compile and run the sample programs in the README
in the same directory. The basic steps are:
-
Change into the
$ORACLE_HOME/xdk/demo/java/jaxb
directory (UNIX) or%ORACLE_HOME%\xdk\demo\java\jaxb
directory (Windows). -
Make sure that your environment variables are set as described in Setting Up the XDK for Java Environment.
-
Run
make
(UNIX) orMake.bat
(Windows) at the system prompt. Themake
utility performs these sequential actions for each sample subdirectory:-
Runs the
orajaxb
utility to generate Java class files based on an input XML schema. For most of the demos, the output classfiles are written to thegenerated
subdirectory. For example, themake
file performs these commands for thesample1.xsd
schema in theSample1
subdirectory:cd ./Sample1; $(JAVA_HOME)/bin/java -classpath "$(MAKE_CLASSPATH)" \ oracle.xml.jaxb.orajaxb -schema sample1.xsd -targetPkg generated; echo;
-
Runs the
javac
utility to compile the Java classes. For example, themake
utility performs these commands for the Java class files in theSample1/generated/
subdirectory:cd ./Sample1/generated; $(JAVA_HOME)/bin/javac -classpath \ "$(MAKE_CLASSPATH)" *.java
-
Runs the
javac
utility to compile a sample Java application that uses the classes compiled in the preceding step. For example, themake
utility compiles theSampleApp1.java
program:cd ./Sample1; $(JAVA_HOME)/bin/javac -classpath "$(MAKE_CLASSPATH)" \ SampleApp1.java
-
Runs the sample Java application and writes the results to a log file. For example, the
make
utility executes theSampleApp1
class and writes the output tosample1.out
:cd ./Sample1; $(JAVA_HOME)/bin/java -classpath "$(MAKE_CLASSPATH)" \SampleApp1 > sample1.out
-
Using the JAXB Class Generator Command-Line Utility
XDK includes orajaxb
, which is a command-line Java interface that generates Java classes from input XML schemas. Shell scripts $ORACLE_HOME/bin/orajaxb
and %ORACLE_HOME%\bin\orajaxb.bat
execute class oracle.xml.jaxb.orajaxb
.
To use orajaxb
ensure that your CLASSPATH
is set as described in Setting Up the XDK for Java Environment.
Table 18-3 lists the orajaxb
command-line options.
Table 18-3 orajaxb Command-Line Options
Option | Purpose |
---|---|
- |
Prints the help message. |
- |
Prints the release version. |
- |
Specifies the directory in which to generate the Java source files. If the schema has a namespace, then the program generates the java code in the package (corresponding to the namespace) referenced from the outputDir. By default, the current directory is the |
- |
Specifies the input XML schema. |
- |
Specifies the target package name. This option overrides any binding customization for package name, and also the default package name algorithm defined in the JAXB specification. |
- |
Generates only the interfaces. |
- |
Lists the generated classes and interfaces. |
- |
Generates the default customization file. |
- |
Allows vendor specific extensions and does not strictly follow the compatibility rules specified in Appendix E.2 of the JAXB 1.0 specification. When specified, the program ignores JAXB 1.0 unsupported features such as notations, substitution groups, and any attributes. |
Using the JAXB Class Generator Command-Line Utility: Example
An example shows how to use the JAXB class generator command-line utility.
To test orjaxb
, change to directory $ORACLE_HOME/xdk/demo/java/jaxb/Sample1
. If you have run make
then the directory contains these files:
SampleApp1.class
SampleApp1.java
generated/
sample1.out
sample1.xml
sample1.xsd
File sample.xsd
is the XML schema associated with XML document sample1.xml
. Subdirectory generated/
contains the classes generated from the input schema. You can test orajaxb
by deleting the contents of generated/
and regenerating the classes.
rm generated/*
orajaxb -schema sample1.xsd -targetPkg generated -verbose
The terminal displays this output:
generated/CType.java
generated/AComplexType.java
generated/AnElement.java
generated/RElemOfCTypeInSameNs.java
generated/RType.java
generated/RElemOfSTypeInSameNs.java
generated/CTypeImpl.java
generated/AComplexTypeImpl.java
generated/AnElementImpl.java
generated/RElemOfCTypeInSameNsImpl.java
generated/RTypeImpl.java
generated/RElemOfSTypeInSameNsImpl.java
generated/ObjectFactory.java
Processing XML with the JAXB Class Generator
Topics include binding complex types and customizing a class name in a top-level element.
Binding Complex Types
Sample3.java
shows how to bind a complex type definition to a Java content interface. One complex type defined in the XML schema is derived by extension from another complex type.
Defining the Schema to Validate sample3.xml
An XML schema, schema3.xsd
, is defined for validating XML document schema3.xml
.
Example 18-1 shows the XML data document that provides the input to the sample application. The sample3.xml
document describes the address of an employee.
The XML schema shown in Example 18-2 defines the structure that you use to validate sample3.xml
. The schema defines two complex types and one element, which are defined:
-
The first complex type, which is named
Address
, is a sequence of elements. Each element in the sequence describes one part of the address: name, door number, and so forth. -
The second complex type, which is named
USAddress
, uses the<extension base="exp:Address">
element to extendAddress
by adding US-specific elements to theAddress
sequence: state, zip, and so forth. Theexp
prefix specifies thehttp://www.oracle.com/sample3/
namespace. -
The element is named
myAddress
and is of typeexp:USAddress
. Theexp
prefix specifies thehttp://www.oracle.com/sample3/
namespace. Insample3.xml
, themyAddress
top-level element, which is in namespacehttp://www.oracle.com/sample3/
, conforms to the schema definition.
Example 18-1 sample3.xml
<?xml version="1.0"?> <myAddress xmlns = "http://www.oracle.com/sample3/" xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation = "http://www.oracle.com/sample3 sample3.xsd"> <name>James Bond</name> <doorNumber>420</doorNumber> <street>Oracle parkway</street> <city>Redwood shores</city> <state>CA</state> <zip>94065</zip> <country>United States</country> </myAddress>
Example 18-2 sample3.xsd
<?xml version="1.0"?> <!-- Binding a complex type definition to java content interface The complex type definition is derived by extension --> <schema xmlns = "http://www.w3.org/2001/XMLSchema" xmlns:exp="http://www.oracle.com/sample3/" targetNamespace="http://www.oracle.com/sample3/" elementFormDefault="qualified"> <complexType name="Address"> <sequence> <element name="name" type="string"/> <element name="doorNumber" type="short"/> <element name="street" type="string"/> <element name="city" type="string"/> </sequence> </complexType> <complexType name="USAddress"> <complexContent> <extension base="exp:Address"> <sequence> <element name="state" type="string"/> <element name="zip" type="integer"/> <element name="country" type="string"/> </sequence> </extension> </complexContent> </complexType> <element name="myAddress" type="exp:USAddress"/> </schema>
Generating and Compiling the Java Classes
If you have an XML document and corresponding XML schema, then the next stage of processing is to generate the Java classes from the XML schema.
You can use the JAXB command-line interface described in Using the JAXB Class Generator Command-Line Utility to perform this task.
Assuming that your environment is set up as described in Setting Up the XDK for Java Environment, you can create the source files in the generated
package:
cd $ORACLE_HOME/xdk/demo/java/jaxb/Sample3 orajaxb -schema sample1.xsd -targetPkg generated
The preceding orajaxb
command creates these source files in the ./generated/
subdirectory:
Address.java AddressImpl.java MyAddress.java MyAddressImpl.java ObjectFactory.java USAddress.java USAddressImpl.java
The complex types Address
and USAddress
each has two associated source files, as does the element MyAddress
. The source file named after the element contains the interface; the file with the suffix Impl
contains the class that implements the interface. For example, Address.java
contains the interface Address
, whereas AddressImpl.java
contains the class that implements Address
.
The content of the Address.java
source file is shown in Example 18-3.
The Address
complex type defined a sequence of elements: name
, doorNumber
, street
, and city
. Consequently, the Address
interface includes a get
and set
method signature for each of the four elements. For example, the interface includes getName()
for retrieving data in the <name>
element and setName()
for modifying data in this element.
You can compile the Java source files with javac
:
cd $ORACLE_HOME/xdk/demo/java/jaxb/Sample3/generated javac *.java
Example 18-3 Address.java
package generated; public interface Address { public void setName(java.lang.String n); public java.lang.String getName(); public void setDoorNumber(short d); public short getDoorNumber(); public void setStreet(java.lang.String s); public java.lang.String getStreet(); public void setCity(java.lang.String c); public java.lang.String getCity(); }
Processing the XML Data in sample3.xml
Sample3.java
unmarshals an XML data document, marshals it, and uses the generated classes to print and modify the address data.
It shows how you can process the sample3.xml
document by using the Java class files that you generated in Generating and Compiling the Java Classes.
The Sample3.java
program processes the data as follows:
Customizing a Class Name in a Top-Level Element
The Sample10.java
program shows one form of JAXB customization. The program shows you can change the name of a class that corresponds to an element in the input XML schema.
Defining the Schema to Validate schema10.xml
An XML schema, schema10.xsd
, is defined for validating XML document schema10.xml
.
Example 18-4 shows the XML data document that provides the input to the sample application. The sample10.xml
document describes a business.
Example 18-5 shows the XML schema that defines the structure of sample10.xml
. The schema defines one complex type and one element as follows:
-
The complex type, which is named
businessType
, is a sequence of elements. Each element in the sequence describes a part of the business: title, owner, and id. -
The element, which is named
business
, is of typebiz:businessType
. Thebiz
prefix specifies thehttp://jaxbcustomized/sample10/
namespace. Insample10.xml
, thebusiness
top-level element, which is in namespacehttp://jaxbcustomized/sample10/
, conforms to the schema definition.
Example 18-4 sample10.xml
<?xml version="1.0"?> <business xmlns="http://jaxbcustomized/sample10/"> <title>Software Development</title> <owner>Larry Peterson</owner> <id>45123</id> </business>
Example 18-5 sample10.xsd
<?xml version="1.0"?> <!-- Customization of class name in top level element --> <schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="http://jaxbcustomized/sample10/" xmlns:biz="http://jaxbcustomized/sample10/" xmlns:jaxb="http://java.sun.com/xml/ns/jaxb" jaxb:version="1.0" elementFormDefault="qualified"> <element name="business" type="biz:businessType"> <annotation> <appinfo> <jaxb:class name="myBusiness"/> </appinfo> </annotation> </element> <complexType name="businessType"> <sequence> <element name="title" type="string"/> <element name="owner" type="string"/> <element name="id" type="integer"/> </sequence> </complexType> </schema>
Customizing the Schema Binding
Binding customizations used in XML schema sample10.xsd
are described.
The schema shown in Example 18-5 customizes the binding of the business
element with an inline binding declaration. The general form for inline customizations is:
<xs:annotation> <xs:appinfo> . . binding declarations . . </xs:appinfo> </xs:annotation>
Example 18-5 uses the <class>
binding declaration to bind a schema element to a Java class name. You can use the declaration to customize the name for an interface or the class that implements an interface. The JAXB class generator supports this syntax for <class>
customizations:
<class [ name = "className"] >
The name
attribute specifies the name of the derived Java interface. Example 18-5 contains this customization:
<jaxb:class name="myBusiness"/>
Thus, the schema binds the business
element to the interface myBusiness
rather than to the interface business
, which is the default.
Generating and Compiling the Java Classes
After you have an XML document and corresponding XML schema, the next stage is to generate the Java classes from the XML schema. You can use the JAXB command-line interface to perform this task.
If your environment is set up as described in Setting Up the XDK for Java Environment, then you can create the source files in the generated
package:
cd $ORACLE_HOME/xdk/demo/java/jaxb/Sample10 orajaxb -schema sample10.xsd
Because the preceding command does not specify a target package, the package name is constructed from the target namespace of the schema, which is http://jaxbcustomized/sample10/
. Consequently, the utility generates these source files in the ./jaxbcustomized/sample10/
subdirectory:
BusinessType.java BusinessTypeImpl.java MyBusiness.java MyBusinessImpl.java ObjectFactory.java
The complex type businessType
has two source files, BusinessType.java
and BusinessTypeImpl.java
. Because of the JAXB customization, the business
element is bound to interface MyBusiness
and implementing class MyBusinessImpl
.
The content of the BusinessType.java
source file is shown in Example 18-6.
The BusinessType
complex type defined a sequence of elements: title
, owner
, and id
. Consequently, the Address
interface includes a get
and set
method signature for each of the elements. For example, the interface includes getTitle()
for retrieving data in the <title>
element and setTitle()
for modifying data in this element.
You can compile the Java source files with javac
:
cd $ORACLE_HOME/xdk/demo/java/jaxb/Sample10/jaxbcustomized/sample10 javac *.java
Example 18-6 BusinessType.java
package jaxbcustomized.sample10; public interface BusinessType { public void setTitle(java.lang.String t); public java.lang.String getTitle(); public void setOwner(java.lang.String o); public java.lang.String getOwner(); public void setId(java.math.BigInteger i); public java.math.BigInteger getId(); }
Processing the XML Data in sample10.xml
Sample10.java
unmarshals an XML document, prints its content, and marshals the XML to standard output.
Sample10.java
shows how you can process the data in the sample10.xml
document by using the class files that you generated in Generating and Compiling the Java Classes.
The Sample10.java
program processes the XML data as follows: