JAXB Guide

JAXB allows you to access XML documents like regular Java classes. It only works for documents that follow a fixed structure that can be described by a schema, a DTD or by a tree of Java classes.
The easiest way to use JAXB is with a XML Schema (XSD file). You can then just compile the schema using xjc. xjc generates annotated Java classes that you use to read and write the XML. Alternatively, you write your data structures as Java classes yourself and use annotations to map them onto the XML structure. An XML schema is not needed for this approach, but you can generate one from your code using the schemagen tool.
Once you have the annotated classes, JAXB can read XML documents and create object trees that represents them (this is called unmarshalling) and write them back into an XML document (marshalling). The object tree itself can be created, read and modified like any other Java object.

Use JAXB when..

• you want to easily read or write XML documents with a specific schema
• the documents are mainly structured data, not markup text (e.g. no XHTML or DocBook)
• throughput and performance is not your primary concern

Alternatives

• DOM provides a flexible object model that allows you to read and write any XML document. However, if your document has a known schema, using JAXB will be easier and less error-prone than the generic DOM model.
• StAX is a low-level pull API for reading any XML. It is fast and flexible, but also complicated to use and parsing a specific schema is hard to get right.
• SaX is a very old push XML API. Is is quite fast, but very difficult to use correctly. Avoid if possible.
• There are several XML APIs that are not part of any Java Edition. None of them is in wide-spread use anymore, even though they may have advantages over Java's APIs.

For JAXB 2.x...

• Java SE 6 (or higher) ships with JAXB 2.x
• Java EE 5 (or higher) ships with JAXB 2.x
• JAXB for Java SE 5 can be downloaded here
• JAXB 2.x can not be used for versions < Java 5

In case you don't already have a schema, you need to ask yourself whether you want to write the XML Schema first and generate classes for it using xjc, or whether you want to write the Java classes with JAXB annotations, and optionally generate the XML Schema later using schemagen.

• If you just want to serialize some data in XML, and don't really care too much what the XML looks like, write the definitions in Java. It's usually more convenient and the resulting Java classes are simpler and easier to use. This is called bottom-up design.
• If you care about the XML Schema (e.g. you want to publish it), write the Schema first and use xjc. This makes it a lot easier to have a good XML schema. This is called top-down design

If you have a schema, you can use xjc on the command line to get the classes that you need. xjc is included with both JDK6 and the JAXB reference implementation. Usage:

> xjc -d target-directory -p your.package.name path-to-schema

package com.jarfiller.example;
import java.util.*;
import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement
public class MovieLibrary {                      // root element
  private List<Movie> collection;

  public MovieLibrary() {                        // no-arg constructor required (more)
  }

  public MovieLibrary(List<Movie> collection) {  // convenience constructor
    this.collection = collection;
  }

  public void setCollection(List<Movie> collection) {
    this.collection = collection;
  }
  public List<Movie> getCollection() {
    return collection;
  }
}

public class Movie {                             // normal element - annotations are optional
  private String title;
  private int releaseYear;

  public Movie() {                               // no-arg constructor required (more)
  }

  public Movie(String title, int releaseYear) {
    this.title = title;
    this.releaseYear = releaseYear;
  }

  public String getTitle() {
    return title;
  }
  public void setTitle(String title) {
    this.title = title;
  }

  public int getReleaseYear() {
    return releaseYear;
  }
  public void setReleaseYear(int releaseYear) {
    this.releaseYear = releaseYear;
  }
}

Shorter alternative: just use public fields. The following classes would create exactly the same XML as the property-based bean above:

@XmlRootElement
public class MovieLibrary {
  public List<Movie> collection;
}

public class Movie {
  public String title;
  public int releaseYear;
}

This is the XML Schema that the schemagen tool will create, given the MovieLibrary class:

