Java Architecture for XML Binding (JAXB)

From: http://www.oracle.com/technetwork/articles/javase/index-140168.html


You will find the following topics covered in this article:

What's JAXB?

An Example: Accessing an XML Document

Bind the Schema

Unmarshal the Document

Another Example: Building an XML Document

Bind the Schema

Create the Content Tree

Marshal the Content Tree

A Final Example: Updating an XML Document

Binding Can Be Customized

Distinct Advantages

Run the Examples

What's JAXB?

XML and Java technology are recognized as ideal building blocks for developing Web services and applications that access Web services. A new Java API called Java Architecture for XML Binding (JAXB) can make it easier to access XML documents from applications written in the Java programming language.

The
Extensible Markup Language (XML)
and Java technology are natural partners in helping developers exchange
data and programs across the Internet. That's because XML has emerged
as the standard for exchanging data across disparate systems, and Java
technology provides a platform for building portable applications. This
partnership is particularly important for Web services, which promise
users and application developers program functionality on demand from
anywhere to anywhere on the Web. XML and Java technology are recognized
as ideal building blocks for developing Web services and applications
that access Web services.

But how do you
couple these partners in practice? More specifically, how do you access
and use an XML document (that is, a file containing XML-tagged data)
through the Java programming language? One way to do this, perhaps the
most typical way, is through parsers that conform to the
Simple API for XML (SAX)
or the
Document Object Model (DOM)
. Both of these parsers are provided by
Java API for XML Processing (JAXP)
.
Java developers can invoke a SAX or DOM parser in an application
through the JAXP API to parse an XML document -- that is, scan the
document and logically break it up into discrete pieces. The parsed
content is then made available to the application. In the SAX approach,
the parser starts at the beginning of the document and passes each piece
of the document to the application in the sequence it finds it. Nothing
is saved in memory. The application can take action on the data as it
gets it from the parser, but it can't do any in-memory manipulation of
the data. For example, it can't update the data in memory and return the
updated data to the XML file.

In the DOM
approach, the parser creates a tree of objects that represents the
content and organization of data in the document. In this case, the tree
exists in memory. The application can then navigate through the tree to
access the data it needs, and if appropriate, manipulate it.

Now developers have another Java API at their disposal that can make it easier to access XML documents:
Java Architecture for XML Binding (JAXB)
. A Reference Implementation of the API is now available in the
Java Web Services Developer Pack V 1.1
.

Let's look at JAXB in action, and compare it to SAX and DOM-based processing.

An Example: Accessing an XML Document

Suppose you need to develop a Java application that accesses and displays data in XML documents such as
books.xml
.
These documents contain data about books, such as book name, author,
description, and ISBN identification number. You could use the SAX or
DOM approach to access an XML document and then display the data. For
example, suppose you took the SAX approach. In that case, you would need
to:

Write a program that creates a SAX parser and then uses
that parser to parse the XML document. The SAX parser starts at the
beginning of the document. When it encounters something significant (in
SAX terms, an "event") such as the start of an XML tag, or the text
inside of a tag, it makes that data available to the calling
application.

Create a content handler that defines the methods to be
notified by the parser when it encounters an event. These methods,
known as callback methods, take the appropriate action on the data they
receive.

As an example,
here
is a program that uses JAXP to create and use a SAX parser to parse an XML document. The program uses a content handler,

MyContentHandler

, to display the data passed to it by the SAX parser.

JAXB allows Java developers to access and process XML data without having to know XML or XML processing. For example, there's no need to create or use a SAX parser or write callback methods.

Now let's look at how you use JAXB to access an XML document such as

books.xml

and display its data. Using JAXB, you would:

Bind the schema
for the XML document.

Unmarshal the document
into Java content objects. The Java content objects represent the
content and organization of the XML document, and are directly available
to your program.

