JAXB - XML Schema Types, Defining Types for XML Elements With Content

Content: A Value

The content of an XML element may be some value, or one or more subordinate elements, or even a combination of both. Let's look at an XML element with a value of some type. This is defined by a schema construct like this:

<xsd:element name="Quantity" type="xsd:int"/>

This does not define another type, but it may occur as some part of a complex type definition that describes the structure and attributes of the containing element, this element itself and its siblings. Thexsd:element defines the XML tag, so that an example of this XML element is bound to look like this:

<Quantity>144</Quantity>

The Java code resulting from such an embedded element definition is part of some class definition, i.e., the one describing the containing element, and it consists of the declaration of an instance variable, a getter method (here: int getQuantity()) and, except for list types, a setter method (here: void setQuantity(int value)).

An element definition like this may also be provided for specifying the root element of an XML document. Obviously, such an element cannot be part of yet another type definition describing the structure of an enclosing element, simply because there is no such element. The code generated for a stand-alone element definition can be found in the class ObjectFactory which is generated along with all the classes derived from your schema's type definitions. So, from any stand-alone element definition that looks like this

<xsd:element name="Doc" type="DocType"/>

you may expect the generated class ObjectFactory to contain

public class ObjectFactory {
    private final static QName _Doc_QNAME = new QName("", "Doc");
    //...
    public JAXBElement<DocType> createDoc(DocType value) {
      return new JAXBElement<DocType>(_Doc_QNAME, DocType.class, null, value);
    }
    // ...
}

Notice that you are not restricted to a single document root element.

Content: An Ordered Set of Elements

The schema element xsd:sequence defines that the enclosed set of elements should occur in the given order and according to the specified minimum and maximum repetition counts. (The default for both is 1.) The following complex type defines a set of two coordinates.

<xsd:complexType name="PointType">
    <xsd:sequence>
        <xsd:element name="X" type="xsd:int"/>
        <xsd:element name="Y" type="xsd:int"/>
    </xsd:sequence>
</xsd:complexType>

The resulting Java code is straightforward.

public class PointType {

    protected int x;
    protected int y;

    public int getX() {
        return x;
    }

    public void setX(int value) {
        this.x = value;
    }

    public int getY() {
        return y;
    }

    public void setY(int value) {
        this.y = value;
    }
}

Content: An Unordered Set of Elements

Content consisting of a set of elements that may occur in any order within its parent XML element can be defined by using the schema element xsd:all. There is, however, a severe restriction: themaxOccurs may not have a value greater than 1. Here is the definition for an XML element describing the courses of a dinner which does not permit repetitions of any course, but you may omit all courses except for the main dish.

<xsd:complexType name="DinnerType">
    <xsd:all>
        <xsd:element name="Starter" type="xsd:string" minOccurs="0"/>
        <xsd:element name="Soup" type="xsd:string" minOccurs="0"/>
        <xsd:element name="Entree" type="xsd:string"/>
        <xsd:element name="Dessert" type="xsd:string" minOccurs="0"/>
    </xsd:all>
</xsd:complexType>

The generated Java conforms to the structure of a JavaBean:

public class LunchType {

    protected String starter;
    protected String soup;
    protected String entree;
    protected String dessert;

    public String getStarter() {
        return starter;
    }

    public void setStarter( String value ) {
        this.starter = value;
    }

    // ...(more getters and setters)
}

Here, the getters for the optional child elements may return null to distinguish "not present" from any possible value.

Content: Alternative Elements

The schema element xsd:choice lets you define a type for an XML element which has a content of exactly one element from a given set of alternatives.

<xsd:complexType name="CommType">
    <xsd:choice>
        <xsd:element name="SMS" type="xsd:string"/>
        <xsd:element name="MMS" type="xsd:string"/>
        <xsd:element name="Email" type="xsd:string"/>
    </xsd:choice>
</xsd:complexType>

Although only one out of the three elements will actually be present, the generated Java class provides instance variables and getters and setters for all alternatives.

public class CommType {

    protected String sms;
    protected String mms;
    protected String email;

    public String getSMS() {
        return sms;
    }

    public void setSMS(String value) {
        this.sms = value;
    }

    // ...(more getters and setters)
}

Although a handful of unused references isn't all that expensive, a Java class like this just doesn't have a nice feeling about it. Also, using such a class may easily lead to errors that are hard to track down. There is, for instance, nothing in the generated code that will keep you from calling more than one setter.

Content: A Homogeneous List of Elements

To define an element where some sub-element occurs repeatedly, we make use of the optional attributes minOccurs and maxOccurs. Various combinations are possible, permitting the definition of a list that may be empty, may contain any number of elements, or a fixed number. The definition of an unbounded list with at least two elements is given below. (PointType is shown in subsection Content: An Ordered Set of Elements.)

<xsd:complexType name="PolygonType">
    <xsd:sequence>
        <xsd:element name="Points" type="PointType" minOccurs="2" maxOccurs="unbounded"/>
    </xsd:sequence>
</xsd:complexType>

The resulting Java code does not express the required minimum of two points in a polygon. Here, and for all similar element lists, a java.util.List is used. Therefore the generated code will always be as simple as the one shown below.

public class PolygonType {

    protected List<PointType> points;

    public List<PointType> getPoints() {
        if (points == null) {
            points = new ArrayList<PointType>();
        }
        return this.points;
    }
}

The Javadoc documentation (omitted here) emphasizes that getPoints returns a reference to the actual list while making sure that the list is created. All methods defined in java.util.List may be applied to the returned value.Most importantly, code like this

polygon.getPoints().add( new PointType( 4, 9 ) );

adds another point. The list can be added to one by one, or you may use addAll for bulk additions, and you could remove or even clear to delete elements. With all of these possibilities there is just no need for a setter for the entire list.