32.4. Lists

Overview

XML Schema supports a mechanism for defining data types that are a list of space separated simple types. An example of an element, primeList, using a list type is shown in Example 32.7, “List Type Example”.

Example 32.7. List Type Example

<primeList>1 3 5 7 9 11 13<\primeList>
XML Schema list types are generally mapped to Java List<T> objects. The only variation to this pattern is when a message part is mapped directly to an instance of an XML Schema list type.

Defining list types in XML Schema

XML Schema list types are simple types and as such are defined using a simpleType element. The most common syntax used to define a list type is shown in Example 32.8, “Syntax for XML Schema List Types”.

Example 32.8. Syntax for XML Schema List Types

<simpleType name="listType">
  <list itemType="atomicType">
    <facet value="value" />
    <facet value="value" />
    ...
  </list>
</simpleType>
The value given for atomicType defines the type of the elements in the list. It can only be one of the built in XML Schema atomic types, like xsd:int or xsd:string, or a user-defined simple type that is not a list.
In addition to defining the type of elements listed in the list type, you can also use facets to further constrain the properties of the list type. Table 32.3, “List Type Facets” shows the facets used by list types.

Table 32.3. List Type Facets

FacetEffect
lengthDefines the number of elements in an instance of the list type.
minLengthDefines the minimum number of elements allowed in an instance of the list type.
maxLengthDefines the maximum number of elements allowed in an instance of the list type.
enumerationDefines the allowable values for elements in an instance of the list type.
patternDefines the lexical form of the elements in an instance of the list type. Patterns are defined using regular expressions.
For example, the definition for the simpleList element shown in Example 32.7, “List Type Example”, is shown in Example 32.9, “Definition of a List Type”.

Example 32.9. Definition of a List Type

<simpleType name="primeListType">
  <list itemType="int"/>
</simpleType>
<element name="primeList" type="primeListType"/>
In addition to the syntax shown in Example 32.8, “Syntax for XML Schema List Types” you can also define a list type using the less common syntax shown in Example 32.10, “Alternate Syntax for List Types”.

Example 32.10. Alternate Syntax for List Types

<simpleType name="listType">
  <list>
    <simpleType>
      <restriction base="atomicType">
        <facet value="value"/>
        <facet value="value"/>
        ...
      </restriction>
    </simpleType>
  </list>
  </simpleType>

Mapping list type elements to Java

When an element is defined a list type, the list type is mapped to a collection property. A collection property is a Java List<T> object. The template class used by the List<T> is the wrapper class mapped from the list's base type. For example, the list type defined in Example 32.9, “Definition of a List Type” is mapped to a List<Integer>.
For more information on wrapper type mapping see the section called “Wrapper classes”.

Mapping list type parameters to Java

When a message part is defined as a list type, or is mapped to an element of a list type, the resulting method parameter is mapped to an array instead of a List<T> object. The base type of the array is the wrapper class of the list type's base class.
For example, the WSDL fragment in Example 32.11, “WSDL with a List Type Message Part” results in the method signature shown in Example 32.12, “Java Method with a List Type Parameter”.

Example 32.11. WSDL with a List Type Message Part

<definitions ...>
  ...
  <types ...>
    <schema ... >
      <simpleType name="primeListType">
        <list itemType="int"/>
      </simpleType>
      <element name="primeList" type="primeListType"/>
    </schemas>
  </types>
  <message name="numRequest">
    <part name="inputData" element="xsd1:primeList" />
  </message>
  <message name="numResponse">;
    <part name="outputData" type="xsd:int">
  ...
  <portType name="numberService">
    <operation name="primeProcessor">
      <input name="numRequest" message="tns:numRequest" />
      <output name="numResponse" message="tns:numResponse" />
    </operation>
    ...
  </portType>
  ...
</definitions>

Example 32.12. Java Method with a List Type Parameter

public interface NumberService {

    @XmlList
    @WebResult(name = "outputData", targetNamespace = "", partName = "outputData")
    @WebMethod
    public int primeProcessor(
        @WebParam(partName = "inputData", name = "primeList", targetNamespace = "...")
        java.lang.Integer[] inputData
    );
}