<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:complexType name="movieLibrary">
    <xs:sequence>
      <xs:element name="collection" type="movie" nillable="true"
                     minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="movie">
    <xs:sequence>
      <xs:element name="title" type="xs:string" minOccurs="0"/>
      <xs:element name="releaseYear" type="xs:int"/>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

Be careful with schemagen-generated schemas though: as in this example, they do not declare a top-level element. You may need to add it yourself:

<xs:element name="movieLibrary" type="movieLibrary"/>

List<Movie> movies = new java.util.ArrayList<Movie>();
movies.add(new Movie("Casablanca", 1942));
movies.add(new Movie("Dr Zhivago", 1965));
movies.add(new Movie("Out of Africa", 1985));
MovieLibrary library = new MovieLibrary(movies);

JAXB.marshal(library, new File("/tmp/library.xml"));  // write XML (more)

Result of the previous code snippet:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<movieLibrary>
    <collection>
        <name>Casablanca</name>
        <releaseYear>1942</releaseYear>
    </collection>
    <collection>
        <name>Dr Zhivago</name>
        <releaseYear>1965</releaseYear>
    </collection>
    <collection>
        <name>Out of Africa</name>
        <releaseYear>1985</releaseYear>
    </collection>
</movieLibrary>

MovieLibrary library = JAXB.unmarshal(new File("/tmp/library.xml"), 
                               MovieLibrary.class);  // read XML (more)

assert library.getCollection().size() == 3;
assert library.getCollection().get(0).getTitle().equals("Casablanca");
assert library.getCollection().get(2).getReleaseYear() == 1985;

Beside beans, JAXB supports the following types natively. Each of them can also be used either as element content or for XML attributes:

Collections are also supported by JAXB and can be used as element content:

To declare an XML namespace at the Java package level, create a file called package-info.java in the package's directory and declare the namespace using the @XmlSchema annotation like this (no class declaration needed):

@javax.xml.bind.annotation.XmlSchema(namespace="http://example.jarfiller.com")
package com.jarfiller.example;

Alternatively, you can also declare the schema separately for each class as well as for the XML root element:

@XmlRootElement(namespace="http://example.jarfiller.com")
@XmlType(namespace="http://example.jarfiller.com")
public class MovieLibrary {
  public List<Movie> collection;
}

@XmlType(namespace="http://example.jarfiller.com")
public class Movie {
    public String title;
    public int releaseYear;
}

With the annotation @XmlAttribute you can declare that a bean's property or field is represented by an attribute instead of by an element. Example (with properties):

public class Movie {
    private String title;
    private int releaseYear;

    @XmlAttribute
    public String getTitle() {
        return title;
    }
    public void setTitle(String title) {
        this.title = title;
    }

    @XmlAttribute
    public int getReleaseYear() {
        return releaseYear;
    }
    public void setReleaseYear(int releaseYear) {
        this.releaseYear = releaseYear;
    }
}

Resulting XML Schema fragment:

<xs:complexType name="movie">
    <xs:sequence/>
    <xs:attribute name="releaseYear" type="xs:int" use="required"/>
    <xs:attribute name="title" type="xs:string"/>
</xs:complexType>

Example XML fragment:

<ns2:movieLibrary xmlns:ns2="http://example.jarfiller.com">
    <collection title="Casablanca" releaseYear="1942" />
    <collection title="Dr Zhivago" releaseYear="1965" />
    <collection title="Out of Africa" releaseYear="1985" />
</ns2:movieLibrary>

By default, all XML elements in the generated schema are optional, unless the underlying Java type is a built-in type that does not allow null (such as int, boolean...). If you a value is required in an element, you must declare this explicitly:

public class Movie {
    private String title;
    private int releaseYear;

    @XmlElement(required=true)
    public String getTitle() {
        return title;
    }
    public void setTitle(String title) {
        this.title = title;
    }

    public int getReleaseYear() {  // int is always required (more)
        return releaseYear;
    }
    public void setReleaseYear(int releaseYear) {
        this.releaseYear = releaseYear;
    }
}

