33.6. Using Model Groups

Overview

XML Schema model groups are convenient shortcuts that allows you to reference a group of elements from a user-defined complex type.For example, you can define a group of elements that are common to several types in your application and then reference the group repeatedly. Model groups are defined using the group element, and are similar to complex type definitions. The mapping of model groups to Java is also similar to the mapping for complex types.

Defining a model group in XML Schema

You define a model group in XML Schema using the group element with the name attribute. The value of the name attribute is a string that is used to refer to the group throughout the schema. The group element, like the complexType element, can have the sequence element, the all element, or the choice element as its immediate child.
Inside the child element, you define the members of the group using element elements. For each member of the group, specify one element element. Group members can use any of the standard attributes for the element element including minOccurs and maxOccurs. So, if your group has three elements and one of them can occur up to three times, you define a group with three element elements, one of which uses maxOccurs="3". Example 33.22, “XML Schema Model Group” shows a model group with three elements.

Example 33.22. XML Schema Model Group

<group name="passenger">
  <sequence>
    <element name="name" type="xsd:string" />
    <element name="clubNum" type="xsd:long" />
    <element name="seatPref" type="xsd:string"
             maxOccurs="3" />
  </sequence>
</group>

Using a model group in a type definition

Once a model group has been defined, it can be used as part of a complex type definition. To use a model group in a complex type definition, use the group element with the ref attribute. The value of the ref attribute is the name given to the group when it was defined. For example, to use the group defined in Example 33.22, “XML Schema Model Group” you use <group ref="tns:passenger" /> as shown in Example 33.23, “Complex Type with a Model Group”.

Example 33.23. Complex Type with a Model Group

<complexType name="reservation">
  <sequence>
    <group ref="tns:passenger" />
    <element name="origin" type="xsd:string" />
    <element name="destination" type="xsd:string" />
    <element name="fltNum" type="xsd:long" />
  </sequence>
</complexType>
When a model group is used in a type definition, the group becomes a member of the type. So an instance of reservation has four member elements. The first element is the passenger element and it contains the member elements defined by the group shown in Example 33.22, “XML Schema Model Group”. An example of an instance of reservation is shown in Example 33.24, “Instance of a Type with a Model Group”.

Example 33.24. Instance of a Type with a Model Group

<reservation>
  <passenger>
    <name>A. Smart</name>
    <clubNum>99</clubNum>
    <seatPref>isle1</seatPref>
  </passenger>
  <origin>LAX</origin>
  <destination>FRA</destination>
  <fltNum>34567</fltNum>
</reservation>

Mapping to Java

By default, a model group is only mapped to Java artifacts when it is included in a complex type definition. When generating code for a complex type that includes a model group, Apache CXF simply includes the member variables for the model group into the Java class generated for the type. The member variables representing the model group are annotated based on the definitions of the model group.
Example 33.25, “Type with a Group” shows the Java class generated for the complex type defined in Example 33.23, “Complex Type with a Model Group”.

Example 33.25. Type with a Group

@XmlType(name = "reservation", propOrder = {
    "name",
    "clubNum",
    "seatPref",
    "origin",
    "destination",
    "fltNum"
})
public class Reservation {

    @XmlElement(required = true)
    protected String name;
    protected long clubNum;
    @XmlElement(required = true)
    protected List<String> seatPref;
    @XmlElement(required = true)
    protected String origin;
    @XmlElement(required = true)
    protected String destination;
    protected long fltNum;

    public String getName() {
        return name;
    }

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

    public long getClubNum() {
        return clubNum;
    }

    public void setClubNum(long value) {
        this.clubNum = value;
    }

    public List<String> getSeatPref() {
        if (seatPref == null) {
            seatPref = new ArrayList<String>();
        }
        return this.seatPref;
    }

    public String getOrigin() {
        return origin;
    }

    public void setOrigin(String value) {
        this.origin = value;
    }

    public String getDestination() {
        return destination;
    }

    public void setDestination(String value) {
        this.destination = value;
    }

    public long getFltNum() {
        return fltNum;
    }

    public void setFltNum(long value) {
        this.fltNum = value;
    }

Multiple occurrences

You can specify that the model group appears more than once by setting the group element's maxOccurs attribute to a value greater than one. To allow for multiple occurrences of the model group Apache CXF maps the model group to a List<T> object. The List<T> object is generated following the rules for the group's first child: