XML-to-Java Mapping

JAXB defines the basic mapping rules between XML and Java that all JAXB implementations must support. These are referred to as default bindings, and the schema compiler uses them by default. In addition, JAXB is flexible enough to allow custom bindings, though by passing in the "configuration" in the form of binding declarations to the binding compiler. In , we discussed how JAX-RPC maps and marshalls XML to Java. The default binding defined by JAXB is identical to the mapping specified in JAX-RPC. In this section, we will discuss some commonly used additional details and mappings . We encourage you to refer to the JAXB specifications for syntactical details regarding XML-Java mappings.

Java Start Sidebar

For the sake of brevity, concepts pertaining to XML-Java mapping covered in are not repeated here. We suggest reading that chapter, particularly the section "XML to Java Unmarshalling," before this section.

Java End Sidebar

Primitives and Simple Types

In addition to the types defined by JAX-RPC (, Table 10.3a), JAXB addresses mapping for the types shown in Table 13.1.

Table 13.1: Additional Mappings Defined in JAXB

XML type

Java type














XML enumerations map to Java classes where the name of the class is the name of the enumeration and the package corresponds to the target namespace. This was discussed in (see Table 10.3b). JAXB generates similar mappings, and the generated interface has a getValue and setValue method to access the underlying value. Listings 13.4a and 13.4b show a sample XML schema and its corresponding Java interface.

Listing 13.4a: A schema with enumerations
<xsd:schema xmlns:xsd="">
 <xsd:element >
 <xsd:simpleType >
 <xsd:restriction base="xsd:string">
 <xsd:enumeration value="Saturday"></xsd:enumeration>
 <xsd:enumeration value="Sunday"></xsd:enumeration>
 <xsd:enumeration value="Monday"></xsd:enumeration>
 <xsd:enumeration value="Tuesday"></xsd:enumeration>
 <xsd:enumeration value="Wednesday"></xsd:enumeration>
 <xsd:enumeration value="Thursday"></xsd:enumeration>
 <xsd:enumeration value="Friday"></xsd:enumeration>

Java End example
Listing 13.4b: The generated interface for an enumeration in Listing 13.4a
public interface Days extends javax.xml.bind.Element{
 String getValue();
 void setValue(String value);

Java End example

typesafe Enumerations

typesafe enumeration is an important concept. Because Java was designed to avoid using the C/C++ type enumerations (enum), developers often define simple sets of primitive values:

public class Days{
 public static final int MONDAY= "Monday";
 public static final int TUESDAY= "Tuesday";
 public static final int WEDNESDAY= "Wednesday";
// And so on

Java Start Sidebar

The above approach using primitive ints was originally proposed by James Gosling and Henry McGilton in The Java Language Environment whitepaper (see section 2.2.3, "No Enums") at

Java End Sidebar

The problem with using Strings is that it causes numerous string comparisons and embeds the values in the code. The typesafe enum pattern takes the approach of using static final primitives one step further and essentially replaces the primitive constants with a set of static final object references encapsulated in a class:

public final class Days {
 public static final Days MONDAY = new Days();
 public static final Days TUESDAY = new Days();
 public static final Days WEDNESDAY = new Days();
// And so on
 private Daya() {}

The static fields will be initialized when the class is loaded. Because the only way to construct the objects is internal to the class, there can be no other instance of these Days objects. Because the fields are final, the identity comparison (==) can be easily used instead of the equals() method—for example, if(someday== Days.TUESDAY) {}. This is analogous to comparing pointers in C/C++.

Java Start Sidebar

Details on typesafe enumerations and their complexities can be found in Joshua Bloch's Effective Java Programming Language Guide (Oracle, 2001). Some discussion is available at

Java End Sidebar

JAXB allows developers to specify that code generated for the enumerations in the schema use this typesafe enumeration pattern. By default, only XML enumerations derived by restriction from the base type "xsd:NCName" are mapped to typesafe enumeration classes.

Java Start Sidebar

If the Java object is being serialized, then the enum class must implement the read Resolve() method, because the private constructor state is lost during serialization.

Java End Sidebar


XML lists map to java.util.List instances. The data types contained in the collection are either the Java mappings of the basic data types or objects based on the enumeration mapping. For example, consider this schema fragment:

<xsd:schema xmlns:xsd="">
<xsd:element >
 <xsd:list itemType="xsd:string"/>

The element would map to a Catalog class object, and the getValue() would return a List of String objects:

public interface Catalog extends javax.xml.bind.Element{
 java.util.List getValue();

If the itemType in the schema were an enumeration or a complex type, the List would contain the corresponding Java classes—for example, a List of Billingaddress objects.

Java Start Sidebar

Recall that in JAX-RPC the Java mapping for the list and union type are optional.

Java End Sidebar

Complex Types

As in JAX-RPC, XML complex types are mapped to Java interfaces. For example, Listings 13.5a and 13.5b show how the billingaddress element is mapped to Java.

Listing 13.5a: A complex element
<xsd:element name="billingaddress">
 <xsd:element ref="name"/>
 <xsd:element ref="street"/>
 <xsd:element ref="city"/>
 <xsd:element ref="state"/>
 <xsd:element ref="zip"/>

Java End example
Listing 13.5b: Generated binding interface for a complex element
package com.flutebank.schema;
public interface Billingaddress
 extends javax.xml.bind.Element, com.flutebank.schema.BillingaddressType{
package com.flutebank.schema;
public interface BillingaddressType {
 com.flutebank.schema.Name getName();
 void setName(com.flutebank.schema.Name value);
 com.flutebank.schema.Zip getZip();
 void setZip(com.flutebank.schema.Zip value);
 com.flutebank.schema.State getState();
 void setState(com.flutebank.schema.State value);
 com.flutebank.schema.City getCity();
 void setCity(com.flutebank.schema.City value);
 com.flutebank.schema.Street getStreet();
 void setStreet(com.flutebank.schema.Street value);

Java End example

Mappings in JAXB and JAX-RPC

Although the JAXB and JAX-RPC API were developed independently, and JAXB was released after JAX-RPC, both specify XML-to-Java and Java-to-XML mappings. We looked at the JAX-RPC mappings in . JAXB concentrates on the binding issue and therefore seeks to solve the larger problem of how XML and Java can work seamlessly through the use of compile-time bindings. Therefore, the treatment in JAXB is much more detailed and thorough. This should not be construed to mean that there are two sets of bindings. The bindings defined by JAX-RPC and discussed in can be considered a subset of details addressed in JAXB. JAXB also allows for customization using the binding declaration mechanism.