Resulting XML Schema fragment (the minOccurs attributes that made the elements optional have disappeared):

<xs:complexType name="movie">
    <xs:sequence>
        <xs:element name="releaseYear" type="xs:int"/>
        <xs:element name="title" type="xs:string"/>
    </xs:sequence>
</xs:complexType>

By default, JAXB uses the property name or field name as element name. If you don't want this, use an @XmlElement annotation with name parameter.

public class Movie {
    @XmlElement(name="movie-title")
    public String title;
    @XmlAttribute(name="release-year")
    public int releaseYear;
}

By default, JAXB will serialize all public fields and properties of a bean. However, you can control this behaviour using the @XmlAccessorType annotation at class or package level. Instead of the default XmlAccessType.PUBLIC you can specify that only properties (XmlAccessType.PROPERTY), fields (XmlAccessType.FIELD) or no members (XmlAccessType.NONE) are serialized without a explicit annotation. Then only @XmlElement-annotated members will be written:

@XmlAccessorType(XmlAccessType.NONE)
public class Movie {
    @XmlElement
    public String title;
    @XmlElement
    public int releaseYear;
    public String notWritten;  // will not be serialized
}

The serialization of specific members can also be prevented with the @XmlTransient annotation, or (for fields) with the transient modifier:

public class Movie {
    public String title;
    public int releaseYear;

    @XmlTransient
    public String notWritten1;            // will not be serialized

    public transient String notWritten2;  // will not be serialized
}

By default, the generated XML Schema for a bean require XML elements to have the same order that you defined your properties and fields in (using xs:sequence). Often this is not a good idea, because after refactoring the Java code may create a XML Schema incompatible with the old one. Therefore a specific order can be defined with the propOrder parameter of the @XmlType annotation:

@XmlType(propOrder={"title", "releaseYear"})
public class Movie {
    public int releaseYear;
    public String title;
}

If you do not care about the element order at all, you can also specify an empty propOrder sequence. The generated XML Schema will then use xs:all instead of xs:sequence, meaning that the XML elements can appear in any order. But note that the resulting schema may be more difficult to read, for humans as well as computers:

@XmlType(propOrder={})
public class Movie {
    public int releaseYear;
    public String title;
}

It is possible to put different XML elements in the same list. Let's say you want to create a collection of values that can either be strings, numbers or a key/value pair of strings. This can be represented by the following schema:

<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="values">
    <xs:complexType>
      <xs:choice minOccurs="0" maxOccurs="unbounded">
        <xs:element name="aString" type="xs:string"/>
        <xs:element name="aNumber" type="xs:int"/>
        <xs:element name="aKeyValuePair">
          <xs:complexType>
            <xs:sequence/>
            <xs:attribute name="key" type="xs:string"/>
            <xs:attribute name="value" type="xs:string"/>
          </xs:complexType>
        </xs:element>
      </xs:choice>
    </xs:complexType>
  </xs:element>
</xs:schema>

The problem here is that the aString, aNumber and aKeyValuePair elements do not have a common super-class. You can implement it in Java by using an Object collection and specifying all possible types that the collection may contain:

@XmlRootElement(name="values")
@XmlType(name="")    // anonymous (inline) type
public class Values {

  @XmlElements({     // declares the element choice
    @XmlElement(name="aKeyValuePair", type=Values.AKeyValuePair.class),
    @XmlElement(name="aString", type=String.class),
    @XmlElement(name="empty")
  })
  public List<Object> list = new new ArrayList<Object>();

  @XmlType(name="")  // anonymous (inline) type
  public static class AKeyValuePair {
    @XmlAttribute
    public String key;
    @XmlAttribute
    public String value;
  }
}

