WSDL - Complex Data Types

Example 6-6, shown later in this section, is a sample WSDL file that illustrates the use of arrays. This is the Price List Service we created in Chapter 5. The service has one public method, called getPriceList, which expects an array of string SKU values and returns an array of double price values.

The WSDL file now includes a types element. Inside this element, we have defined two new complex types. Very broadly, the XML Schema defines simple types and complex types. Simple types cannot have element children or attributes, whereas complex types can have element children and attributes. We have declared complex types in our WSDL file, because an array may have multiple elements, one for each value in the array.

The XML Schema requires that any new type you create be based on some existing data type. This existing base type is specified via the base attribute. You can then choose to modify this base type using one of two main methods: extension or restriction. Extension simply means that your new data type will have all the properties of the base type plus some extra functionality. Restriction means that your new data type will have all the properties of the base data type, but may have additional restrictions placed on the data.

In Example 6-6, we'll create two new complex types via restriction. For example:

<complexType name="ArrayOfString">
   <complexContent>
      <restriction base="soapenc:Array">
         <attribute ref="soapenc:arrayType" 
            wsdl:arrayType="string[]"/>
      </restriction>
   </complexContent>
</complexType>

Example 6-6: PriceListService.wsdl

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="PriceListService"
   targetNamespace="http://www.ecerami.com/wsdl/PriceListService.wsdl"
   xmlns="http://schemas.xmlsoap.org/wsdl/"
   xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
   xmlns:tns="http://www.ecerami.com/wsdl/PriceListService.wsdl"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:xsd1="http://www.ecerami.com/schema">
 
   <types>
      <schema xmlns="http://www.w3.org/2001/XMLSchema"
         targetNamespace="http://www.ecerami.com/schema"
         xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
         xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
 
         <complexType name="ArrayOfString">
            <complexContent>
               <restriction base="soapenc:Array">
                  <attribute ref="soapenc:arrayType" 
                  wsdl:arrayType="string[]"/>
               </restriction>
            </complexContent>
         </complexType>
         <complexType name="ArrayOfDouble">
            <complexContent>
               <restriction base="soapenc:Array">
                  <attribute ref="soapenc:arrayType"
                  wsdl:arrayType="double[]"/>
               </restriction>
            </complexContent>
         </complexType>
      </schema>
   </types>
 
   <message name="PriceListRequest">
      <part name="sku_list" type="xsd1:ArrayOfString"/>
   </message>
 
   <message name="PriceListResponse">
      <part name="price_list" type="xsd1:ArrayOfDouble"/>
   </message>
 
   <portType name="PriceList_PortType">
      <operation name="getPriceList">
         <input message="tns:PriceListRequest"/>
         <output message="tns:PriceListResponse"/>
      </operation>
   </portType>
 
   <binding name="PriceList_Binding" type="tns:PriceList_PortType">
   <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
      <operation name="getPriceList">
      <soap:operation soapAction="urn:examples:pricelistservice"/>
         <input>
            <soap:body
               encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
               namespace="urn:examples:pricelistservice"
               use="encoded"/>
         </input>
         <output>
            <soap:body
               encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
               namespace="urn:examples:pricelistservice" use="encoded"/>
         </output>
      </operation>
   </binding>
   
   <service name="PriceList_Service">
      <port name="PriceList_Port" binding="tns:PriceList_Binding">
         <soap:address location="http://localhost:8080/soap/servlet/rpcrouter"/>
      </port>
   </service>
</definitions>

The WSDL specification requires that arrays be based on the SOAP 1.1 encoding schema. It also requires that arrays use the name ArrayOfXXX, where XXX is the type of item in the array. The previous example therefore creates a new type called ArrayOfString. This new type is based on the SOAP array data type, but it is restricted to holding only string values. Likewise, the ArrayOfDouble data type creates a new array type containing only double values.

When using the WSDL types element, you need to be particularly aware of XML namespace issues. First, note that the root schema element must include a namespace declaration for the SOAP encoding specification (http://schemas.xmlsoap.org/soap/encoding/). This is required because our new data types extend the array definition specified by SOAP.

Second, the root schema element must specify a targetNamespace attribute. Any newly defined elements, such as our new array data types, will belong to the specified targetNamespace. To reference these data types later in the document, you must refer back to the same targetNamespace. Hence, our definitions element includes a new namespace declaration:

xmlns:xsd1="http://www.ecerami.com/schema">

xsd1 matches the targetNamespace and therefore enables us to reference the new data types later in the document. For example, the message element references the xsd1:ArrayOfString data type:

<message name="PriceListRequest">
   <part name="sku_list" type="xsd1:ArrayOfString"/>
</message> 

Tbe scenario of mutiple types in a structure is as below

<xsd:complexType name="phone">
  <xsd:all>
    <xsd:element name="areaCode" type="xsd:int"/>
    <xsd:element name="exchange" type="xsd:string"/>
    <xsd:element name="number" type="xsd:string"/>
  </xsd:all>
</xsd:complexType> 

TIP:  For an excellent and concise overview of W3C Schema complex types and their derivation via extension and restriction, see Donald Smith's article on "Understanding W3C Schema Complex Types." The article is available online at http://www.xml.com/pub/a/2001/08/22/easyschema.html.