35.5. Occurrence Constraints
35.5.1. Schema Elements Supporting Occurrence Constraints
35.5.2. Occurrence Constraints on the All Element
XML Schema
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
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
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
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.
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
<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
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.
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
.
- 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.
@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.
@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
@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
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
element
element's minOccurs
attribute and maxOccurs
attribute. The default value for both attributes is 1
.
minOccurs set to 0
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
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
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.
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
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
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.
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
<complexType name="CultureInfo"> <sequence minOccurs="0" maxOccurs="2"> <element name="Name" type="string"/> <element name="Lcid" type="int"/> </sequence> </complexType>
Mapping to Java
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.
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
.
- 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.
@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.
@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
@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
minOccurs
element is specified and its value is 0
, the code generators generate the Java class as if the minOccurs
attribute is not set.