Simple types are types that consist only of text, without any elements. Examples for simple types are strings, numbers and dates.
JAXB has the @XmlValue type to implement simple types. To do this, you need to create a Java class to represent the type. Exactly one single property or field of the class must be annotated with the @XmlValue annotation. The property's (or field's) type must always map to a simple type (such as a string or number). The following example implements the class Price as simple type:

@XmlRootElement
public class PriceList {
	public List<Price> prices;
}

public class Price {
  @XmlValue
  public double amount;

  public Price(double amount) {
    this.amount = amount;
  }

  public Price() {
  }
}

Now the following marshalling code

PriceList priceList = new PriceList();
priceList.prices = Arrays.asList(new Price(99.95), new Price(74.90));
JAXB.marshal(priceList, System.out);

Note that will print this XML document:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<priceList>
  <prices>99.95</prices>
  <prices>74.9</prices>
</priceList>

Note that there is no <amount> element in the resulting XML, only PriceList's <prices> element.

You can also combine a @XmlValue in a class with an @XmlAttribute. The following example shows you how to use it:

public class Price {
  @XmlValue
  public double amount;

  @XmlAttribute
  public String currency;

  public Price(double amount, String currency) {
    this.amount = amount;
    this.currency = currency;
  }

  public Price() {
  }
}

Then the following code

PriceList priceList = new PriceList();
priceList.prices = Arrays.asList(new Price(99.95, "US Dollar"), new Price(74.90, "Euro"));
JAXB.marshal(priceList, System.out);

will print this XML document:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<priceList>
  <prices currency="US Dollar">99.95</prices>
  <prices currency="Euro">74.9</prices>
</priceList>

Not every @XmlValue property needs to be backed by an actual field, of course. You can also use it to construct a simple typed value from several other values:

public class Price {
  private double amount;
  private String currency;

  public Price(double amount, String currency) {
    this.amount = amount;
    this.currency = currency;
  }

  public Price() {
  }

  @XmlValue
  public String getValue() {
    return amount + " " + currency;
  }

  public void setValue(String v) {  // bad code, no error handling!
    amount = Double.parseDouble(v.replaceFirst("\\s.*$", ""));
    currency = v.replaceFirst("^.*\\s", "");
  }
}

When using the same content tree as in the previous example, the resulting XML will be:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<priceList>
  <prices>99.95 US Dollar</prices>
  <prices>74.9 Euro</prices>
</priceList>

The XmlAdapter interface allows you to serialize any Java type to XML, by providing a XmlAdapter implementation that maps the arbitrary Java object to a JAXB supported object.
For example, the following class is not JAXB-compatible because it lacks the argument-less default constructor and its fields are final:

public class EMailAddress {  // not JAXB-compatible
  public final String user, hostname;

  public EMailAddress(String user, String hostname) {
    this.user = user;
    this.hostname = hostname;
  }
}

The first step for mapping the EMailAddress class to XML is creating or finding a suitable JAXB-compatible type that can represent it. So let's define a bean XmlEMailAddress that can be serialized by JAXB:

public class XmlEMailAddress {   // JAXB-compatible
  public String user;
  public String hostname;
}

The next step is to implement the XmlAdapter and provide methods to convert between EMailAddress and XmlEMailAddress:

public class XmlEMailAddressAdapter extends XmlAdapter<XmlEMailAddress, EMailAddress> {
  @Override
  public XmlEMailAddress marshal(EMailAddress v) {
    XmlEMailAddress a = new XmlEMailAddress();
    a.user = v.user;
    a.hostname = v.hostname;
    return a;
  }

  @Override
  public EMailAddress unmarshal(XmlEMailAddress v){
    return new EMailAddress(v.user, v.hostname);
  }
}

Now you only need to declare that the XmlAdapter should be used for EMailAddress. For this you need the XmlJavaTypeAdapter annotation. It can be used at a property-level (to define the adapter only for this property or field), at the mapped class, or at the package level to define an adapter for the whole package. In this example, a class EMail is defined that uses the adapter only for a single property:

