The XML Schema any
element is used to create a wild card place holder in complex type
definitions. When an XML element is instantiated for an XML Schema any
element, it can be any valid
XML element. The any
element does not place any restrictions on either the content or the name of
the instantiated XML element.
For example, given the complex type defined in Example 13.1 you can instantiate either of the XML elements shown in Example 13.2.
Example 13.1. XML Schema Type Defined with an Any Element
<element name="FlyBoy"> <complexType> <sequence> <any /> <element name="rank" type="xsd:int" /> </sequence> </complexType> </element>
Example 13.2. XML Document with an Any Element
<FlyBoy> <learJet>CL-215</learJet> <rank>2</rank> </element> <FlyBoy> <viper>Mark II</viper> <rank>1</rank> </element>
XML Schema any
elements are mapped to either a Java Object
object or a Java org.w3c.dom.Element
object.
The any
element can be used when defining sequence complex types and choice complex
types. In most cases, the any
element is an empty element. It can, however, take an
annotation
element as a child.
Table 13.1 describes the any
element's
attributes.
Table 13.1. Attributes of the XML Schema Any Element
Attribute | Description |
---|---|
namespace |
Specifies the namespace of the elements that can be used to instantiate the element in an XML document. The valid values are:
|
maxOccurs | Specifies the maximum number of times an instance of the element can appear in the parent element. The default value is 1 . To specify that an instance of the element can appear an unlimited number of times, you can set the attribute's value to unbounded . |
minOccurs | Specifies the minimum number of times an instance of the element can appear in the parent element. The default value is 1 . |
processContents |
Specifies how the element used to instantiate the any element should be validated. Valid values are:
|
Example 13.3 shows a complex type defined with an any
element
Example 13.3. Complex Type Defined with an Any Element
<complexType name="surprisePackage"> <sequence> <any processContents="lax" /> <element name="to" type="xsd:string" /> <element name="from" type="xsd:string" /> </sequence> </complexType>
XML Schema any
elements result in the creation of a Java property named
any
. The property has associated getter and setter methods. The type of the resulting property depends on the
value of the element's processContents
attribute. If the any
element's
processContents
attribute is set to skip
, the element is mapped to a
org.w3c.dom.Element
object. For all other values of the
processContents
attribute an any
element is mapped to a Java
Object
object.
The generated property is decorated with the @XmlAnyElement
annotation. This
annotation has an optional lax property that instructs the runtime what to do when marshaling the data. Its
default value is false
which instructs the runtime to automatically marshal the data into a
org.w3c.dom.Element
object. Setting lax to true
instructs
the runtime to attempt to marshal the data into JAXB types. When the any
element's
processContents
attribute is set to skip
, the
lax property is set to its default value. For all other values of the
processContents
attribute, lax is set to true
.
Example 13.4 shows how the complex type defined in Example 13.3 is mapped to a Java class.
Example 13.4. Java Class with an Any Element
public class SurprisePackage { @XmlAnyElement(lax = true) protected Object any; @XmlElement(required = true) protected String to; @XmlElement(required = true) protected String from; public Object getAny() { return any; } public void setAny(Object value) { this.any = value; } public String getTo() { return to; } public void setTo(String value) { this.to = value; } public String getFrom() { return from; } public void setFrom(String value) { this.from = value; } }
If the Java property for an any
element has its lax set to
false
, or the property is not specified, the runtime makes no attempt to parse the XML data into JAXB objects.
The data is always stored in a DOM Element
object.
If the Java property for an any
element has its lax set to
true
, the runtime attempts to marshal the XML data into the appropriate JAXB objects. The runtime attempts to
identify the proper JAXB classes using the following procedure:
It checks the element tag of the XML element against the list of elements known to the runtime. If it finds a match, the runtime marshals the XML data into the proper JAXB class for the element.
It checks the XML element's
xsi:type
attribute. If it finds a match, the runtime marshals the XML element into the proper JAXB class for that type.If it cannot find a match it marshals the XML data into a DOM
Element
object.
Usually an application's runtime knows about all of the types generated from the schema's included in its contract. This
includes the types defined in the contract's wsdl:types
element, any data types added to the contract
through inclusion, and any types added to the contract through importing other schemas. You can also make the runtime aware of
additional types using the @XmlSeeAlso
annotation which is described in
Adding Classes to the Runtime Marshaller.
If the Java property for an any
element has its lax set to
false
, or the property is not specified, the runtime will only accept DOM Element
objects. Attempting to use any other type of object will result in a marshalling error.
If the Java property for an any
element has its lax set to
true
, the runtime uses its internal map between Java data types and the XML Schema constructs they represent
to determine the XML structure to write to the wire. If the runtime knows the class and can map it to an XML Schema construct, it
writes out the data and inserts an xsi:type
attribute to identify the type of data the element
contains.
If the runtime cannot map the Java object to a known XML Schema construct, it will throw a marshaling exception. You can
add types to the runtime's map using the @XmlSeeAlso
annotation which is described in
Adding Classes to the Runtime Marshaller.