After
unmarshalling, your program can access and display the data in the XML
document simply by accessing the data in the Java content objects and
then displaying it. There is no need to create and use a parser and no
need to write a content handler with callback methods. What this means
is that developers can access and process XML data without having to
know XML or XML processing.

Bind the Schema

JAXB
simplifies access to an XML document from a Java program by presenting
the XML document to the program in a Java format. The first step in this
process is to bind the schema for the XML document into a set of Java
classes that represents the schema.

Schema
:
A schema is an XML specification that governs the allowable components
of an XML document and the relationships between the components. For
example, a schema identifies the elements that can appear in an XML
document, in what order they must appear, what attributes they can have,
and which elements are subordinate (that is, are child elements) to
other elements. An XML document does not have to have a schema, but if
it does, it must conform to that schema to be a valid XML document. JAXB
requires that the XML document you want to access has a schema, and
that schema is written in the
W3C XML Schema Language
(see the box "Why W3C XML Schema Language?").

Assume, for this example, that the

books.xml

document has a schema,
books.xsd
, that is written in the W3C XML Schema Language. This schema defines a

<Collection>

as an element that has a complex type. This means that it has child elements, in this case,

<book>

elements. Each

<book>

element also has a complex type named

bookType

. The

<book>

element has child elements such as

<name>

,

<ISBN>

, and

<author>

. Some of these have their own child elements.

Why W3C XML Schema Language? The W3C XML Schema Language is not the only schema language. In fact, the XML specification describes document-type definitions (DTDs) as the way to express a schema. In addition, pre-release versions of the JAXB Reference Implementation worked only with DTDs -- that is, not with schemas written in the XML Schema Language. However, the XML Schema Language is much richer than DTDs. For example, schemas written in the XML Schema Language can describe structural relationships and data types that can't be expressed (or can't easily be expressed) in DTDs. There are tools available to convert DTDs to the W3C XML Schema Language, so if you have DTD-based schemas that you used with an earlier version of the JAXB Reference Implementation, you can use these tools to convert the schemas to XML Schema Language.

Binding
:
Binding a schema means generating a set of Java classes that represents
the schema. All JAXB implementations provide a tool called a binding
compiler to bind a schema (the way the binding compiler is invoked can
be implementation-specific). For example, the JAXB Reference
Implementation provides a binding compiler that you can invoke through
scripts. Suppose, for example, you want to bind the

books.xsd

schema using the binding compiler
provided by the JAXB Reference Implementation. Suppose too that you're
working in the Solaris Operating Environment. Here's a command you can
use to run the script that binds the schema:

xjc.sh -p test.jaxb books.xsd -d work

The

-p

option identifies a package for the generated classes, and the

-d

option identifies a target directory. So for this command, the classes are packaged in

test.jaxb

within the

work

directory.

In response, the
binding compiler generates a set of interfaces and a set of classes that
implement the interfaces. Here are the interfaces it generates for the

books.xsd

schema:

CollectionType.java

. Represents the unnamed complex type for the

<Collection>

element.

Collection.java

. Represents the

<Collection>

element.

BookType.java

. Represents the

BookType

complex type.

ObjectFactory.java

. Contains methods for generating instances of the interfaces.

Here are the classes that implement the interfaces (these are generated in an

impl

subdirectory). Note that these classes are
implementation-specific -- in this example, they are specific to the
Reference Implementation. Because the classes are
implementation-specific, classes generated by the binding compiler in
one JAXB implementation will probably not work with another JAXB
implementation. So if you change to another JAXB implementation, you
should rebind the schema with the binding compiler provided by that
implementation.

impl/CollectionTypeImpl.java

. Implements the

CollectionType

interface described in

CollectionType.java

.

impl/CollectionImpl.java

. Implements the

Collection

interface described in

Collection.java

.

impl/BookTypeImpl.java

. Implements the

BookType

interface described in

BookType.java

.

In total, the generated classes represent the entire

books.xsd

schema. Notice that the classes define

get

and

set

methods that are used to respectively obtain and specify data for each type of element and attribute in the schema.

You then compile the generated interfaces and classes. For example:

javac test/jaxb/*.java  test/jaxb/impl/*.java

This compiles all of the interfaces and classes in the

test.jaxb

package generated by the binding compiler.

Unmarshal the Document

Unmarshalling
an XML document means creating a tree of content objects that
represents the content and organization of the document. The content
tree is not a DOM-based tree. In fact, content trees produced through
JAXB can be more efficient in terms of memory use than DOM-based trees.

The
content objects are instances of the classes produced by the binding
compiler. In addition to providing a binding compiler, a JAXB
implementation must provide runtime APIs for JAXB-related operations
such as marshalling. The APIs are provided as part of a binding
framework. The binding framework comprises three packages. The primary
package,

javax.xml.bind

, contains classes and interfaces
for performing operations such as unmarshalling, marshalling, and
validation (marshalling and validation will be covered later). A second
package,

javax.xml.bind.util

, contains a number of utility classes. The third package,

javax.xml.bind.helper

, is designed for JAXB implementation providers.

To unmarshal an XML document, you:

Create a

JAXBContext

object. This object provides the
entry point to the JAXB API. When you create the object, you need to
specify a context path. This is a list of one or more package names that
contain interfaces generated by the binding compiler. By allowing
multiple package names in the context path, JAXB allows you to unmarshal
a combination of XML data elements that correspond to different
schemas.

For example, the following code snippet creates a

JAXBContext

object whose context path is

test.jaxb

, the package that contains the interfaces generated for the

books.xsd

schema:

import javax.xml.bind.JAXBContext;

JAXBContext jc = JAXBContext.newInstance("test.jaxb");

Create an

Unmarshaller

object. This object controls the
process of unmarshalling. In particular, it contains methods that
perform the actual unmarshalling operation. For example, the following
code snippet creates an

Unmarshaller

object:

import javax.xml.bind.Unmarshaller;

Unmarshaller unmarshaller = jc.createUnmarshaller();

Call the

unmarshal

method. This method does the actual
unmarshalling of the XML document. For example, the following statement
unmarshals the XML data in the

books.xml

file:

Collection collection= (Collection)
unmarshaller.unmarshal(new File( "books.xml"));

Note that a

Collection

here is a

test.jaxb.Collection

, not a

java.util.Collection

.

Use the

get

methods in the schema-derived classes to
access the XML data. Recall that the classes that a JAXB compiler
generates for a schema include

get

and

set

methods you can use to respectively
obtain and specify data for each type of element and attribute in the
schema. For example, the following statement gets the data in the

books

and

book

elements:

CollectionType.BooksType booksType = collection.getBooks();
List bookList = booksType.getBook();

After obtaining the data, you can display it directly from your program. Here, for example, is a
program
that unmarshals the data in the

books.xml

file and then displays the data. If you run the program, you should see the following result:

Book details Item id: 999 Book Name: Learning JAXB Book ISBN: 123445 Book Price: 34 $ Book category: other Book promotion: 10% on this book if purchased by March 2003 No of Authors 1 Author Name Jane Doe Book details Item id: 129 Book Name: Java Webservices today and Beyond Book ISBN: 522965 Book Price: 29 $ Book category: magazine Book promotion: Buy one get Learning webservices Part 1 free No of Authors 2 Author Name John Brown Author Name Peter T.

Validating the Source Data
: Notice that the program includes the following statement:

unmarshaller.setValidating(true);

You can validate source data against an associated schema as part of the unmarshalling operation.

This
statement highlights an important feature of JAXB: you can have it
validate the source data against the associated schema as part of the
unmarshalling operation. In this case, the statement asks JAXB to
validate the source data against its schema. If the data is found to be
invalid (that is, it doesn't conform to the schema) the JAXB
implementation can report it and might take further action. JAXB
providers have a lot of flexibility here. The JAXB specification
mandates that all provider implementations report validation errors when
the errors are encountered, but the implementation does not have to
stop processing the data. Some provider implementations might stop
processing when the first error is found, others might stop even if many
errors are found. In other words, it is possible for a JAXB
implementation to successfully unmarshal an invalid XML document, and
build a Java content tree. However, the result won't be valid. The main
requirement is that all JAXB implementations must be able to unmarshal
valid documents.

You also
have the flexibility of turning the validation switch off if you don't
want to incur the additional validation processing overhead.

Unmarshalling Other Sources
:
Although the example described in this section shows how to unmarshal
XML data in a file, you can unmarshal XML data from other input sources
such as an

InputStream object

, a URL, or a DOM node. You can even unmarshal transformed XML data. For example, you can unmarshal a

javax.xml.transform.sax.SAXSource

object. You
can also unmarshal SAX events -- in other words, you can do a SAX parse
of a document and then pass the events to JAXB for unmarshalling.

An Alternative: Accessing Data without Unmarshalling
: JAXB also allows you to access XML data without having to unmarshal it. One of the classes generated from a schema,

ObjectFactory

, contains methods to generate
objects for each of the schema-derived interfaces and classes. For
example, the package generated for the

books.xsd

schema includes an

ObjectFactory

class that has methods such as

createCollection

to create a

Collection

object, and

createBookType

to create a

BookType

object. You can use these methods to
create a tree of content objects without doing any unmarshalling. All
your program needs is access to the

ObjectFactory

class that's in the package for the pertinent schema. Then you can use the appropriate methods in the

ObjectFactory

class to create the objects you
need. After you create the objects, you need to provide their content.
To do that, you use the

set

methods in the objects.

Another Example: Building an XML Document

Instead
of accessing data in an XML document, suppose you need to build an XML
document through a Java application. Here too using JAXB is easier.
Let's investigate.

You could
use the DOM approach to build an XML document, but not SAX. That's
because you would need to build and populate the content of the document
in memory -- recall that SAX does not allow you to perform any
in-memory manipulation of data. Using the DOM approach, your program
needs to create and use DOM objects and methods to build the document.
DOM is designed to represent the content and organization of data in a
document as a tree of objects. To build the document, your program uses
DOM to create a

Document

object that represents the document. Your program then uses

Document

object methods to create other objects
that represent the nodes of the tree. Each node contains content for
the XML document. You then append the nodes in an order that reflects
the organization of the tree. In other words, your program uses DOM
object methods to create a root node, and append the root node to the

Document

object. Then it creates child nodes
and appends them to the root node. If a child node has children of its
own, your program uses DOM object methods to create those nodes and
append them to their parent node.

Unlike the SAX
approach, there is no need in DOM to write a content handler and
callback methods. However the DOM approach requires you to understand
the organization of the document tree. In fact, if you use DOM to access
data, you create a parser that builds a tree, and then you use DOM
methods to navigate to the appropriate object in the tree that contains
the data you need. So an understanding of the tree's organization is a
requirement. Compare this to JAXB, where you have direct access to
unmarshalled XML data through objects in the content tree. As in
DOM-based processing, JAXB allows access to data in non-sequential
order, but it doesn't force an application to navigate through a tree to
access the data. In addition, with all the creating and appending of
objects that represent the nodes of the tree, the DOM approach can be
tedious.

Here
,
for example, is a program that uses DOM to build and populate a
document, and then write the document to an XML file. Notice that the
type of data that gets populated into the document is similar to the
data in the

books.xml

file that was used in the first example,
Accessing an XML Document
. In fact, the program validates the document it builds against the
books.xsd
schema that was used in the first example.

As in DOM-based processing, JAXB allows access to data in non-sequential order, but it doesn't force an application to navigate through a tree to access the data.

Now let's look at how you use JAXB to build the same document, validate it against the

books.xsd

schema, and write the document to an XML file. Using JAXB, you would:

Bind the schema
for the XML document (if it isn't already bound).

Create the content tree
.

Marshal the content tree
into the XML document.

In this process, you don't deal with the intricacies of the DOM object model or even need to know XML.

Bind the Schema

This is the
same operation
you perform prior to unmarshalling a document. In this case, the schema
is for the XML document you want to build. Of course, if you've already
bound the schema (for instance, you unmarshalled an XML document,
updated the data, and now want to write the updated data back to the XML
document), you don't have to bind the schema again.

Create the Content Tree

The
content tree represents the content that you want to build into the XML
document. You can create the content tree by unmarshalling XML data, or
you can create it using the

ObjectFactory

class that's generated by binding the appropriate schema. Let's use the

ObjectFactory

approach. First, create an instance of the

ObjectFactory

class:

ObjectFactory objFactory = new ObjectFactory();

Next, use

create

methods in the

ObjectFactory

object to create each of the objects in the content tree. For example:

Collection collection= (Collection) objFactory.createCollection(); Collection.BooksType booksType = objFactory. createCollectionTypeBooksType(); BookType book = objFactory.createBookType();

Then use

set

methods in the created objects to specify data values. For example:

book.setItemId("307");
book.setName("JAXB today and beyond");

Marshal the Content Tree

Marshalling is the opposite of unmarshalling. It creates an XML document from a content tree. To marshal a content tree, you:

Create a

JAXBContext

object, and specify the
appropriate context path -- that is, the package that contains the
classes and interfaces for the bound schema. As is the case for
unmarshalling, you can specify multiple package names in the context
path. That gives you a way of building an XML document using a
combination of XML data elements that correspond to different schemas.

import javax.xml.bind.JAXBContext;

JAXBContext jaxbContext = JAXBContext.newInstance("test.jaxb");

Create a

Marshaller

object. This object controls the
process of marshalling. In particular, it contains methods that perform
the actual marshalling operation.

import javax.xml.bind.Marshaller;

Marshaller marshaller = jaxbContext.createMarshaller();

The

Marshaller

object has properties that you can set through the

setProperty

method. For example, you can specify the output encoding to be used when marshalling the XML data. Or you can tell the

Marshaller

to format the resulting XML data
with line breaks and indentation. The following statement turns this
output format property on -- line breaks and indentation will appear in
the output format:

marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT,
new Boolean(true));

Call the

marshal

method. This method does the actual
marshalling of the content tree. When you call the method, you specify
an object that contains the root of the content tree, and the output
target. For example, the following statement marshals the content tree
whose root is in the

collection

object and writes it as an output stream to the XML file

jaxbOutput.xml

:

marshaller.marshal(collection,
new FileOutputStream("jaxbOutput.xml"));

Here, for example, is a
program
that creates a content tree, fills it with data, and then marshals the content tree to an XML file.

Validating the Content Tree
:
Notice that validation is not performed as part of the marshalling
operation. In other words, unlike the case for unmarshalling, there is
no

setValidating

method for marshalling. Instead, when marshalling data, you use the

Validator

class that is a part of the binding framework to validate a content tree against a schema. For example:

import javax.xml.bind.Validator;

Validator validator = jaxbContext.createValidator();
validator.validate(collection));

Validating
the data as a separate operation from marshalling gives you a lot of
flexibility. For example, you can do the validating at one point in
time, and do the marshalling at another time. Or you can do some
additional processing in between the two operations. Note that the JAXB
specification doesn't require a content tree to be valid before it's
marshalled. That doesn't necessarily mean that a JAXB implementation
will allow invalid data to be marshalled -- it might marshal part or all
of the invalid data, or not. But all JAXB implementations must be able
to marshal valid data.

Marshalling to Other Targets
:
Although the example described in this section shows how to marshal
data to an XML file, you can marshal to other output formats such as an

OutputStream

object or a DOM node. You can also marshal to a transformed data format such as

javax.xml.transform.SAXResult

. You can even marshal to a content handler. This allows you to process the data as SAX events.

A Final Example: Updating an XML Document

Here's
a final example, one that logically combines elements of accessing an
XML document and building an XML document. Suppose you need to update an
XML document. In the DOM approach, you would create and use a DOM
parser to navigate to the appropriate object in the tree that contains
the data you need, update the data, and then write the updated data to
an XML file. Here, for example, is a
program
that uses DOM to update an XML document. As discussed in
Building an XML Document
, the DOM approach is relatively tedious and forces you to know the organization of the content tree.

Here, by comparison, is a
JAXB program
that updates an XML document. Specifically, it updates an unmarshalled
content tree and then marshals it back to an XML document. Notice how
JAXB simplifies the process. The program has direct access to the object
it needs to update. The program uses a

get

method to access the data it needs, and a

set

method to update the data.

Although it's
tempting to think that the XML data can make a "roundtrip" unchanged,
there's no guarantee of that. In other words, if you use JAXB to
unmarshal an XML document and then marshal it back to the same XML file,
there's no guarantee that the XML document will look exactly the same
at it did originally. For example, the indentation of the resulting XML
document might be a bit different than the original. The JAXB
specification does not require the preservation of the XML information
set in a roundtrip from XML document-to-Java representation-to XML
document. But it also doesn't forbid the preserving of it.

Binding Can Be Customized

The JAXB specification describes the default behavior for binding a subset of XML schema components to Java components. However JAXB allows you to annotate a schema with binding declarations that override or extend the default binding behavior.

The
JAXB specification describes the default behavior for binding a subset
of XML schema components to Java components. The specification
identifies which XML schema components must be bound and to what Java
representations these components are bound. For example, the XML
built-in datatype

xsd:string

must be bound to the Java data type

java.lang.String

. All JAXB compiler
implementations must implement the default binding specifications.
However there are times when the default behavior might not be what you
want. For example, suppose you want an XML data type mapped to a Java
data type that is different than the type called for by the default
binding specification. Or you want the binding compiler to assign a name
of your choice to a class that it generates.

To meet these and
other customization needs, JAXB allows you to annotate a schema with
binding declarations that override or extend the default binding
behavior. JAXB allows these declarations to be made "inline" -- that is,
in the schema, or in a separate document.

Let's look at a customization example.
Here
is an annotated version of the

books.xsd

schema that was used in the previous examples. The annotations in this example are inline.

Notice the

annotation

element near the top of the schema:

<xs:annotation> <xs:appinfo> <jaxb:globalBindings generateIsSetMethod="true"> bindingStyle="modelGroupBinding" choiceContentProperty="true" > <xjc:serializable uid="12343"/> <jaxb:javaType name="short" xmlType="xs:long" printMethod="javax.xml.bind.DatatypeConverter.printShort" parseMethod="javax.xml.bind.DatatypeConverter.parseShort"/> </jaxb:globalBindings> </xs:appinfo> </xs:annotation>

All binding declarations are in an

annotation

element and its subordinate

appinfo

element. In fact, all inline binding declarations must be made this way.

This block of code demonstrates a number of customizations that you can make to a schema:

Make global customizations
: The

<jaxb:globalBindings ...>

element
specifies binding declarations that have global scope. In JAXB, binding
declarations can be specified at different levels, or "scopes." Each
scope inherits from the scopes above it, and binding declarations in a
scope override binding declarations in scopes above it. Global scope is
at the top of the scope hierarchy. It covers all the schema elements in
the source schema and (recursively) any schemas that are included or
imported by the source schema. Global scope is followed in the hierarchy
by Schema scope (covers all the schema elements in the target namespace
of a schema), Definition scope (covers all schema elements that
reference a specified type definition or a global declaration), and
Component scope (applies only to a specific schema element that was
annotated with a binding declaration).

Notice that the namespace prefix (

jaxb

) for the

<globalBindings>

element is bound to http://java.sun.com/xml/ns/jaxb. This URI contains the core schema for binding declarations.

Add method signatures
. The declaration

generateIsSetMethod="true"

tells the binding compiler to generate

isSet

methods for the properties of all
generated classes. These methods are used to determine if a property in a
class is set or has a default value.

Change binding style
.
By default, schema components that have complex types and that have a
content type property of mixed or element-only are bound with a style
called element binding. In element binding, each element in the complex
type is mapped to a unique content property. Alternatively, you can
change the binding style to model group binding by specifying

bindingStyle="modelGroupBinding" choiceContentProperty="true"

.
In model group binding, schema components that have complex type and
that are nested in the schema are mapped to Java interfaces. This gives
users a way to specifically customize these nested components. For
example, the following component is nested in the customized schema:

<xs:element name="promotion"> <xs:complexType> <xs:choice> <xs:element name="Discount" type="xs:string" /> <xs:element name="None" type="xs:string"/> </xs:choice> </xs:complexType> </xs:element>

As
result of the global declarations made earlier, the binding compiler
will generate the following methods for the elements tagged as

choice

:

java.lang.Object getDiscountOrNone();
void setDiscountOrNone(java.lang.Object value);
boolean is SetDiscountOrNone();

Include vendor-specific extensions
. The declaration

<xjc:serializable uid="12343"/>

is an extension binding declaration. The

xjc

prefix binds to a namespace for extension
binding declarations. These declarations are vendor-specific extensions
to the binding declarations defined in http://java.sun.com/xml/ns/jaxb. Here, the vendor-specific declaration covers the binding of classes that
implement

java.io.Serializable

. The serial version uid 12343 will be assigned to each generated class.

Customize the binding of a simple data type
. The declaration

<jaxb:javaType name="short" xmlType="xs:long"

binds the XML datatype

xs:long

to the Java data type

short

. This overrides the default binding behavior, which is to bind

xs:long

to the Java primitive data type

long

. The additional declaration

printMethod="javax.xml.bind.DatatypeConverter.parseShort"

tells the binding compiler to use the

DatatypeConverter.parseShort

method in JAXB's

javax.xml.bind

package to convert a lexical
representation of the XML data type into the Java data type. The parse
method is invoked by the JAXB provider's implementation during
unmarshalling. The additional declaration

printMethod="javax.xml.bind.DatatypeConverter.printShort"

tells the binding compiler to use the

DatatypeConverter.printShort

method in JAXB's

javax.xml.bin

package to convert the Java data
type into a lexical representation of the XML data type. The print
method is invoked by the JAXB provider's implementation during
marshalling.

Additional customizations
:
Other annotations in the schema illustrate additional types of
customization, such as annotating a specific schema element to a Java
Content Interface or Java Element Interface. This is done through a

<class>

binding declaration. In the annotated schema example, a

<class>

binding declaration is used to specify the name

MyCollection

for the interface bound to the

<Collection>

class. Another binding declaration in the annotated schema example binds the

<bookCategory>

element to its Java
representation as a typesafe enumeration class. Although not illustrated
in the annotated schema, another type of customization you can make is
to specify javadoc for a generated package or class. These are only some
of the many binding customizations that JAXB allows.

You can see the impact of the binding declarations by binding the annotated schema. When you do the binding, specify the

-extension

option, as in the following command:

xjc.sh -extension -p cust books_customization.xsd

The

-extension

option allows you to use
vendor-provided extensions. You need this to enable the extension
binding declaration in the schema. If you don't specify the

-extension

option, the binding compiler will
run in "strict" mode. In this mode, it allows only for default bindings,
and will produce an error message when it comes to the extension
binding declaration.

After you run the
program, examine the interfaces and classes that the binding compiler
generates, and compare them to the interfaces and classes generated from
the uncustomized schema. For example,
here
is the

CollectionType.java

file generated for the unnamed complex type for the

<Collection>

element. Notice the additional methods that have been added because of the binding customizations.

Distinct Advantages

Let's reiterate a number of important advantages of using JAXB:

JAXB simplifies access to an XML document from a Java program:

.

JAXB allows you to access and process XML data
without having to know XML or XML processing. Unlike SAX-based
processing, there's no need to create a SAX parser or write callback
methods.

JAXB allows you to access data in non-sequential
order, but unlike DOM-based processing, it doesn't force you to navigate
through a tree to access the data.

By unmarshalling XML data through JAXB, Java
content objects that represent the content and organization of the data
are directly available to your program.

JAXB uses memory efficiently: The tree of content
objects produced through JAXB tends can be more efficient in terms of
memory use than DOM-based trees.

JAXB is flexible:

You can unmarshal XML data from a variety of input sources, including a file, an

InputStream

object, a URL, a DOM node, or a transformed source object.

You can marshal a content tree to a variety of output targets, including an XML file, an

OutputStream

object, a DOM node, or a transformed data object

You can unmarshal SAX events -- for example, you
can do a SAX parse of a document and then pass the events to JAXB for
unmarshalling.

JAXB allows you to access XML data without having to unmarshal it. Once a schema is bound you can use the

ObjectFactory

methods to create the objects and then use

set

methods in the generated objects to create content.

You can validate source data against an associated
schema as part of the unmarshalling operation, but you can turn
validation off if you don't want to incur the additional validation
overhead.

You can validate a content tree, using the

Validator

class, separately from
marshalling. For example, you can do the validating at one point in
time, and do the marshalling at another time.

JAXB's binding behavior can be customized in a variety of ways.

Java developers should find JAXB a welcome aid in developing Web services and other Java-XML applications.

Run the Examples

If you'd like to run the examples in this article with Java Web Services Developer Pack V 1.1, you need to:

Install Java Web Services Developer Pack V 1.1 (if you haven't already done so).

Set the

JWSDP_HOME

environment variable to the Java
Web Services Developer Pack V 1.1 installation directory. For example,
if you're using the C shell in the Solaris Operating Environment, enter
the command:

setenv JWSDP_HOME install_dir

replace
install_dir
with the Java Web Services Developer Pack V 1.1 installation directory.

Set the class paths for JAXB, JAXP, and Java Web
Services Developer Pack V 1.1. For example, if you're using the C shell
in the Solaris Operating Environment, enter the commands:

setenv jaxb_lib $JWSDP_HOME/jaxb-1.0/lib
setenv jaxp_lib $JWSDP_HOME/jaxp-1.2.2/lib/endorsed
setenv jwsdp_lib $JWSDP_HOME/jwsdp-shared/lib

and on one line:

setenv CLASSPATH $jwsdp_lib/jax-qname.jar: $jwsdp_lib/namespace.jar:$jaxb_lib/jaxb-api.jar: $jaxb_lib/jaxb-libs.jar:$jaxb_lib/jaxb-ri.jar: $jaxb_lib/jaxb-xjc.jar: $jaxp_lib/dom.jar:$jaxp_lib/sax.jar: $jaxp_lib/xalan.jar:$jaxp_lib/xercesImpl.jar: $jaxp_lib/xsltc.jar:$jaxp_lib/../jaxp-api.jar: .:classes:work

Set the path for JAXB. For example, if you're using the C shell in the Solaris Operating Environment, enter the command:

setenv PATH $JWSDP_HOME/jaxb-1.0/bin:$PATH

For More Information

Java Architecture for XML Binding (JAXB)

Java Web Services Developer Pack V 1.1

W3C XML Schema Language

About the Authors

[b]Ed Ort
[/b]
is a java.sun.com staff member. He has written extensively about Java technology and Web services.

[b]Bhakti Mehta
[/b]
is a Member of Technical Staff at Sun Microsystems
Inc. She is in the Web Technologies and Standards Interoperability and
Quality team, and has worked with JAXP, JAXB, JAXR and JAXM.