The Java Architecture for XML Binding has been developed through the Java Community Process (JCP). There are two Java Specification Requests associated with JAXB: JSR 31 and JSR 222 define JAXB 1.0 and JAXB 2.0, respectively. JAXB has a few different web sites associated with it, listed in .

Main site
Reference implementation site
JSR 31
JSR 222

JAXB 1.0

JAXB 1.0 defines a standardized API for marshalling and unmarshalling as well as a validation API. The specification also defines how a schema compiler binds a schema to its Java representation. However, it does not specify how a schema compiler is invoked. As a result, implementations are free to package their schema compiler in any way, but generally you will see a shell script, an Ant task, or both. Although JAXB 1.0 apps are portable in the sense that the behavior of implementations of the Marshaller, Unmarshaller, and Validator interfaces is defined in the specification, Java classes and interfaces generated by a JAXB 1.0 schema compiler are not portable between JAXB implementations.

[*] Or batch file, for Windows users.

[] Ant is a build tool used extensively for Java apps. More info can be found at and in Ant: The Definitive Guide by Steve Holzner (Oracle).

JAXB 1.0 requires implementations to support a subset of W3C XML Schemas only. Implementations are free to support additional features of W3C XML Schemas and additional schema languages, including DTDs. The specific features for which support is not required are listed in the JAXB 1.0 specification, available from the JSR 31 web site, listed in . For each namespace defined in a schema, a JAXB 1.0 schema compiler will produce a package containing a set of Java interfaces, a class named ObjectFactory, and, if necessary, classes for any enumerations defined in the schema. The compiler will also produce implementation classes for these interfaces, usually in a separate implementation package. I will detail the interfaces and classes created in the section " later in this chapter. In JAXB 1.0, it is not possible to bind an arbitrary Java class, even one that adheres to JavaBeans naming conventions, to an XML representation. Classes to be marshalled must be generated by the JAXB schema compiler. The validation features within JAXB 1.0 allow for validation on demand. At any point, an instance of any JAXB-generated class can be validated against the schema constraints compiled into those generated classes. By default, validation occurs during marshalling and unmarshalling, but it is possible to disable validation.

JAXB 2.0

Just a few months after the release of the final JAXB 1.0 specification in the fall of 2003, JSR 222 was created to develop the second version of JAXB. The final specification for JAXB 2.0 was released almost three years later, in May of 2006. JAXB 2.0 is also part of the Java Enterprise version 5 specification. Like many of the other specifications that are part of Java EE 5, JAXB 2.0 is dependent upon the new language features introduced with Java 5, most significantly annotations and parameterized types (also known as generics). Thus, if your app must run on Java 1.4 or below, you cannot use JAXB 2.0. JAXB 2.0 adds several significant features to JAXB.

Java Tip Although JAXB 2.0 is part of Java EE 5, it is not dependent upon a Java EE container.


Schema compiler generates annotated POJOs

Unlike JAXB 1.0, which produced both public interfaces and private implementation classes for each component of an XML Schema, JAXB 2.0 produces plain Java classes that don't implement any special interfaces or extend any classes. In other words, the generated classes are plain-old Java objects: POJOs. The metadata needed to marshall and unmarshall is contained in Java annotations.


Annotations enable binding arbitrary classes

As a result of the use of annotations, any Java class can be bound to an XML representation simply by adding the appropriate annotations to an existing class.


Schema generation

In addition to the schema compiler specified in JAXB 1.0, JAXB 2.0 includes a schema generator that looks for annotations in Java classes and produces an XML schema. However, if a schema is compiled and then the resulting code is used as the source for schema generation, the compiled schema and the generated schema are not necessarily equivalent.


Portable runtime

Unlike JAXB 1.0, JAXB 2.0 specifies that all interfaces and classes, both those that are part of the API and those generated by the schema compiler, be portable between implementations.


Integration with JAXP validation

Unlike JAXB 1.0, JAXB 2.0 does not include its own validation capabilities. Instead, validation is delegated to the validation features of JAXP 1.3, covered in . Although the javax.xml.bind.Validator class is still part of the API, it is deprecated and optional. This separation of concerns means that it is possible, for example, to have a schema compiler generate classes from a W3C XML Schema, but when validating the marshalled document, use a RELAX NG schema. It also means that enhancements to the JAXP validation features will be usable by JAXB without updating the JAXB API or implementations.


Complete W3C XML Schema support

Whereas JAXB 1.0 did not require complete support for the W3C XML Schema specification, JAXB 2.0 requires support of the complete specification.


Integration with StAX

