Module org.glassfish.jaxb.runtime

Package org.glassfish.jaxb.runtime.v2

The JAXB 2.0 runtime

.

Overview

This module provides code that implements JAXBContext. Roughly speaking the runtime works like this:

  1. There's a set of classes and interfaces that model JAXB-bound types. You can think of this as a reflection library for JAXB.
  2. There's a set of classes that constitute the unmarshaller and marshaller. Each class represents a small portion, and they are composed to perform the operations.
  3. JAXBContextImpl builds itself by reading the model and composing unmarshallers and marshallers.

Interesting Pieces inside Runtime

The followings are the interesting pieces inside the runtime.

org.glassfish.jaxb.core.v2.model model
This set of classes and interfaces models JAXB-bound types.
XML I/O
This set of classes implements the JAXB API and provides the XML I/O functionality.

The classes NOT in the org.glassfish.jaxb.core.v2 package (and its subpackages) are also used by old JAXB 1.0 clients.

Models

"Model" is the portion of the code that represents JAXB-bound types.

The following picture illustrates the relationship among major packages of the binding model.

The core model contracts are all interfaces, and they are parameterized so that they can be used with different reflection libraries. This is necessary, as the model is used:

  1. at runtime to process loaded classes,
  2. at tool-time to process source files / class files, and
  3. at schema compile time to generate source code.
They all use different reflection libraries.

This portion is used by all three running mode of JAXB. The corresponding base-level implementaion is also parameterized.

The runtime model contract and implementation are used only at the run-time. These packages fix the parameterization to the Java reflection, and also exposes additional functionalities to actually do the unmarshalling/marshalling. These classes have "Runtime" prefix.

Finally XJC has its own implementation of the contract in its own package. This package also fixes the parameterization to its own reflection library.

When you work on the code, it is often helpful to know the layer you are in.

The binding model design roughly looks like the following. For more details, see the javadoc of each component.

TODO: link to classes from above pictures

Evolution Rules

None of the class in this package or below should be directly referenced by the generated code. Hence they can be changed freely from versions to versions.

Performance Characteristics

Model construction happens inside JAXBContext.newInstance(Class[]). It's desirable for this step to be fast and consume less memory, but it's not too performance sensitive.

Code that implements the unmarshaller and the marshaller OTOH needs to be very carefully written to achieve maximum sustaining performance.

Bootstrap Sequence

The following picture illustrates how the JAXBContext.newInstance(Class[]) method triggers activities.