Eclipse Implementation of JAXB Users Guide

Because XML Schema is so complicated, and because there are a lot of tools out there do not implement the spec correctly, it is often the case that a schema you are trying to compile has some real errors in it. When this is the case, you'll see XJC reporting somewhat cryptic errors such as rcase-RecurseLax.2: There is not a complete functional mapping between the particles.

The Eclipse Implementation of JAXB uses the schema correctness checker from the underlying JAXP implementation, which is the JAXP RI in a typical setup. The JAXP RI is one of the most conformant schema validators, and therefore most likely correct. So the first course of action usually is to fix problems in the schema.

However, in some situations, you might not have an authority to make changes to the schema. If that is the case and you really need to compile the schema, you can bypass the correctness check by using the -nv option in XJC. When you do this, keep in mind that you are possibly feeding "garbage" in, so you may see XJC choke with some random exception.

One of the typical errors you'll see when compiling a complex schema is:

parsing a schema...
[ERROR] Property "MiOrMoOrMn" is already defined.
  line 132 of
file:/C:/kohsuke/Sun/JAXB/jaxb-unit/schemas/individual/MathML2/presentation/scripts.xsd

[ERROR] The following location is relevant to the above error
  line 138 of
file:/C:/kohsuke/Sun/JAXB/jaxb-unit/schemas/individual/MathML2/presentation/scripts.xsd

This is an actual example of the offending part of a schema, taken from MathML. If you go to line 132 of scripts.xsd, you'll see that it has a somewhat complicated content model definition:

<xs:group name="mmultiscripts.content">
    <xs:sequence>
        <xs:group ref="Presentation-expr.class"/>
        <xs:sequence minOccurs="0" maxOccurs="unbounded">      <!-- line 132 -->
            <xs:group ref="Presentation-expr-or-none.class"/>
            <xs:group ref="Presentation-expr-or-none.class"/>
        </xs:sequence>
        <xs:sequence minOccurs="0">
            <xs:element ref="mprescripts"/>
            <xs:sequence maxOccurs="unbounded">                 <!-- line 138 -->
                <xs:group ref="Presentation-expr-or-none.class"/>
                <xs:group ref="Presentation-expr-or-none.class"/>
            </xs:sequence>
        </xs:sequence>
    </xs:sequence>
</xs:group>

This is a standard technique in designing a schema. When you want to say "in this element, B can occur arbitrary times, but C can occur only up to once", you write this as B*,(C,B*)?. This, however, confuses Eclipse Implementation of JAXB, because it tries to bind the first B to its own property, then C to its own property, then the second B to its own property, and so we end up having a collision again.

In this particular case, B isn't a single element but it's a choice of large number of elements abstracted away in <xs:group>s, so they are hard to see. But if you see the same content model referring to the same element/group twice in a different place, you can suspect this.

In this case, you'd probably want the whole thing to map to a single list so that you can retain the order those elements show up in the document. You can do this by putting the same <jaxb:property> customization on the whole "mmultiscripts.content" model group, like this (or you can do it externally with XPath):

<xs:groupname="mmultiscripts.content">
<xs:annotation>
    <xs:appinfo>
        <jaxb:propertyname="content"/>
    </xs:appinfo>
</xs:annotation>
<xs:sequence>
<xs:groupref="Presentation-expr.class"/>

Another way to fix this problem is to use the simpler and better binding mode in XJC, which is a Eclipse Implementation of JAXB vendor extension.