@XmlRootElement
public class EMail {
  @XmlJavaTypeAdapter(value=XmlEMailAddressAdapter.class)
  public EMailAddress recipient;

  public String body;
}

Now EMail can be used like any other class:

EMail mail = new EMail();
mail.recipient = new EMailAddress("recipient", "example.com");
mail.body = "Hello!";
JAXB.marshal(mail, System.out);

This is the output of the last code fragment:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<eMail>
    <recipient>
        <user>recipient</user>
        <hostname>example.com</hostname>
    </recipient>
    <body>Hello!</body>
</eMail>

An adapter can also map to a simple type such as a string. The following example shows an adapter that converts the EMail class into a string with the usual email notation:

public class XmlEMailAddressAdapter extends XmlAdapter<String, EMailAddress> {
  @Override
  public String marshal(EMailAddress v) throws Exception {
    return v.user + "@" + v.hostname;
  }

  @Override
  public EMailAddress unmarshal(String v) throws Exception {
    return new EMailAddress(v.replaceFirst("@.*$", ""), v.replaceFirst("^.*@", ""));
  }
}

When this is used as XmlAdapter, the following XML will be generated:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<eMail>
    <recipient>recipient@example.com</recipient>
    <body>Hello!</body>
</eMail>

JAXBElement is used in JAXB where the XML Schema can not be represented by a Java bean. You will often encounter it when compiling complex XML Schema documents with xjc. Each JAXBElement corresponds to an XML element. It stores the element's tag name as well as its content. The content of a JAXBElement can be any object supported by JAXB, beans or simple types.
The following example

Movie movieContent = new Movie("Casablanca", 1942);
JAXBElement<Movie> myMovie = new JAXBElement<Movie>(new QName("myMovie"),
                                           Movie.class, movieContent);
JAXB.marshal(myMovie, new File("/tmp/movie.xml"));

will create this XML:

<myMovie>
  <releaseYear>1942</releaseYear>
  <title>Casablanca</title>
</myMovie>

Note that the tag name of the generated element is not Movie, but myMovie, as specified in the JAXBElement.

JAXBElement for Choice

Here is an example for a XML Schema that will need JAXBElement:

<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="movieSoSoLibrary">
    <xs:complexType>
      <xs:choice minOccurs="0" maxOccurs="unbounded">
        <xs:element name="goodMovie" type="movie" nillable="true"/>
        <xs:element name="badMovie" type="movie" nillable="true"/>
      </xs:choice>
    </xs:complexType>
  </xs:element>

  <xs:complexType name="movie">
    <xs:sequence>
      <xs:element name="releaseYear" type="xs:int"/>
      <xs:element name="title" type="xs:string"/>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

In this example, the tag names goodMovie and badMovie can both be used to represent the movie type. In order to differentiate a goodMovie from a badMovie, even though both are represented by the Movie class, xjc will create the following code:

@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "", propOrder = { "goodMovieOrBadMovie" })
@XmlRootElement(name = "movieSoSoLibrary")
public class MovieSoSoLibrary {

  @XmlElementRefs({
    @XmlElementRef(name = "goodMovie", type = JAXBElement.class),
    @XmlElementRef(name = "badMovie", type = JAXBElement.class)
  })
  protected List<JAXBElement<Movie>> goodMovieOrBadMovie;

  public List<JAXBElement<Movie>> getGoodMovieOrBadMovie() {
    if (goodMovieOrBadMovie == null) {
      goodMovieOrBadMovie = new ArrayList<JAXBElement<Movie>>();
    }
  return this.goodMovieOrBadMovie;
  }
}

When xjc generates such code, it places factory methods for the JAXBElement instances into a class called ObjectFactory. There you can find the following definitions for creating goodMovie and badMovie elements:

