35.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 35.22, “XML Schema Model Group” shows a model group with three elements.
Example 35.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 35.22, “XML Schema Model Group” you use <group ref="tns:passenger" /> as shown in Example 35.23, “Complex Type with a Model Group”.
Example 35.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 35.22, “XML Schema Model Group”. An example of an instance of reservation is shown in Example 35.24, “Instance of a Type with a Model Group”.
Example 35.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 35.25, “Type with a Group” shows the Java class generated for the complex type defined in Example 35.23, “Complex Type with a Model Group”.
Example 35.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:
- If the group is defined using a
sequence
element see Section 35.5.5, “Occurrence Constraints on Sequences”. - If the group is defined using a
choice
element see Section 35.5.3, “Occurrence Constraints on the Choice Element”.