 |  |  |  |  |
| | | | |
 |  |
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.
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 13.18 shows the definition of a choice type, ClubEvent, with choice occurrence constraints. The choice type overall can be repeated 0 to unbounded times.
Example 13.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>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 13.18 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 13.18 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 the JAXBElement<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 13.19 shows the Java mapping for the XML Schema choice structure defined in Example 13.18.
Example 13.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;
}
}| |  | |
 |