@XmlElementDecl(namespace = "", name = "badMovie", scope = MovieSoSoLibrary.class)
public JAXBElement<Movie> createMovieSoSoLibraryBadMovie(Movie value) {
  return new JAXBElement<Movie>(_MovieSoSoLibraryBadMovie_QNAME, 
                                   Movie.class, MovieSoSoLibrary.class, value);
}

@XmlElementDecl(namespace = "", name = "goodMovie", scope = MovieSoSoLibrary.class)
public JAXBElement<Movie> createMovieSoSoLibraryGoodMovie(Movie value) {
  return new JAXBElement<Movie>(_MovieSoSoLibraryGoodMovie_QNAME, 
                                   Movie.class, MovieSoSoLibrary.class, value);
}

Note that the @XmlElementRef annotations in the MovieSoSoLibrary refer to the @XmlElementDecl annotations in ObjectFactory.

JAXBContext represents a collection of JAXB-enabled classes. You create it with either a list of JAXB-enabled classes, or using a 'context path' containing a list of colon-separated packages (read newInstance(String,ClassLoader) for details). Once you have the JAXBContext, you can obtain Marshaller and Unmarshaller objects from it, which will do the acutal serialization.
When you use the methods JAXB.marshal and JAXB.unmarshall shown in the previous sections, you don't need to take care of the JAXBContext yourself - it will all be done automatically. JAXBContext is only needed when you want to customize the serialization process.

Creating JAXBContext by Class

This is a simplest way to create a JAXBContext. Note that not only the MovieLibrary class will be in the context, but also all beans it refers to:

JAXBContext ctx = JAXBContext.newInstance(MovieLibrary.class);

You can also add more classes:

JAXBContext ctx = JAXBContext.newInstance(MovieLibrary.class, Movie.class);

Creating JAXBContext by Package

You can also generate the context for one or more packages, but only if you generated them using xjc (more). Just list the package names, separated by colons:

JAXBContext ctx = JAXBContext.newInstance("com.jarfiller.example:com.jarfiller.xml");

Using the methods JAXB.marshal and JAXB.unmarshall, as shown in the previous sections, is the most convenient way of using JAXB. Unfortunately, they do no allow any customization of the serialization and deserialization processes, and they are not available JAXB 2.0. In order to get around these limitations, you have to work with the JAXBContext, Marshaller and Unmarshaller objects.
The following example shows you how to write a Java object into an XML document using Marshaller:

MovieLibrary library = ...;

JAXBContext ctx = JAXBContext.newInstance(MovieLibrary.class);  // create JAXBContext (more)
Marshaller marshaller = ctx.createMarshaller();
marshaller.marshal(library, new FileOutputStream("/tmp/library.xml"));

Note that the example above only works if you declared the @XmlRootElement for the MovieLibrary class. This shouldn't be a problem for classes you wrote yourself. However, the xjc compiler does not set it automatically under some circumstances (more). In this case you must set the root element's name explicitly and the marshal call looks like this:

marshaller.marshal(new JAXBElement<MovieLibrary>(new QName("movieLibrary"), 
                                                    MovieLibrary.class, library),
                   new FileOutputStream("/tmp/library.xml"));

Loading XML with the Unmarshaller is similar to storing:

JAXBContext ctx = JAXBContext.newInstance(MovieLibrary.class);  // can be reused
Unmarshaller unmarshaller = ctx.createUnmarshaller();
MovieLibrary library = unmarshaller.unmarshal(new StreamSource(new File("/tmp/library.xml")),
                                              MovieLibrary.class).getValue();

A XML Schema allows more restrictions than Java's object model. For example, Java does not allow you to limit the length of a string. If you have a XML schema, you can let JAXB check the XML during the transformation process to be sure that the input and output is valid. First, you need to create a Schema instance (javax.xml.validation package):

SchemaFactory factory = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);
Schema schema = factory.newSchema(new StreamSource(new File("schema1.xsd")));

Now that you have the Schema, just set the property in the Marshaller to validate the generated XML:

