6 Using JAXB Class Generator

This chapter contains these topics:

• What Is JAXB?

• Replacing the XML Class Generator with JAXB Class Generator

• Unmarshalling, Marshalling, and Validating Using JAXB

• Using JAXB Class Generator

• Features Not Supported in JAXB

• JAXB Class Generator Command-Line Interface

• JAXB Compared with JAXP

What Is JAXB?

Java Architecture for XML Binding (JAXB) consists of an API and tools that map to and from XML data and Java objects. It is an implementation of the JSR-31 "The Java Architecture for XML Binding (JAXB)", Version 1.0, recommendation of the JCP (Java Community Process). JSR is a Java Specification Request of the JCP.

The JAXB compiler generates the interfaces and the implementation classes corresponding to the XML Schema. The classes can be used to read, manipulate and re-create XML documents. The JAXB compiler generates Java classes corresponding to an XML Schema, and interfaces that are needed to access XML data. The Java classes, which can be extended, give you access to the XML data without any specific knowledge about the underlying data structure.

Note: The JAXB specification is described at http://java.sun.com/xml/jaxb/ JSR is described at http://jcp.org/en/jsr/overview

Replacing the XML Class Generator with JAXB Class Generator

You are requested to use JAXB Class Generator for new applications in order to use the object binding feature for XML data. The Oracle9i Class Generator for Java is deprecated. However, the Oracle9i Class Generator runtime was included in release 10.1 and is supported for the duration of the 10.x releases.

Unmarshalling, Marshalling, and Validating Using JAXB

Unmarshalling is defined as moving data from an XML document to the Java generated class objects. Each object is derived from an instance of the schema component in the input document. Because of the inherent weaknesses of DTDs, they are not supported by JAXB, but a DTD can be converted to an XML Schema that is then used by JAXB.

Marshalling is defined as creating an XML document from Java objects by traversing a content tree of instances of Java classes.

Validation is a prerequisite to marshalling if content has changed in the Java representation. Validation is verifying that the content tree satisfies the constraints defined in the schema. The tree is defined as valid when marshalling the tree generates a document that is valid according to the source schema. If unmarshalling includes validation that is error-free then the input document and the content tree are valid. However, validation is not required during unmarshalling.

Validation comes in these forms:

• Unmarshalling-time validation notifies the application of errors and warnings during unmarshalling.

• On-demand validation on a Java content tree when the application initiates it.

• Fail-fast validation that gives immediate results.

Using JAXB Class Generator

To build a JAXB application, start with an XML Schema file. Build and use a JAXB application by performing these steps:

1. Generate the Java source files by submitting the XML Schema file to the binding compiler. The binding compiler could be invoked through the command-line utility called orajaxb.

2. Compile the Java source code using JDK 1.3 or higher.

3. With the classes and the binding framework, write Java applications that:

   • Build object trees representing XML data that is valid against the XML Schema by either unmarshalling the data from a document or instantiating the classes you created.

   • Access and modify the data.

   • Optionally validate the modifications to the data relative to the constraints expressed in the XML Schema.

   • Marshal the data to new XML documents.

     
     

     See Also: http://java.sun.com/xml/jaxb/faq.html for more information on JAXB

     
     

Features Not Supported in JAXB

The Oracle release does not support the following:

• The Javadoc generation.

• The List and Union features of XML Schema.

• SimpleType mapping to TypeSafe Enum class and IsSet property modifier.

• XML Schema component "any" and substitution groups.

• Customization of XML Schema to override the default binding of XML Schema components.

• On-demand validation of content tree.

JAXB Class Generator Command-Line Interface

The JAXB class generator command-line interface is accessed this way:

oracle.xml.jaxb.orajaxb [-options]

where the options are listed in Table 6-1:

Table 6-1 JAXB Class Generator Command-line Interface

Option	Description
-help	Prints the help message text
-version	Prints the release version
-outputDir OutputDir	The directory in which to generate Java source
-schema SchemaFile	The input schema file
-targetPkg targetPkg	The target package name
-interface	Generate only the interfaces

JAXB Compared with JAXP

The following lists summarize the advantages of JAXB.

Use JAXB when you want to:

• Access data in memory, but do not need DOM tree manipulation capabilities.

• Build object representations of XML data.

For more information about JAXB:

See Also: Code examples are found with the XDK download and with the JAXB code at $INSTALL_HOME/xdk/demo/java.101/jaxb http://java.sun.com/xml/jaxb/ for documentation and examples of the use of JAXB Oracle XML API Reference for details of the JAXB API

The Java API for XML Processing (JAXP), that enables applications to parse and transform XML documents using an API that is independent of a particular XML processor implementation, is implemented by Oracle.

See Also: "Using JAXP"

Use JAXP when you want to:

• Have flexibility with regard to the way you access the data: either serially with SAX or randomly in memory with DOM.

• Use your same processing code with documents based on different schemas.

• Parse documents that are not necessarily valid.

• Apply XSLT transforms.

• Insert or remove objects from an object tree that represents XML data.