Chapter 33. Using Complex Types

Abstract

Complex types can contain multiple elements and they can have attributes. They are mapped into Java classes that can hold the data represented by the type definition. Typically, the mapping is to a bean with a set of properties representing the elements and the attributes of the content model..

33.1. Basic Complex Type Mapping

Overview

XML Schema complex types define constructs containing more complex information than a simple type. The most simple complex types define an empty element with an attribute. More intricate complex types are made up of a collection of elements.
By default, an XML Schema complex type is mapped to a Java class, with a member variable to represent each element and attribute listed in the XML Schema definition. The class has setters and getters for each member variable.

Defining in XML Schema

XML Schema complex types are defined using the complexType element. The complexType element wraps the rest of elements used to define the structure of the data. It can appear either as the parent element of a named type definition, or as the child of an element element anonymously defining the structure of the information stored in the element. When the complexType element is used to define a named type, it requires the use of the name attribute. The name attribute specifies a unique identifier for referencing the type.
Complex type definitions that contain one or more elements have one of the child elements described in Table 33.1, “Elements for Defining How Elements Appear in a Complex Type”. These elements determine how the specified elements appear in an instance of the type.

Table 33.1. Elements for Defining How Elements Appear in a Complex Type

ElementDescription
allAll of the elements defined as part of the complex type must appear in an instance of the type. However, they can appear in any order.
choiceOnly one of the elements defined as part of the complex type can appear in an instance of the type.
sequenceAll of the elements defined as part of the complex type must appear in an instance of the type, and they must also appear in the order specified in the type definition.
Note
If a complex type definition only uses attributes, you do not need one of the elements described in Table 33.1, “Elements for Defining How Elements Appear in a Complex Type”.
After deciding how the elements will appear, you define the elements by adding one or more element element children to the definition.
Example 33.1, “XML Schema Complex Type” shows a complex type definition in XML Schema.

Example 33.1. XML Schema Complex Type

<complexType name="sequence">
  <sequence>
    <element name="name" type="xsd:string" />
    <element name="street" type="xsd:short" />
    <element name="city" type="xsd:string" />
    <element name="state" type="xsd:string" />
    <element name="zipCode" type="xsd:string" />
  </sequence>
</complexType>

Mapping to Java

XML Schema complex types are mapped to Java classes. Each element in the complex type definition is mapped to a member variable in the Java class. Getter and setter methods are also generated for each element in the complex type.
All generated Java classes are decorated with the @XmlType annotation. If the mapping is for a named complex type, the annotations name is set to the value of the complexType element's name attribute. If the complex type is defined as part of an element definition, the value of the @XmlType annotation's name property is the value of the element element's name attribute.
Note
As described in the section called “Java mapping of elements with an in-line type”, the generated class is decorated with the @XmlRootElement annotation if it is generated for a complex type defined as part of an element definition.
To provide the runtime with guidelines indicating how the elements of the XML Schema complex type should be handled, the code generators alter the annotations used to decorate the class and its member variables.
All Complex Type
All complex types are defined using the all element. They are annotated as follows:
  • The @XmlType annotation's propOrder property is empty.
  • Each element is decorated with the @XmlElement annotation.
  • The @XmlElement annotation's required property is set to true.
Example 33.2, “Mapping of an All Complex Type” shows the mapping for an all complex type with two elements.

Example 33.2. Mapping of an All Complex Type

@XmlType(name = "all", propOrder = {

})
public class All {
    @XmlElement(required = true)
    protected BigDecimal amount;
    @XmlElement(required = true)
    protected String type;

    public BigDecimal getAmount() {
        return amount;
    }

    public void setAmount(BigDecimal value) {
        this.amount = value;
    }

    public String getType() {
        return type;
    }

    public void setType(String value) {
        this.type = value;
    }
}
Choice Complex Type
Choice complex types are defined using the choice element. They are annotated as follows:
  • The @XmlType annotation's propOrder property lists the names of the elements in the order they appear in the XML Schema definition.
  • None of the member variables are annotated.
Example 33.3, “Mapping of a Choice Complex Type” shows the mapping for a choice complex type with two elements.

Example 33.3. Mapping of a Choice Complex Type

@XmlType(name = "choice", propOrder = {
    "address",
    "floater"
})
public class Choice {

    protected Sequence address;
    protected Float floater;

    public Sequence getAddress() {
        return address;
    }

    public void setAddress(Sequence value) {
        this.address = value;
    }

    public Float getFloater() {
        return floater;
    }

    public void setFloater(Float value) {
        this.floater = value;
    }

}
Sequence Complex Type
A sequence complex type is defined using the sequence element. It is annotated as follows:
  • The @XmlType annotation's propOrder property lists the names of the elements in the order they appear in the XML Schema definition.
  • Each element is decorated with the @XmlElement annotation.
  • The @XmlElement annotation's required property is set to true.
Example 33.4, “Mapping of a Sequence Complex Type” shows the mapping for the complex type defined in Example 33.1, “XML Schema Complex Type”.

Example 33.4. Mapping of a Sequence Complex Type

@XmlType(name = "sequence", propOrder = {
    "name",
    "street",
    "city",
    "state",
    "zipCode"
})
public class Sequence {

    @XmlElement(required = true)
    protected String name;
    protected short street;
    @XmlElement(required = true)
    protected String city;
    @XmlElement(required = true)
    protected String state;
    @XmlElement(required = true)
    protected String zipCode;

    public String getName() {
        return name;
    }

    public void setName(String value) {
        this.name = value;
    }

    public short getStreet() {
        return street;
    }

    public void setStreet(short value) {
        this.street = value;
    }

    public String getCity() {
        return city;
    }

    public void setCity(String value) {
        this.city = value;
    }

    public String getState() {
        return state;
    }

    public void setState(String value) {
        this.state = value;
    }

    public String getZipCode() {
        return zipCode;
    }

    public void setZipCode(String value) {
        this.zipCode = value;
    }
}