35.5. Occurrence Constraints
35.5.1. Schema Elements Supporting Occurrence Constraints
XML Schema allows you to specify the occurrence constraints on four of the XML Schema elements that make up a complex type definition:
35.5.2. Occurrence Constraints on the All Element
XML Schema
Complex types defined with the
all
element do not allow for multiple occurrences of the structure defined by the all
element. You can, however, make the structure defined by the all
element optional by setting its minOccurs
attribute to 0
.
Mapping to Java
Setting the
all
element's minOccurs
attribute to 0
has no effect on the generated Java class.
35.5.3. Occurrence Constraints on the Choice Element
Overview
By default, the results of a
choice
element can only appear once in an instance of a complex type. You can change the number of times the element chosen to represent the structure defined by a choice
element is allowed to appear using its minOccurs
attribute and its mxOccurs
attribute. Using these attributes you can specify that the choice type can occur zero to an unlimited number of times in an instance of a complex type. The element chosen for the choice type does not need to be the same for each occurrence of the type.
Using in XML Schema
The
minOccurs
attribute specifies the minimum number of times the choice type must appear. Its value can be any positive integer. Setting the minOccurs
attribute to 0
specifies that the choice type does not need to appear inside an instance of the complex type.
The
maxOccurs
attribute specifies the maximum number of times the choice type can appear. Its value can be any non-zero, positive integer or unbounded
. Setting the maxOccurs
attribute to unbounded
specifies that the choice type can appear an infinite number of times.
Example 35.18, “Choice Occurrence Constraints” shows the definition of a choice type, ClubEvent, with choice occurrence constraints. The choice type overall can be repeated 0 to unbounded times.
Example 35.18. Choice Occurrence Constraints
<complexType name="ClubEvent"> <choice minOccurs="0" maxOccurs="unbounded"> <element name="MemberName" type="xsd:string"/> <element name="GuestName" type="xsd:string"/> </choice> </complexType>
Mapping to Java
Unlike single instance choice structures, XML Schema choice structures that can occur multiple times are mapped to a Java class with a single member variable. This single member variable is a
List<T>
object that holds all of the data for the multiple occurrences of the sequence. For example, if the sequence defined in Example 35.18, “Choice Occurrence Constraints” occurred two times, then the list would have two items.
The name of the Java class' member variable is derived by concatenating the names of the member elements. The element names are separated by
Or
and the first letter of the variable name is converted to lower case. For example, the member variable generated from Example 35.18, “Choice Occurrence Constraints” would be named memberNameOrGuestName
.
The type of object stored in the list depends on the relationship between the types of the member elements. For example:
- If the member elements are of the same type the generated list will contain
JAXBElement<T>
objects. The base type of theJAXBElement<T>
objects is determined by the normal mapping of the member elements' type. - If the member elements are of different types and their Java representations implement a common interface, the list will contains objects of the common interface.
- If the member elements are of different types and their Java representations extend a common base class, the list will contains objects of the common base class.
- If none of the other conditions are met, the list will contain
Object
objects.
The generated Java class will only have a getter method for the member variable. The getter method returns a reference to the live list. Any modifications made to the returned list will effect the actual object.
The Java class is decorated with the
@XmlType
annotation. The annotation's name property is set to the value of the name
attribute from the parent element of the XML Schema definition. The annotation's propOrder property contains the single member variable representing the elements in the sequence.
The member variable representing the elements in the choice structure are decorated with the
@XmlElements
annotation. The @XmlElements
annotation contains a comma separated list of @XmlElement
annotations. The list has one @XmlElement
annotation for each member element defined in the XML Schema definition of the type. The @XmlElement
annotations in the list have their name property set to the value of the XML Schema element
element's name
attribute and their type property set to the Java class resulting from the mapping of the XML Schema element
element's type.
Example 35.19, “Java Representation of Choice Structure with an Occurrence Constraint” shows the Java mapping for the XML Schema choice structure defined in Example 35.18, “Choice Occurrence Constraints”.
Example 35.19. Java Representation of Choice Structure with an Occurrence Constraint
@XmlType(name = "ClubEvent", propOrder = { "memberNameOrGuestName" }) public class ClubEvent { @XmlElementRefs({ @XmlElementRef(name = "GuestName", type = JAXBElement.class), @XmlElementRef(name = "MemberName", type = JAXBElement.class) }) protected List<JAXBElement<String>> memberNameOrGuestName; public List<JAXBElement<String>> getMemberNameOrGuestName() { if (memberNameOrGuestName == null) { memberNameOrGuestName = new ArrayList<JAXBElement<String>>(); } return this.memberNameOrGuestName; } }
minOccurs set to 0
If only the
minOccurs
element is specified and its value is 0
, the code generators generate the Java class as if the minOccurs
attribute were not set.
35.5.4. Occurrence Constraints on Elements
Overview
You can specify how many times a specific element in a complex type appears using the
element
element's minOccurs
attribute and maxOccurs
attribute. The default value for both attributes is 1
.
minOccurs set to 0
When you set one of the complex type's member element's
minOccurs
attribute to 0
, the @XmlElement
annotation decorating the corresponding Java member variable is changed. Instead of having its required property set to true
, the @XmlElement
annotation's required property is set to false
.
minOccurs set to a value greater than 1
In XML Schema you can specify that an element must occur more than once in an instance of the type by setting the
element
element's minOccurs
attribute to a value greater than one. However, the generated Java class will not support the XML Schema constraint. Apache CXF generates the supporting Java member variable as if the minOccurs
attribute were not set.
Elements with maxOccurs set
When you want a member element to appear multiple times in an instance of a complex type, you set the element's
maxOccurs
attribute to a value greater than 1. You can set the maxOccurs
attribute's value to unbounded
to specify that the member element can appear an unlimited number of times.
The code generators map a member element with the
maxOccurs
attribute set to a value greater than 1 to a Java member variable that is a List<T>
object. The base class of the list is determined by mapping the element's type to Java. For XML Schema primitive types, the wrapper classes are used as described in the section called “Wrapper classes”. For example, if the member element is of type xsd:int the generated member variable is a List<Integer>
object.
35.5.5. Occurrence Constraints on Sequences
Overview
By default, the contents of a
sequence
element can only appear once in an instance of a complex type. You can change the number of times the sequence of elements defined by a sequence
element is allowed to appear using its minOccurs
attribute and its maxOccurs
attribute. Using these attributes you can specify that the sequence type can occur zero to an unlimited number of times in an instance of a complex type.
Using XML Schema
The
minOccurs
attribute specifies the minimum number of times the sequence must occur in an instance of the defined complex type. Its value can be any positive integer. Setting the minOccurs
attribute to 0
specifies that the sequence does not need to appear inside an instance of the complex type.
The
maxOccurs
attribute specifies the upper limit for how many times the sequence can occur in an instance of the defined complex type. Its value can be any non-zero, positive integer or unbounded
. Setting the maxOccurs
attribute to unbounded
specifies that the sequence can appear an infinite number of times.
Example 35.20, “Sequence with Occurrence Constraints” shows the definition of a sequence type, CultureInfo, with sequence occurrence constraints. The sequence can be repeated 0 to 2 times.
Example 35.20. Sequence with Occurrence Constraints
<complexType name="CultureInfo"> <sequence minOccurs="0" maxOccurs="2"> <element name="Name" type="string"/> <element name="Lcid" type="int"/> </sequence> </complexType>
Mapping to Java
Unlike single instance sequences, XML Schema sequences that can occur multiple times are mapped to a Java class with a single member variable. This single member variable is a
List<T>
object that holds all of the data for the multiple occurrences of the sequence. For example, if the sequence defined in Example 35.20, “Sequence with Occurrence Constraints” occurred two times, then the list would have four items.
The name of the Java class' member variable is derived by concatenating the names of the member elements. The element names are separated by
And
and the first letter of the variable name is converted to lower case. For example, the member variable generated from Example 35.20, “Sequence with Occurrence Constraints” is named nameAndLcid
.
The type of object stored in the list depends on the relationship between the types of the member elements. For example:
- If the member elements are of the same type the generated list will contain
JAXBElement<T>
objects. The base type of theJAXBElement<T>
objects is determined by the normal mapping of the member elements' type. - If the member elements are of different types and their Java representations implement a common interface, the list will contains objects of the common interface.
- If the member elements are of different types and their Java representations extend a common base class, the list will contain objects of the common base class.
- If none of the other conditions are met, the list will contain
Object
objects.
The generated Java class only has a getter method for the member variable. The getter method returns a reference to the live list. Any modifications made to the returned list effects the actual object.
The Java class is decorated with the
@XmlType
annotation. The annotation's name property is set to the value of the name
attribute from the parent element of the XML Schema definition. The annotation's propOrder property contains the single member variable representing the elements in the sequence.
The member variable representing the elements in the sequence are decorated with the
@XmlElements
annotation. The @XmlElements
annotation contains a comma separated list of @XmlElement
annotations. The list has one @XmlElement
annotation for each member element defined in the XML Schema definition of the type. The @XmlElement
annotations in the list have their name property set to the value of the XML Schema element
element's name
attribute and their type property set to the Java class resulting from the mapping of the XML Schema element
element's type.
Example 35.21, “Java Representation of Sequence with an Occurrence Constraint” shows the Java mapping for the XML Schema sequence defined in Example 35.20, “Sequence with Occurrence Constraints”.
Example 35.21. Java Representation of Sequence with an Occurrence Constraint
@XmlType(name = "CultureInfo", propOrder = { "nameAndLcid" }) public class CultureInfo { @XmlElements({ @XmlElement(name = "Name", type = String.class), @XmlElement(name = "Lcid", type = Integer.class) }) protected List<Serializable> nameAndLcid; public List<Serializable> getNameAndLcid() { if (nameAndLcid == null) { nameAndLcid = new ArrayList<Serializable>(); } return this.nameAndLcid; } }
minOccurs set to 0
If only the
minOccurs
element is specified and its value is 0
, the code generators generate the Java class as if the minOccurs
attribute is not set.