JAXB - Annotations, Top-level Elements: XmlRootElement

A class that describes an XML element that is to be a top-level element, i.e., one that can function as an XML document, should be annotated with XmlRootElement. Its optional elements are name and namespace. By default, the class name is used as the name.

This annotation corresponds to an xsd:element construct being used at the outermost level of an XML schema. The sequence of Java, XML and schema snippets given below illustrates this relation.

@XmlRootElement( name="doc" )
public class Document {
   @XmlElement
   protected Foo foo;
   // ...
}

<?xml version="1.0" encoding="UTF-8"?>
<doc>
    <foo>...</foo>
</doc>

<?xml version="1.0" encoding="UTF-8"?>
<xsd:complexType name="Foo">
    ...
</xsd:complexType>
<xsd:complexType name="Document">
    <xsd:sequence>
        <xsd:element name="foo" type="Foo"/>
    </xsd:sequence>
</xsd:complexType>
<xsd:element name="doc" type="Document"/>

It's a surprising fact that if all of your Java classes permit a straightforward mapping to XML Schema, XmlRootElement may be the only annotation you have to make! Here's a small set of classes, that is even capable of marshalling a Map<K,V>.

import java.util.HashMap;
import java.util.Map;
import javax.xml.bind.annotation.*;

@XmlRootElement(name="doc")
public class DocType {
    public Map<KeyType,EntryType> key2entry =
        new HashMap<KeyType,EntryType>();
    public DocType(){
    }
}

import javax.xml.datatype.*;
public class KeyType {
    public String               event;
    public XMLGregorianCalendar datetime;
    public KeyType(){}
    public KeyType( String event, XMLGregorianCalendar datetime ){
        this.event    = event;
        this.datetime = datetime;
    }
}

public class EntryType {
    public String program;
    public String artists;

    public EntryType(){}
    public EntryType( String artists, String program ){
        this.artists = artists;
        this.program = program;
    }
}

Applying the usual incantations for creating and marshalling content, you could produce XML data like so:

<doc>
    <key2entry>
        <entry>
            <key>
                <event>Soiree</event>
                <datetime>2008-08-23T20:00:00</datetime>
            </key>
            <value>
                <program>Man on the Moon</program>
                <artists>R.E.M</artists>
            </value>
        </entry>
    </key2entry>
</doc>

The XMLGregorianCalendar is mapped to xsd:dateTime, and the 'T' between the date and the time is just right, according to the Schema Datatypes specification. You can see that JAXB had to "invent" a few tag names for the intermediary element levels separating map entries from each other, and key data from value data, but you'd have to do something similar if you'd design it yourself.