When schemas contain similar looking element/type names, they can result in "Two declarations cause a collision in the ObjectFactory class" errors. To be more precise, for each of all types and many elements (exactly what elements get a factory and what doesn't is bit tricky to explain), XJC produces one method on the ObjectFactory class in the same package. The ObjectFactory class is created for each package that XJC generates some files into. The name of the method is derived from XML element/type names, and the error is reported if two elements/types try to generate the same method name.

There are two approaches to fix this problem. If the collision is coming from two different schemas with different target namespaces, then you can easily avoid the collision by compiling them into different Java packages. To do this, use <schemabindings> customization on two schemas and specify the package name.

Another way to fix this problem is to use <factoryMethod> customization on two conflicting elements/types to specify different factory method names. This can be used in all cases, but if you have a large number of conflicts, you'll have to specify this customization one by one.

Notice that <class> customization doesn't affect the ObjectFactory method name by itself.

The catalog resolver supports many different formats, but the easiest one is a line based *.cat format. Other than comments and empty lines, the file mainly consists of two kinds of declarations, SYSTEM, and PUBLIC.

--
  sample catalog file.

  double hyphens are used to begin and end a comment section.
--

SYSTEM "http://www.w3.org/2001/xml.xsd" "xml.xsd"

PUBLIC "-//W3C//DTD XMLSCHEMA 200102//EN" "s4s/XMLSchema.dtd"

The SYSTEM entry has the format of "SYSTEM REFERENCE ACTUAL-LOCATION", which defines a simple redirection. Every time XJC loads any resource (be it schemas, DTDs, any entities referenced within), it will first resolve relative paths to absolute paths, then looks for a matching REFERENCE line. If it is found, the specified actual location is read instead. Otherwise XJC will attempt to resolve the absolutepath.

ACTUAL-LOCATION above accepts relative paths, and those are resolved against the catalog file itself (so in the above example, xml.xsd is assumed to be in the same directory with sample-catalog.cat.

What you need to be careful is the fact that the REFERENCE portion must be absolute, and when XJC finds a reference in schema, it will first convert that to the absolute path before checking the catalog. So what this means is that if your schema is written like this:

<xs:import namespace="http://www.w3.org/1999/xlink" schemaLocation="xlink.xsd" />

Then your catalog entry would have to look like this:

-- this doesn't work because xlink.xsd will be turned into absolute path --
SYSTEM "xlink.xsd" "http://www.w3.org/2001/xlink.xsd"

-- this will work, assuming that the above schema is in /path/to/my/test.xsd --
SYSTEM "/path/to/my/xlink.xsd" "http://www.w3.org/2001/xlink.xsd"

Another kind of entry has the format of "PUBLIC PUBLICID ACTUAL-LOCATION" or "PUBLIC NAMESPACEURI ACTUAL-LOCATION".

The "PUBLICID" version is used to resolve DTDs and entities in DTDs. But this type of entry is also used to resolve <xs:import> statements. XJC will match the value of the namespace attribute and see if there's any matching entry. So given a schema like this:

<xs:import namespace="http://www.w3.org/1999/xlink" schemaLocation="xlink.xsd" />
<xs:import namespace="http://www.w3.org/1998/Math/MathML" />

The following catalog entries will match them.

PUBLIC "http://www.w3.org/1999/xlink" "http://www.w3.org/2001/xlink.xsd"
PUBLIC "http://www.w3.org/1998/Math/MathML" "/path/to/my/mathml.xsd"

As you can see, XJC will check the PUBLIC entries regardless of whether <xs:import> has the schemaLocation attribute or not. As with the case with the SYSTEM entry, the ACTUAL-LOCATION part can be relative to the location of the catalog file.

Once you write a catalog file, you'd need to specify that when you invoke XJC.

If you are trying to write a catalog file and banging your head against a wall because it's not working, you should enable the verbose option of the catalog resolver. How you do this depends on what interface you use:

If you are otherwise invoking XJC programmatically, you can set the above system property before invoking XJC.

<xs:any /> with processContents=skip means any well-formed XML elements can be placed. Therefore, XJC binds this to DOM Element interface.

<xs:element name="person">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="name" type="xs:string" />
      <xs:any processContents="skip" maxOccurs="unbounded" minOccurs="0" />
    </xs:sequence>
  </xs:complexType>
</xs:element>

import org.w3c.dom.Element;

@XmlRootElement
class Person {
  public String getName();
  public void setName(String);

  @XmlAnyElement
  public List<Element> getAny();
}

<xs:any /> with processContents=strict (or <xs:any /> without any processContents attribute, since it defaults to "strict") means any XML elements placed here must have corresponding schema definitions. This mode is not what people typically expect as "wildcard", but this is the default. The following shows this binding. (lax=true is unintuitive, but it's not an error in this document):

<xs:element name="person">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="name" type="xs:string" />
      <xs:any maxOccurs="unbounded" minOccurs="0" />
    </xs:sequence>
  </xs:complexType>
</xs:element>

@XmlRootElement
class Person {
  public String getName();
  public void setName(String);

  @XmlAnyElement(lax=true)
  public List<Object> getAny();
}

Jakarta XML Binding binds any such element to an Object, and during unmarshalling, all elements encountered are unmarshalled into corresponding Jakarta XML Binding objects (including JAXBElements if necessary) and placed in this field. If it encounters elements that cannot be unmarshalled, DOM elements are produced instead.

At runtime, you can place either DOM elements or some Jakarta XML Binding objects that map to elements. A typical mistake is to put a String that contains XML fragment, but this won't work; you'd have to first read that into a DOM.

<xs:any /> with processContents=lax means any XML elements can be placed here, but if their element names match those defined in the schema, they have to be valid. XJC actually handles this exactly like processContents='strict', since the strict binding allows unknown elements anyway.

Chameleon schema" (read more, in particular this) is a technique used to define multiple almost-identical sets of definitions into multiple namespaces from a single schema document.

For example, with this technique, you can write just one "foo" complex type and define it into namespace X and Y. In this case, one tends to hope that XJC will only give you one Foo class for this, but unfortunately because it's actually defined in two namespaces, Jakarta XML Binding needs two Java classes to distinguish X:foo and Y:foo, so you'll get multiple copies.

If you find this to be problematic, there are a few ways to work around the problem.

If you have a type hierarchy and would like to insert your class in the middle, you can use the combination of XmlTransient and @implClass of <class> customization. See the following example:

<xs:schema ...>
  <xs:complexType name="vehicle">
    <xs:annotation><xs:appinfo>
      <jaxb:class implClass="MyVehicle" />
    </xs:appinfo></xs:annotation>
  </xs:complexType>

  <xs:complexType name="car">
    <xs:complexContent>
      <xs:extension base="vehicle" />
    </xs:complexContent>
  </xs:complexType>

  <xs:complexType name="bicycle">
    <xs:complexContent>
      <xs:extension base="vehicle" />
    </xs:complexContent>
  </xs:complexType>
</xs:schema>

            Vehicle
               ^
               |
            MyVehicle
               ^
          _____|______
         |            |
        Car          Bicycle

You'll then manually write MyVehicle class that extends from Vehicle. Annotate this class with XmlTransient to achieve the desired effect.

The following customization will stop binding a simple type to a type-safe enum. This can be convenient when number of constants is too large to be an useful enum (by default, the Jakarta XML Binding spec won't generate enum with more than 256 constants, but even 100 might be too large for you.)

<xs:simpleType name="foo">
  <xs:annotation><xs:appinfo>
    <jaxb:typesafeEnumClass map="false" />
  </xs:appinfo></xs:annotation>
  <xs:restriction base="xs:string">
    <xs:enumeration value="x" />
    <xs:enumeration value="y" />
    <xs:enumeration value="z" />
  </xs:restriction>
</xs:simpleType>

To disable such type-safe enum binding altogether for the entire schema, use a global binding setting like this (this is actually telling XJC not to generate enums if a simple type has more than 0 constants --- the net effect is no enum generation):

<xs:schema ...>
  <xs:annotation><xs:appinfo>
    <jaxb:globalBindings typesafeEnumMaxMembers="0" />
  </xs:appinfo></xs:annotation>
  ...
</xs:schema>

The <jaxb:dom>customization allows you to map a certain part of the schema into a DOM tree. This customization can be attached to the following schema components:

In the following example, a wildcard is mapped to a DOM node. Each element that matches to the wildcard will be turned into a DOM tree.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
               xmlns:jaxb="https://jakarta.ee/xml/ns/jaxb"
               jaxb:version="3.0">

        <xs:element>
           <xs:complexType>
              <xs:sequence>
                 <xs:any maxOccurs="unbounded" processContents="skip">
                    <xs:annotation><xs:appinfo>
                      <jaxb:dom/>
                    </xs:appinfo></xs:annotation>
                 </xs:any>
              </xs:sequence>
           </xs:complexType>
        </xs:element>
    .
    .
    .
    </xs:schema>

This extension can be used to access wildcard content or can be used to process a part of a document by using other technologies that require "raw" XML. By default, Jakarta XML Binding generates a getContent() method for accessing wildcard content, but it only supports "lax" handling which means that unknown content is discarded. You may find more information in 7.12 chapter of Jakarta XML Binding 2 specification.

The generated beans (and in particular the JAXBElement class) do not support the clone operation. There was a suggestion by another user that beanlib has been used successfully to clone Jakarta XML Binding objects.

Under some rare circumstances, XJC will generate some Java classes into a package called org.w3._2001.xmlschema. This happens when XJC decides that it needs some Java artifacts for the XML Schema built-in namespace of http://www.w3.org/2001/XMLSchema.

Since this package name is most often problematic, you can rename this by simply saving the following text in an .xsd file and submitting it to XJC along with the other schemas you have:

<schema xmlns="http://www.w3.org/2001/XMLSchema"
  targetNamespace="http://www.w3.org/2001/XMLSchema"
  xmlns:jaxb="https://jakarta.ee/xml/ns/jaxb"
  jaxb:version="3.0">
  <annotation><appinfo>
    <jaxb:schemaBindings>
      <jaxb:package name="org.acme.foo"/>
    </jaxb:schemaBindings>
  </appinfo></annotation>
</schema>

This is bit tricky, but the idea is that since you can define a schema for one namespace in multiple schema documents, this makes XJC think that this schema is a part of the built-in "XML Schema for XML Schema".

Jakarta XML Binding (or any other databinding engine, for that matter) is for binding strongly-typed POJO-like objects to XML, such as AddressBook class, PurchaseOrder class, and so on, where you have fields and methods that shape a class.

There are other kinds of classes that are more close to reflection. Those classes don't have methods like getAddress, and instead you'd do get("Address"). JDBC ResultSet is one of those classes. It's one class that represents million different data structures, be it a customer table or a product table. Generally speaking, these classes does not allow Jakarta XML Binding to statically determine what the XML representation should look like. Instead, you almost always need to look at an instance to determine the shape of XML.

These classes are not really suitable for binding in Jakarta XML Binding. If this is the only object that you'd want to write out, then you'd be better off using XMLStreamWriter or some such XML infoset writing API. There are a few online articles that cover this topic. Also, many modern database offers a native ability to export a query into XML, which is supposed to work a lot faster than you'd do in Java (and saves your time of writing code.)

If you are using ResultSet as a part of your object tree that you want to marshal to Jakarta XML Binding, then you can use XmlJavaTypeAdapter.

Jakarta XML Binding spec defines a special handling for Map when it's used as a propety of a bean. For example, the following bean would produce XMLs like the following:

@XmlRootElement
class Foo {
  public HashMap<String,Integer> map;
}

<foo>
  <map>
    <entry>
      <key>a</key>
      <value>1</value>
    </entry>
    <entry>
      <key>b</key>
      <value>2</value>
    </entry>
  </map>
</foo>

Unfortunately, as of 2.1, this processing is only defined for bean properties and not when you marshal HashMap as a top-level object (such as a value in JAXBElement.) In such case, HashMap will be treated as a Java bean, and when you look at HashMap as a bean it defines no getter/setter property pair, so the following code would produce the following XML:

m = new HashMap();
m.put("abc",1);
marshaller.marshal(new JAXBElement(new QName("root"),HashMap.class,m),System.out);

<root />

This issue has been recorded as #223 and the fix needs to happen in later versions of the Jakarta XML Binding spec.

In the mean time, such top-level objects have to be first adapted to a bean that Jakarta XML Binding can process. This has added benefit of being able to control XML representation better. The following code illustrates how to do this:

public class MyHashMapType {
    public List<MyHashMapEntryType> entry = new ArrayList<MyHashMapEntryType>();
    public MyHashMapType(Map<String,Integer> map) {
        for( Map.Entry<String,Integer> e : map.entrySet() )
            entry.add(new MyHashMapEntryType(e));
    }
    public MyHashMapType() {}
}

public class MyHashMapEntryType {
    @XmlAttribute // @XmlElement and @XmlValue are also fine
    public String key;

    @XmlAttribute // @XmlElement and @XmlValue are also fine
    public int value;

    public MyHashMapEntryType() {}
    public MyHashMapEntryType(Map.Entry<String,Integer> e) {
       key = e.getKey();
       value = e.getValue();
    }
}

marshaller.marshal(new JAXBElement(new QName("root"),MyHashMapType.class,new MyHashMapType(m)),System.out);

If you have a lot of difference kinds of Map, you can instead use Object as the key and the value type. In that way, you'll be able to use maps with different type parameters, at the expense of seeing xsi:type attribute on the instance document.

When your interface is implemented by a large number of sub-classes, consider using XmlRootElement annotation like this:

@XmlRootElement
class Zoo {
  @XmlAnyElement
  public List<Animal> animals;
}

interface Animal {
  void sleep();
  void eat();
  ...
}

@XmlRootElement
class Dog implements Animal { ... }

@XmlRootElement
class Lion implements Animal { ... }

This will produce XML documents like this:

<zoo>
    <lion> ... </lion>
    <dog> ... </dog>
</zoo>

The key characteristics of this approach is:

@XmlElementWrapper is often useful with this, as it allows you need to group them. Such as:

@XmlRootElement
class Zoo {
  @XmlElementWrapper
  @XmlAnyElement
  public List<Animal> onExhibit;
  @XmlElementWrapper
  @XmlAnyElement
  public List<Animal> resting;
}

<zoo>
    <onExhibit>
        <lion> ... </lion>
        <dog> ... </dog>
    </onExhibit>
    <resting>
        <lion> ... </lion>
        <dog> ... </dog>
    </resting>
</zoo>

When you use interfaces just to hide your implementation classes from exposure, and when there's 1-to-1 (or close to 1-on-1) relationship between a class and an interface, XmlJavaTypeAdapter can be used like below.

@XmlJavaTypeAdapter(FooImpl.Adapter.class)
interface IFoo {
  ...
}
class FooImpl implements IFoo {
  @XmlAttribute
  private String name;
  @XmlElement
  private int x;

  ...

  static class Adapter extends XmlAdapter<FooImpl,IFoo> {
    IFoo unmarshal(FooImpl v) { return v; }
    FooImpl marshal(IFoo v) { return (FooImpl)v; }
  }
}

class Somewhere {
  public IFoo lhs;
  public IFoo rhs;
}

<somewhere>
  <lhs name="...">
    <x>5</x>
  </lhs>
  <rhs name="...">
    <x>5</x>
  </rhs>
</somewhere>

The key characteristics of this approach is:

A variation of this technique is when you have a few implementations for interface, not just one.

@XmlJavaTypeAdapter(AbstractFooImpl.Adapter.class)
interface IFoo {
  ...
}
abstract class AbstractFooImpl implements IFoo {
  ...

  static class Adapter extends XmlAdapter<AbstractFooImpl,IFoo> {
    IFoo unmarshal(AbstractFooImpl v) { return v; }
    AbstractFooImpl marshal(IFoo v) { return (AbstractFooImpl)v; }
  }
}

class SomeFooImpl extends AbstractFooImpl {
  @XmlAttribute String name;
  ...
}

class AnotherFooImpl extends AbstractFooImpl {
  @XmlAttribute int id;
  ...
}

class Somewhere {
  public IFoo lhs;
  public IFoo rhs;
}

<somewhere>
  <lhs xsi:type="someFooImpl" name="...">
  </lhs>
  <rhs xsi:type="anotherFooImpl" id="3" />
</somewhere>

Note that SomeFooImpl and AnotherFooImpl must be submitted to JAXBContext.newInstance one way or the other.

To take this example a bit further, you can use Object instead of AbstractFooImpl. The following example illustarates this:

@XmlJavaTypeAdapter(AnyTypeAdapter.class)
interface IFoo {
  ...
}
public class AnyTypeAdapter extends XmlAdapter<Object,Object> {
  Object unmarshal(Object v) { return v; }
  Object marshal(Object v) { return v; }
}

class SomeFooImpl implements IFoo {
  @XmlAttribute String name;
  ...
}

class Somewhere {
  public IFoo lhs;
  public IFoo rhs;
}

<xs:complexType name="somewhere">
  <xs:sequence>
    <xs:element name="lhs" type="xs:anyType" minOccurs="0"/>
    <xs:element name="rhs" type="xs:anyType" minOccurs="0"/>
  </xs:sequence>
</xs:complexType>

As you can see, the schema will generated to accept xs:anyType which is more relaxed than what the Java code actually demands. The instance will be the same as the above example. Starting from JAXB RI 2.1, we bundle the AnyTypeAdapter class in the runtime that defines this adapter. So you won't have to write this adapter in your code.

If the use of interface is very little and there's 1-to-1 (or close to) relationship between interfaces and implementations, then you might find XmlElement to be the least amount of work.

interface IFoo {
  ...
}
class FooImpl implements IFoo {
  ...
}

class Somewhere {
  @XmlElement(type=FooImpl.class)
  public IFoo lhs;
}

<somewhere>
  <lhs> ... </lhs>
</somewhere>

This effectively tells Jakarta XML Binding runtime that "even though the field is IFoo, it's really just FooImpl.

In this approach, a reference to an interface has to have knowledge of the actual implementation class. So while this requires the least amount of typing, it probably wouldn't work very well if this crosses module boundaries.

Like the XmlJavaTypeAdapter approach, this can be used even when there are multiple implementations, provided that they share the common ancestor.

The extreme of this case is to specify @XmlElement(type=Object.class).

Occasionally the above approaches cause the generated schema to become somewhat ugly, even though it does make the Jakarta XML Binding runtime work correctly. In such case you can choose not to use the generated schema and instead manually modify/author schemas tht better match your needs.

With sufficient knowlege, one can also use <jaxb:class ref="..."/> annotation so that you can cause XJC to use the classes you already wrote. See this thread for an example. TODO: more details and perhaps an example.

Some users attempted to use the "generateValueClass" customization and see if they can completely replace the generated implementations with other implementations. Unfortunately, this does not work.

Even with the interface/implementation mode, Jakarta XML Binding runtime still requires that the implementation classes have all the Jakarta XML Binding annotations. So just implementing interfaces is not sufficient. (This mode is mainly added to simplify the migration from JAXB 1.0 to Jakarta XML Binding, and that's a part of the reason why things are done this way.)

There are two directions in the runtime compatibility. One is whether v1 can still read what v2 write (forward compatible), and the other is whether v2 can read what v1 wrote (backward compatible).

Jakarta XML Binding can read XML documents that don't exactly match what's expected. This is the default behavior of the Jakarta XML Binding unmarshaller, yet you can change it to a more draconian behavior (TODO: pointer to the unmarshalling section.)

When we are talking about evolving classes, it's often convenient to leave it in the default behavior, as that would allow Jakarta XML Binding to nicely ignore elements/attributes newly added in v2. So we call it backward semi-compatible if v2 can read what v1 wrote in this default unmarshalling mode, and similarly forward semi-compatible if v1 can read what v2 wrote in this default unmarshalling mode.

Technically, these are weaker than true backward/forward compatibility (since you can't do a draconian error detection), yet in practice it works just fine.

You can add, remove, or change any non-annotated fields, methods, inner/nested types, constructors, interfaces. Those changes are both backward and forward compatible, as they don't cause any change to the XML representation.

Adding super class is backward compatible and forward semi-compatible. Similarly, removing super class is forward compatible and backward semi-compatible.

Adding new annotated fields or methods is backward compatible and forward semi-compatible. Similarly, removing them is forward compatible and backward semi-compatible.

Changing a property is bit more tricky.

XmlType and XmlRootElement allows you to change a class name without affecting XML.

// BEFORE
@XmlRootElement
public class Foo { ... }

// AFTER: no XML change
@XmlRootElement(name="foo")
@XmlType(name="foo")
public class Bar { ... }

// BEFORE
public class Foo { ... }

// AFTER: no XML change
@XmlType(name="foo")
public class Bar { ... }

TODO.

XmlJavaTypeAdapter allows you to de-couple the in-memory representation and the XML representation by introducing an intermediate representation. The basic model is as follows:

In-memory objects  <===>  Intermediate objects   <===>
XML
                  adapter                         XMLBinding

Your adapter code will be responsible for converting in-memory objects to/from intermediate objects. Intermediate objects are then bound to XML by following the standard Jakarta XML Binding rules. See XmlAdapter for a general description of how adapters works.

Adapters extend from the XmlAdapter class and provide two methods "unmarshal" and "marshal" that converts values in both directions, and then the XmlJavaTypeAdapter annotation is used to tell Jakarta XML Binding where and what adapters kick in.

(TODO: more info about XmlJavaTypeAdapter needed)

One of the common use cases of XmlJavaTypeAdapter is to map a "value object" to a string in XML. The following example illustrates how to do this, by using java.awt.Color as an example.

@XmlRootElement
class Box {
  @XmlJavaTypeAdapter(ColorAdapter.class)
  @XmlElement
  Color fill;
}

class ColorAdapter extends XmlAdapter<String,Color> {
  public Color unmarshal(String s) {
    return Color.decode(s);
  }
  public String marshal(Color c) {
    return "#"+Integer.toHexString(c.getRGB());
  }
}

This maps to the following XML representation:

<box>
  <fill>#112233</fill>
</box>

Since XmlJavaTypeAdapter is on a field, this adapter only kicks in for this particular field. If you have many Color fields and would like them all to use the same adapter, you can move the annotation to a package:

@XmlJavaTypeAdapter(type=Color.class,value=ColorAdapter.class)
package foo;

@XmlRootElement
class Box {
  @XmlElement Color fill;
  @XmlElement Color border;
}

This causes all the fields in the classes in the foo package to use the same specified adapter.

Also see the DatatypeConverter class that defines a series of basic conversion routines that you may find useful.

Another useful technique is to define two properties, one for Jakarta XML Binding and the other for your application. See the following example:

@XmlRootElement
class Person {
  private int age;

  // This public property is for users
  @XmlTransient
  public int getAge() {
    return age;
  }
  public void setAge(int age) {
    this.age = age;
  }

  // This property is for Jakarta XML Binding
  @XmlAttribute(name="age")
  private String getAge_() {
    if(age==-1)  return "dead";
    else         return String.valueOf(age);
  }
  private void setAge_(String v) throws NumberFormatException {
    if(v.equals("dead"))   this.age=-1;
    else                   this.age=Integer.parseInt(age);
}

The main "age" property is public, but marked as XmlTransient, so it's exposed in your program, but Jakarta XML Binding will not map this to XML. There's another private "age_" property. Since this is marked with XmlAttribute, this is what Jakarta XML Binding is going to use to map to the attribute. The getter and setter methods on this property will handle the conversion between the in-memory representation and the XML representation.

One of the very common forms of cycle is a parent pointer. The following example illustrates a typical parent pointer, and how this can be turned into "natural" XML:

@XmlRootElement
class Department {
  @XmlAttribute
  String name;
  @XmlElement(name="employee")
  List<Employee> employees;
}

class Employee {
  @XmlTransient
  Department department;  // parent pointer
  @XmlAttribute
  String name;

  public void afterUnmarshal(Unmarshaller u, Object parent) {
    this.department = (Department)parent;
  }
}

This will produce the following XML:

<department name="accounting">
  <employee name="Joe Chin" />
  <employee name="Adam Smith" />
  ...
</department>

And reading this document back into Java objects will produce the expected tree with all the proper parent pointers set up correctly.

The first technique here is the use of XmlTransient on the parent pointer. This tells Jakarta XML Binding that you don't need this parent pointer to be represented explicitly in XML, because the fact that employee is always contained inside department implies the parent/child relationship. This causes the marshaller to produce the expected XML. However, when you unmarshal it, since this field is not bound, the Employee.department field will be left null.

That's where the second technique comes in, which is the use of the afterUnmarshal callback. This method is invoked by the Jakarta XML Binding implementation on each instance when the unmarshalling of a Employee object completes. Furthermore, the second parameter to the method is the parent object, which in this case is a Department object. So in this example, this sets up the parent pointer correctly.

This callback can be also used to perform other post-unmarshalling set up work.

TBD

When a reference to another object is annotated with XmlIDREF, its corresponding XML it will be referenced by xs:IDREF, instead of containment. See below for an example:

Example of @XmlID and @XmlIDREF

@XmlRootElement
class Root {
  List<Foo> foos;
  List<Bar> bars;
}
class Foo {
  // you don't have to make it an attribute, but that's more common
  @XmlAttribute @XmlIDREF Bar bar;
}
class Bar {
  // you don't have to make it an attribute, but that's more common
  @XmlAttribute @XmlID String id;
}

<xs:complexType name="foo">
  <xs:sequence/>
  <xs:attribute name="bar" type="xs:IDREF"/>
  </xs:sequence>
</xs:complexType>
<xs:complexType name="bar">
  <xs:sequence/>
  <xs:attribute name="id" type="xs:ID"/>
</xs:complexType>

<root>
  <foo bar="x"/>
  <foo bar="y"/>
  <bar id="x"/>
  <bar id="y"/>
</root>

There are a few things to consider when you do this. First, the object to be referenced must have an ID that is unique within the whole document. You'd also need to ensure that the referenced objects are contained somewhere else (like in the Root class in this case), or else Bar objects will never be marshalled. This technique can be used to remove the cyclic references, but it's only possible when your object model has an easy cut point.

Starting 2.1 EA2, the Eclipse Implementation of JAXB exposes CycleRecoverable interface. Applications can choose to implement this interface in some of its objects. When a cyclic reference is detected during marshalling, and if the object that formed a cycle implements this interface, then the method on this interface is called to allow an application to nominate its replacement to be written to XML. In this way, the application can recover from a cycle gracefully.

This technique allows you to cope with a situation where you cannot easily determine upfront as to where a cycle might happen. On the other hand, this feature is a Eclipse Implementation of JAXB feature. Another downside of this is that unless you nominate your replacement carefully, you can make the marshalling output invalid with respect to the schema, and thus you might hit another problem when you try to read it back later.

First, use an independent schema validator to check if your document is really valid with respect to the schema you compiled. When the root element of a document is invalid, then the unmarshaller will issue "unexpected element" errors. When a portion of a document is invalid, Eclipse Implementation of JAXB skips that portion, so the end result is that the unmarshalling returns normally, yet you notice that a part of the content tree is missing. This is often the desirable behavior, but it sometimes ends up masking a problem.

Also, try to install ValidationEventHandler on the unmarshaller. When a portion of a document is skipped, the unmarshaller notifies a ValidationEventHandler, so it allows you to see what's going on.

Unmarshaller u = ...;
// this implementation is a part of the API and convenient for trouble-shooting,
// as it prints out errors to System.out
u.setEventHandler(new jakarta.xml.bind.helpers.DefaultValidationEventHandler());

u.unmarshal(new File("foo.xml"));

Also consider installing a Schema object to the unmarshaller, so that the unmarshaller performs a schema validation while unmarshalling. Earlier I suggested that you try an independent schema validator, but for various reasons (not all tools are reliable, you might have made an error and used a different schema/instance), using validating unmarshalling is a better way to guarantee the validity of your instance document being unmarshalled. Please follow the JAXP tutorial for more about how to construct a Schema object from your schema.

If you are unmarshalling from XML parser APIs (such as DOM, SAX, StAX), then also make sure that the parser/DOM is configured with the namespace enabled.

(TODO: This also applies to the marshaller. Think about moving it.)

The other possibility is that JAXBContext is not set up correctly. JAXBContext "knows" a set of classes, and if it doesn't know a class that it's supposed to know, then the unmarshaller may fail to perform as you expected.

To verify that you created JAXBContext correctly, call JAXBContext.toString(). It will output the list of classes it knows. If a class is not in this list, the unmarshaller will never return an instance of that class. Make you see all the classes you expect to be returned from the unmarshaller in the list. When dealing with a large schema that spans across a large number of classes and packages, this is one possible cause of a problem.

If you noticed that a class is missing, explicitly specify that to JAXBContext.newInstance. If you are binding classes that are generated from XJC, then the easiest way to include all the classes is to specify the generated ObjectFactory class(es).

When a document is large, it's usually because there's repetitive parts in it. Perhaps it's a purchase order with a large list of line items, or perhaps it's an XML log file with large number of log entries.

This kind of XML is suitable for chunk-processing; the main idea is to use the StAX API, run a loop, and unmarshal individual chunks separately. Your program acts on a single chunk, and then throws it away. In this way, you'll be only keeping at most one chunk in memory, which allows you to process large documents.

See the streaming-unmarshalling example and the partial-unmarshalling example in the Eclipse Implementation of JAXB distribution for more about how to do this. The streaming-unmarshalling example has an advantage that it can handle chunks at arbitrary nest level, yet it requires you to deal with the push model --- Jakarta XML Binding unmarshaller will "push" new chunk to you and you'll need to process them right there.

In contrast, the partial-unmarshalling example works in a pull model (which usually makes the processing easier), but this approach has some limitations in databinding portions other than the repeated part.

The techniques discussed above can be used to handle this case as well, since they let you unmarshal chunks one by one. See the xml-channel example in the Eclipse Implementation of JAXB distribution for more about how to do this.

For further advanced cases, one could always run a streaming infoset conversion outside Jakarta XML Binding API and basically curve just the portion of the infoset you want to data-bind, and feed it as a complete infoset into Jakarta XML Binding API. Jakarta XML Binding API accepts XML infoset in many different forms (DOM, SAX, StAX), so there's a fair amount of flexibility in choosing the right trade off between the development effort in doing this and the runtime performance.

For more about this, refer to the respective XML infoset API.

The most basic notion of the marshalling is to take a Jakarta XML Binding-bound object that has @XmlRootElement, and write it out as a whole XML document. So perhaps you have a class like this:

class Point {
  @XmlElement
  public int x;
  @XmlElement
  public int y;
  Point(...) { ... }
}

Then you can do:

marshaller.marshal( new Point(1,3), System.out );
marshaller.marshal( new Point(1,3), new File("out.xml") );

.. and so on. There're seven Marshaller.marshal methods that takes different output media as the second parameter. If you are writing to a file, a socket, or memory, then you should use the version that takes OutputStream. Unless you change the target encoding to something else (default is UTF-8), there's a special marshaller codepath for OutputStream, which makes it run really fast. You also don't have to use BufferedOutputStream, since the Eclipse Implementation of JAXB does the adequate buffering.

You can also write to Writer, but in this case you'll be responsible for encoding characters, so in general you need to be careful. If you want to marshal XML into an encoding other than UTF-8, it's best to use the JAXB_ENCODING property and then write to OutputStream, as it escapes characters to things like ᠤ correctly.

The next medium we support is W3C DOM. This is bit unintuitive, but you'll do it like this:

DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
dbf.setNamespaceAware(true);
Document doc = dbf.newDocumentBuilder().newDocument();

marshaller.marshal( new Point(1,3), doc );

And after the method invocation you get a complete DOM tree that represents the marshalled document.

The other versions of the marshal methods are there to write XML documents in terms of other XML APIs, such as SAX and StAX. The version that takes ContentHandler is useful when you need a custom formatting needs (like you want each attribute to be in new line, etc), but otherwise they are not very interesting if you are writing a whole document.

Another common use of Jakarta XML Binding is where you are writing a bigger document, and you use Jakarta XML Binding to generate part(s) of it. The Eclipse Implementation of XML Web Services is the prime example. It produces a SOAP message, and Jakarta XML Binding is only used to produce the body. When you are doing this, you first set JAXB_FRAGMENT property on the marshaller. This changes the behaviors of the marshaller so that it works better in this situation.

If you are writing to an OutputStream or Writer and generally sending it to someone else, you can do something like this:

System.out.println("<envelope>");
marshaller.marshal( object, System.out );
System.out.println("</envelope>");

Like I mentioned, this is probably the fastest, even though println isn't very pretty. JAXB_FRAGMENT prevents the marshaller from producing an XML declaration, so the above works just fine. The downside of this approach is that if the ancestor elements declare the namespaces, Jakarta XML Binding won't be able to take advantage of them.

You can also marshal an object as a subtree of an existing DOM tree. To do this, you pass the Element object as the second parameter, and the marshaller will marshal an object as a child of this node.

StAX is also very convenient for doing this sort of things. You can create XMLStreamWriter, write some stuff, and then pass that to the marshaller. JAXB_FRAGMENT prevents the marshaller from producing startDocument and endDocument token. When doing this sub-tree marshaling to DOM and StAX, Jakarta XML Binding can take advantage of available in-scope namespace bindings.

Finally, you can marshal an object as a subtree into ContentHandler, but it requires a fair amount of SAX programming experience, and it goes beyond the scope of this entry.

Another common use case is where you have an object that doesn't have @XmlRootElement on it. Jakarta XML Binding allows you to marshal it like this:

marshaller.marshal( new JAXBElement(
  new QName("","rootTag"),Point.class,new Point(...)));

This puts the <rootTag> element as the root element, followed by the contents of the object, then </rootTag>. You can actually use it with a class that has @XmlRootElement, and that simply renames the root element name.

At the first glance the second Point.class parameter may look redundant, but it's actually necessary to determine if the marshaller will produce (infamous) @xsi:type. In this example, both the class and the instance are Point, so you won't see @xsi:type. But if they are different, you'll see it.

This can be also used to marshal a simple object, like String or an integer.

Marshalling a non-element with @xsi:type

marshaller.marshal( new JAXBElement(
  new QName("","rootTag"),String.class,"foo bar"));

But unfortunately it cannot be used to marshal objects like List or Map, as they aren't handled as the first-class citizen in the Jakarta XML Binding world.

Because of the Source and Result support, Jakarta XML Binding objects can be easily marshalled into other XML APIs that are not mentioned here. For example, dom4j has DocumentResult that extends Result, so you can do:

DocumentResult dr = new DocumentResult();
marshaller.marshal( object, dr );
o = dr.getDocument();

Similar mechanism is available for JDOM and XOM. This conversion is much more efficient than first marshalling to ByteArrayOutputStream and then read it back into these DOMs. The same mechanism can be used to marshal to FastInfoset or send the marshaled document to an XSLT engine (TransformerHandler.)

The other interesting connector is JAXBSource, which wraps a marshaller and allows a Jakarta XML Binding object to be used as a "source" of XML. Many XML APIs take Source as an input, and now Jakarta XML Binding object can be passed to them directly.

For example, you can marshal a Jakarta XML Binding object and unmarshal it into another JAXBContext like this:

JAXBContext context1 = ... ;
JAXBContext context2 = ... ;

context1.createUnmarshaller().unmarshal( new JAXBSource(context2,object) );

This amounts to looking at the same XML by using different schema, and again this is much more efficient than going through ByteArrayOutputStream.

The #1 cause of extra namespace declarations is due to the DOM mapping. This mainly happens because of a schema construct that forces XJC to generate a property with DOM. This includes the use of wildcard <xs:any/> (see more about this Mapping of <xs:any />), as well as xs:anyType (which can also happen by omission, such as <xs:element name="foo"/>, which is interpreted as <xs:element name="foo" type="xs:anyType" />.

During unmarshalling, when a subtree of the input XML is converted into XML, Jakarta XML Binding copies all the in-scope namespace bindings active at that time to the root of the DOM element. So for example, given the following Java class and XML, the DOM tree that the child field will get will look like the following:

@XmlRootElement
class Foo {
  @XmlAnyElement
  public Element child;
}

<foo xmlns:a="a" xmlns:b="b" xmlns:c="c">
  <subtree xmlns:c="cc">
    <data>a:xyz</data>
  </subtree>
</foo>

<subtree xmlns:a="a" xmlns:b="b" xmlns:c="cc">
    <data>a:xyz</data>
  </subtree>

Note that the two namespace declarations are copied over, but c is not because it's overridden. Also not that Jakarta XML Binding is not touching the whitespace in document. This copying of namespace declarations is necessary to preserve the infoset in the input document. For example, if the <data> is a QName, its meaning would change if Jakarta XML Binding unmarshaller doesn't copy it.

Now, imagine what happens when you marshal this back to XML. Despite the fact that in this example neither b nor c prefixes are in use, Jakarta XML Binding cannot delete them, because it doesn't know if those attributes are significant to the application or not. Therefore, this could end up producing XML with "extra namespace declarations" like:

<foo>
  <subtree xmlns:a="a" xmlns:b="b" xmlns:c="cc">
    <data>a:xyz</data>
  </subtree>
</foo>

Resolving this problem is not possible in the general case, but sometimes one of the following strategy works:

If the classes you'd like to generate schema from are already available as java.lang.Class objects (meaning they are already loaded and resolved in the current JVM), then the easiest way to generate a schema is to use the Jakarta XML Binding API:

File baseDir = new File(".");

class MySchemaOutputResolver extends SchemaOutputResolver {
    public Result createOutput( String namespaceUri, String suggestedFileName ) throws IOException {
        return new StreamResult(new File(baseDir,suggestedFileName));
    }
}

JAXBContext context = JAXBContext.newInstance(Foo.class, Bar.class, ...);
context.generateSchema(new MySchemaOutputResolver());

The CLI interface (public static int com.sun.tools.jxc.SchemaGenerator.run(String[])) is the easiest API to access. You can pass in all the schemagen command-line arguments as a string array, and get the exit code as an int value. Messages are sent to System.err and System.out.

Ant task can be invoked very easily from a non-Ant program. The schemagen ant task is defined in the SchemaGenTask class,

The above two interfaces are built on top of externally committed contracts, so they'll evolve only in a compatibile way. The downside is that the amount of control you can exercise over them would be limited.

So yet another approach to invoke schemagen is to use Eclipse Implementation of JAXB's internal interfaces. But be warned that those interfaces are subject to change in the future versions, despite our best effort to preserve them. This is the API that the Eclipse Implementation of XML Web Services uses to generate schema inside WSDL when they generate WSDL, so does some other web services toolkits that work with the Eclipse Implementation of JAXB.

Most of those interfaces are defined and well-documented in the com.sun.tools.xjc.api package. You can see how the schemagen tools are eventually calling into this API at the implementaion of SchemaGenerator class.

As of Eclipse Implementation of JAXB 4.0.3, currently no support for this, although there has been several discussions in the users alias.

The Eclipse Implementation of JAXB project is currently lacking resources to attack this problem, and therefore looking for volunteers to work on this project. The basic idea would be to define enough annotations to cover the basic constraint facets (such as length, enumerations, pattern, etc.) The schema generator would have to be then extended to honor those annotations and generate schemas accordingly.

Some users pointed out relevance of this to Jakarta Bean Validation. If you are interested in picking up this task, let us know!

In contrast to org.glassfish.jaxb artifacts, these jars have all dependency classes included inside.

Minimum requirement to compile is jakarta.xml.bind-api.jar. If a client application is running on an environment where Jakarta XML Binding runtime is provided, jakarta.xml.bind-api.jar is all that is needed.

                <!-- API -->
                <dependency>
                    <groupId>jakarta.xml.bind</groupId>
                    <artifactId>jakarta.xml.bind-api</artifactId>
                    <version>4.0.0</version>
                </dependency>

If client application needs to include the runtime, e.g. running standalone on Java SE jaxb-impl should be also included.

                <!-- API -->
                <dependency>
                    <groupId>jakarta.xml.bind</groupId>
                    <artifactId>jakarta.xml.bind-api</artifactId>
                    <version>4.0.0</version>
                </dependency>

                <!-- Runtime -->
                <dependency>
                    <groupId>com.sun.xml.bind</groupId>
                    <artifactId>jaxb-impl</artifactId>
                    <version>4.0.3</version>
                </dependency>

Eclipse Implementation of JAXB does reflectively access private members of the class, so client application if loaded from module path needs to "open" packages containing jaxb classes to Jakarta XML Binding. There are alternative Jakarta XML Binding implementations, having different module names, Jakarta XML Binding requires pojo classes to be open only to API module.

//JPMS module descriptor
module com.example.jaxbclasses {

    //Jakarta XML Binding module name
    requires jakarta.xml.bind;

    //open pojo package to make accessing private members possible for Jakarta XML Binding.
    opens com.example.jaxbclasses.pojos to jakarta.xml.bind;
}

Jakarta XML Binding API will delegate openness to implementation module after resolving it with service discovery mechanism.

#Both client and Eclipse Implementation of JAXB on module path:
$ java -m com.example.jaxbclasses/com.example.jaxb.Main --module-path jaxbclient.jar:jakarta.xml.bind-api.jar:jakarta.activation-api.jar:jaxb-core.jar:jaxb-impl.jar

#Both client and Eclipse Implementation of JAXB on classpath:
$ java com.example.jaxb.Main -cp jaxbclient.jar:jakarta.xml.bind-api.jar:jakarta.activation-api.jar:jaxb-core.jar:jaxb-impl.jar

#Client on classpath, Eclipse Implementation of JAXB on module path:
$ java com.example.jaxb.Main -cp jaxbclient.jar --module-path jakarta.xml.bind-api.jar:jakarta.activation-api.jar:jaxb-core.jar:jaxb-impl.jar --add-modules jakarta.xml.bind

Jakarta XML Binding API will delegate openness to implementation module after resolving it with service discovery mechanism.

The customization syntax for DTD is roughly based on the ver.0.21 working draft of the JAXB specification, which is available at xml.coverpages.org. The deviations from this document are: