Chapter 34. Using Wild Card Types

Abstract

There are instances when a schema author wants to defer binding elements or attributes to a defined type. For these cases, XML Schema provides three mechanisms for specifying wild card place holders. These are all mapped to Java in ways that preserve their XML Schema functionality.

34.1. Using Any Elements

Overview

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 34.1, “XML Schema Type Defined with an Any Element” you can instantiate either of the XML elements shown in Example 34.2, “XML Document with an Any Element”.

Example 34.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 34.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.

Specifying in XML Schema

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 34.1, “Attributes of the XML Schema Any Element” describes the any element's attributes.

Table 34.1. Attributes of the XML Schema Any Element

AttributeDescription
namespace
Specifies the namespace of the elements that can be used to instantiate the element in an XML document. The valid values are:
##any
Specifies that elements from any namespace can be used. This is the default.
##other
Specifies that elements from any namespace other than the parent element's namespace can be used.
##local
Specifies elements without a namespace must be used.
##targetNamespace
Specifies that elements from the parent element's namespace must be used.
A space delimited list of URIs, ##local, and ##targetNamespace
Specifies that elements from any of the listed namespaces can be used.
maxOccursSpecifies 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.
minOccursSpecifies 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:
strict
Specifies that the element must be validated against the proper schema. This is the default value.
lax
Specifies that the element should be validated against the proper schema. If it cannot be validated, no errors are thrown.
skip
Specifies that the element should not be validated.
Example 34.3, “Complex Type Defined with an Any Element” shows a complex type defined with an any element

Example 34.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>

Mapping to Java

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 34.4, “Java Class with an Any Element” shows how the complex type defined in Example 34.3, “Complex Type Defined with an Any Element” is mapped to a Java class.

Example 34.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;
    }

}

Marshalling

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:
  1. 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.
  2. 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.
  3. 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 Section 30.4, “Adding Classes to the Runtime Marshaller”.

Unmarshalling

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 Section 30.4, “Adding Classes to the Runtime Marshaller”.