MovieLibrary library = ...;

JAXBContext ctx = JAXBContext.newInstance(MovieLibrary.class);
Marshaller marshaller = ctx.createMarshaller();
marshaller.setSchema(schema);
marshaller.marshal(new JAXBElement<MovieLibrary>(new QName("movieLibrary"), 
                                                    MovieLibrary.class, library),
                   new FileOutputStream("/tmp/library.xml"));

To validate XML before you read it, set the schema property in the Unmarshaller:

JAXBContext ctx = JAXBContext.newInstance(MovieLibrary.class);  // can be reused
Unmarshaller unmarshaller = ctx.createUnmarshaller();
unmarshaller.setSchema(schema);
MovieLibrary library = unmarshaller.unmarshal(new StreamSource(new File("/tmp/library.xml")),
                                              MovieLibrary.class).getValue();

Reading or writing an invalid document causes JAXB to throw an exception.

By default, JAXB creates compact XML that can not easily be read by humans. If you want to format it more nicely, you need to set the JAXB_FORMATTED_OUTPUT property of the Marshaller:

MovieLibrary library = ...;

JAXBContext ctx = JAXBContext.newInstance(MovieLibrary.class);
Marshaller marshaller = ctx.createMarshaller();
marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
marshaller.marshal(new JAXBElement<MovieLibrary>(new QName("movieLibrary"), 
                                                    MovieLibrary.class, library),
                   new FileOutputStream("/tmp/library.xml"));

If you want to create an XML fragment (a XML snippet without XML declaration that can be included into other XML documents) instead of a document, you need to set the JAXB_FRAGMENT property of the Marshaller:

MovieLibrary library = ...;

JAXBContext ctx = JAXBContext.newInstance(MovieLibrary.class);
Marshaller marshaller = ctx.createMarshaller();
marshaller.setProperty(Marshaller.JAXB_FRAGMENT, true);
marshaller.marshal(new JAXBElement<MovieLibrary>(new QName("movieLibrary"), 
                                                    MovieLibrary.class, library),
                   new FileOutputStream("/tmp/library.xml"));

Sometimes you need to use a specific charset for the XML output instead the default UTF-8. You can use the JAXB_ENCODING property of the Marshaller to set it:

MovieLibrary library = ...;

JAXBContext ctx = JAXBContext.newInstance(MovieLibrary.class);
Marshaller marshaller = ctx.createMarshaller();
marshaller.setProperty(Marshaller.JAXB_ENCODING, "iso-8859-15");
marshaller.marshal(new JAXBElement<MovieLibrary>(new QName("movieLibrary"), 
                                                    MovieLibrary.class, library),
                   new FileOutputStream("/tmp/library.xml"));

The Marshaller interface provides several ways of interoperating with code that expects XML as a DOM tree or is implemented as SAX ContentHandler.

MovieLibrary library = new MovieLibrary();
Marshaller m = ...;

// Writing into a DOM tree
Document doc = ...;         // DOM Document
m.marshal(library, doc);    // write into the given DOM node

// Writing to a SAX ContentHandler
ContentHandler handler = ...;
marshal(library, handler);  // write into ContentHandler

In addition to the marshal variants, there is also the optional operation getNode, which would return a live DOM tree corrensponding to the JAXB content tree. Java's default implemention does not support this operation though.

The Unmarshaller interface provides a variant of the unmarshall method that reads a DOM Node.

Node node = ...;
Unmarshaller m = ...;

MovieLibrary library = (MovieLibrary) m.unmarshal(node);  // read from DOM node

JAXB allows you to read from a Reader, which can easily be used to read from a String:

String xml = "<movieLibrary><collection>"+
             "<name>Up</name><releaseYear>2009</releaseYear>"+
             "</collection></movieLibrary>";

StringReader reader = new StringReader(xml);
MovieLibrary lib = JAXB.unmarshall(reader, MovieLibrary.class);