Implementations of the JAXB 2.0 Marshaller interface can marshall a Java object tree to a javax.xml.stream.XMLStreamWriter or a javax.xml.stream.XMLEventWriter object and Unmarshaller implementations can unmarshall from a javax.xml.stream.XMLStreamReader or a javax.xml.stream.XMLEventReader object. These interfaces were discussed in .


Callback methods

Both Marshaller and Unmarshaller interfaces provide callback mechanisms that allow an object participating in a marshalling or an unmarshalling to be notified before and after the object is marshalled. Additionally, a listener object can be registered with a Marshaller or Unmarshaller instance to receive a notification for each object marshalled or unmarshalled.

Java Tip Like JAXB 1.0, JAXB 2.0 only requires support for W3C XML Schema, but does not preclude implementations from including support for additional schema languages.

JAXB Reference Implementations

The reference implementations of both JAXB 1.0 and JAXB 2.0 are included in Sun's Java Web Services Developer Pack. In addition, the reference implementations are open source projects on java.net. The main reference implementation project is located at .

Java WSDP

The Java Web Services Developer Pack (Java WSDP) is a single download that includes a dozen or so XML and web services libraries and apps. It is part of an initiative by Sun to make the XML and web services features of Java more accessible to developers. In addition to libraries and apps, Java WSDP includes documentation and sample code for all of the included components. There's also a tutorial available for download. At the time of writing, the latest version of the Java WSDP is 2.0, released in December of 2005. Java WSDP 2.0 includes the following components:

Some of the components of Java WSDP require Java 5 (JAXB 2.0, for example), but most do not (such JAXP 1.3 and SJSXP). The previous version of Java WSDP is 1.6 (released in June 2005). The component list for Java WSDP 1.6 is similar to that of 2.0, just different versions of those components. Version 1.0.5 of the JAXB reference implementation is included in Java WSDP 1.6.

Downloading Java WSDP

The current version of Java WSDP can be downloaded from . Sun may ask you to register, but that's not required. Sun does require you to accept the terms of the license agreement before downloading. The available downloads are an .exe file for use on Windows and an SH file for use on Linux, Unix, and Mac OS X, as shown in .

Java WSDP download page

Java ScreenShot

Installing Java WSDP can either be done with a graphical wizard-type interface or a console app. The console version has the same prompts as the graphical wizard and is run using the command-line option -console: 

$ ./jwsdp-2_0-unix.sh console

The first step of the installation, regardless of whether you use the graphical or console mode, is accepting the license agreement for Java WSDP. Next, you need to select a JDK for Java 5 or later. The installer will scan your system for an appropriate JDK. If it doesn't find one, or doesn't find the one you want to use, it's possible to select a different JDK, as seen in .

JDK selection dialog

Java ScreenShot

Next, the installer asks you to select a web container for use with Java WSDP. This is an optional step. Java WSDP 2.0 is compatible with Sun Java System app Server 8.1 and 9.0 as well as a version of Apache Tomcat customized for use with Java WSDP. The container selection dialog, shown in , also provides a link to a page on http://java.oracle.com from which you can download a supported web container. If you're only interested in JAXB or the other apps within Java WSDP that don't require a web container (such as SJSXP), feel free to select the "No Web Container" option. Java WSDP also comes with scripts you can run to integrate Java WSDP with one of these containers after installation.

Web container selection dialog

Java ScreenShot

The installer will next ask you where you want Java WSDP installed and which components you want installed, as seen in .

Component selection dialog

Java ScreenShot

Finally, you'll be asked if you use an HTTP proxy and, if so, what the address and port for your proxy server are. Then, you'll be shown a confirmation screen as seen in . Once you click the Next button, the files will be copied to your desired destination.

Java WSDP installation confirmation

Java ScreenShot

The installer for prior versions of Java WSDP has largely the same dialogs.

Downloading JAXB 2.0 reference implementation

As mentioned above, the JAXB 2.0 reference implementation is an open source project hosted by the Java community site Java.net. As you can see in the screenshot in , the project page has a prominent link to download the current version of the reference implementation (2.0.1 at the time this screenshot was taken) as well as a link on the left navigation to all downloads, which include previous versions.

JAXB RI Project page at java.net

Java ScreenShot

The JAR file that you download from java.net is, like the download for Java WSDP, an installer that requires you to accept a license agreement before it installs the contents of the reference implementation.

Contents

Regardless of how it is downloaded, the JAXB reference implementation contains four directories:


bin

Contains batch and shell scripts for running the schema compiler and generator.


docs

Contains various pieces of documentation, including documentation for the schema compiler, schema generator, and Javadocs for the JAXB API.


lib

Contains the JAR files for both the JAXB API and the reference implementation. The classes for the schema compiler and generator are packaged into a separate JAR file that is not typically necessary at runtime.


samples

Contains various sample apps.

Now that we installed an implementation of JAXB, we can start using it.