Note that JAXB will ignore any character encoding set in the XML prolog.

In general, it is not recommended to serialize XML into a String. XML is defined as a binary format, and ideally you should write handle it as such. When storing an 'XML string' you need to be aware of the character encoding defined in the XML prolog. If you write your 'XML string' in the wrong encoding you will run into trouble.

Now, after the obligatory warning, it is possible and actually quite easy to write your JAXB tree into an 'XML string':

MovieLibrary ml = ...;

StringWriter writer = new StringWriter();
JAXB.marshall(ml, writer);
String xmlText = writer.toString();

Java's XPath engine is not able to use JAXB content trees directly. You either need to convert it to a DOM tree or to a binary XML document first. The following example shows you how to use DOM for running XPath:

MovieLibrary library = ...;

JAXBContext ctx = JAXBContext.newInstance(MovieLibrary.class);
Marshaller marshaller = ctx.createMarshaller();

DocumentBuilderFactory domFactory = DocumentBuilderFactory.newInstance();
DocumentBuilder domBuilder = domFactory.newDocumentBuilder();
Document doc = domBuilder.newDocument();
marshaller.marshal(library, doc);

XPathFactory factory = XPathFactory.newInstance();
XPath xpath = factory.newXPath();

NodeList list = (NodeList) xpath.evaluate(
          "/movieLibrary/collection[releaseYear < 1980]/title",
          doc, XPathConstants.NODESET);
for (int i = 0; i < list.getLength(); i++)  // print list of movies older than 1980
  System.out.println(list.item(i).getTextContent());

An alternative for running 'real' XPath expressions over the XML is to use JXPath, which allows you to run XPath expressions over Java object trees.

Java's XSLT framework (TrAX) can use JAXB content trees as input or output of XSLT transformations. You can find the required helper classes JAXBSource and JAXBResult in the javax.xml.bind.util package.
The following example transforms a MovieLibrary document to another MovieLibrary using a XSLT file:

MovieLibrary library = ...;

JAXBContext ctx = JAXBContext.newInstance(MovieLibrary.class);
JAXBSource src = new JAXBSource(ctx, library);
JAXBResult result = new JAXBResult(ctx);

TransformerFactory factory = TransformerFactory.newInstance();
Transformer transformer = factory.newTransformer(new StreamSource(new File("myTemplate.xslt")));
transformer.transform(src, result);

MovieLibrary modifiedLibrary = (MovieLibrary) result.getResult();

Using JAXBSource it is also possible to provide the stylesheet itself as JAXB content tree.

Consider the following things:

• The static helper methods in the JAXB class (JAXB.marshal and JAXB.unmarshall) should be avoided if you need to invoke them repeatedly. Instead, create a JAXBContext instance once and work with the Marshaller and Unmarshaller interfaces.
• Make sure you have only a single JAXBContext instance and share it across objects and threads.
• Don't use schema validation (if possible).
• Check that you use the best source or destination for the serialization/deserialization process. For example, if you want to transmit XML over the net, write it directly into the connection's OutputStream. Try to avoid temporary storage of the XML using ByteArray streams or in DOM trees.
• If the document contains binary data, use a XOP transport if possible.
• If you are sure you can't reach your performance target using JAXB, switch to the XMLStreamReader/XMLStreamWriter interfaces (StAX API) for those parts that are too slow. Note that using this low-level API can be a lot more work than using JAXB, and getting the code to work right in all possible situations (e.g. comments in the middle of an XML text) is even more difficult.

The rules for JAXB in a multi-threaded environment are very simple: you can share the JAXBContext object among threads. Doing so will also improve performance, as the construction of the context may be expensive. All other objects, including Marshaller and Unmarshaller, are not thread-safe and must not be shared. The static helper methods in the JAXB class can be used from several threads, of course.
In practice, this means that if you need a JAXBContext instance, you should probably store in a static member.