WSDL Declarations: The Elements





5.2 WSDL Declarations: The definitions, types, and import Elements

This section focuses on the first two child elements of the definitions element (the root element), types and import, which define the data types and other artifacts used by the WSDL document. Before we examine these crucial elements, though, we need to look at the beginning of the document.

1 The XML Declaration

The XML declaration in Listing 5-2 specified a character encoding of UTF-8.

<?xml version="1.0" encoding="UTF-8"?>

A WSDL document must use either UTF-8 or UTF-16 encoding; other encoding systems are not allowed.BP

5.2.2 The definitions Element

The root element of all WSDL documents is the definitions element, which encapsulates the entire document and also provides a WSDL document with its name.

<definitions name="BookQuoteWS"
 targetNamespace="http://www.Monson-Haefel.com/jwsbook/BookQuote"
 xmlns:mh="http://www.Monson-Haefel.com/jwsbook/BookQuote"
 xmlns:soapbind="http://schemas.xmlsoap.org/wsdl/soap/"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns="http://schemas.xmlsoap.org/wsdl/">

The definitions element usually contains several XML namespace declarations, which is normal for a root element. Among these declarations is one for the namespace of the WSDL 1.1 XML schema "http://schemas.xmlsoap.org/wsdl/". Declaring the WSDL namespace as the default namespace avoids having to qualify every WSDL element explicitly, with a prefix.

The first attribute you see in the definitions element is name, which is used to name the entire WSDL document. In practice the WSDL name is not all that important. Nothing refers to it, and it's optional.

The definitions element also declares a targetNamespace attribute, which identifies the namespace of elements defined in the WSDL document—much as it does in XML schema documents.

The message, portType, and binding elements are assigned labels using their name attributes; these labels automatically take on the namespace specified by the targetNamespace attribute. (In this book the URL of the targetNamespace is also assigned a prefix of mh.) Labeled message, portType, and binding elements are commonly called definitions. These definitions assume the namespace specified by targetNamespace.

Other elements in the document refer to the definitions using their label and namespace prefix. A prefixed label is considered a fully qualified name (QName) for a definition. For example, in the following snippet from Listing 5-2, input and output elements refer to the message definitions using their QNames.

<!-- message elements describe the input and output parameters -->
<message name="GetBookPriceRequest">
  <part name="isbn" type="xsd:string" />
</message>
<message name="GetBookPriceResponse">
  <part name="price" type="xsd:float" />
</message>

<!-- portType element describes the abstract interface of a Web service -->
<portType name="BookQuote">
  <operation name="getBookPrice">
    <input name="isbn" message="mh:GetBookPriceRequest"/>
    <output name="price" message="mh:GetBookPriceResponse"/>
  </operation>
</portType>

5.2.3 The types Element

WSDL adopts, as its basic type system, the W3C XML schema built-in types. The types element serves as a container for defining any data types that are not described by the XML schema built-in types: complex types and custom simple types. The data types and elements defined in the types element are used by message definitions when declaring the parts (payloads) of messages.

The types element is not used in Listing 5-2, because it's unnecessary—the message definitions, GetBookPriceRequest and GetBookPriceResponse, refer to simple built-in types.

If we wanted to, we could define a custom simple type for ISBN number and use that in the GetBookPriceRequest message instead of the built-in string type, as in Listing 5-3.

Listing 5-3 Using XML Schema Types Defined in the WSDL types Element
<?xml version="1.0" encoding="UTF-8"?>
<definitions name="BookQuoteWS"
 targetNamespace="http://www.Monson-Haefel.com/jwsbook/BookQuote"
 xmlns:mh="http://www.Monson-Haefel.com/jwsbook/BookQuote"
 xmlns:soapbind="http://schemas.xmlsoap.org/wsdl/soap/"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns="http://schemas.xmlsoap.org/wsdl/">

  <types>

    <xsd:schema
     targetNamespace="http://www.Monson-Haefel.com/jwsbook/BookQuote">
      <!-- The ISBN simple type -->
      <xsd:simpleType name="ISBN">
        <xsd:restriction base="xsd:string">
          <xsd:pattern value="[0-9]{9}[0-9Xx]" />
        </xsd:restriction>
      </xsd:simpleType>

    </xsd:schema>

  </types>

  <!-- message elements describe the input and output parameters -->
  <message name="GetBookPriceRequest">
    <part name="isbn" type="mh:ISBN" />
  </message>
  <message name="GetBookPriceResponse">
    <part name="price" type="xsd:float" />
  </message>
  ...
</definitions>

In Listing 5-3 a complete W3C XML schema document is nested directly in the types element. The custom simple type, labeled ISBN, is defined and assigned to the mh namespace by the XML schema targetNamespace attribute. The mh:ISBN type is then used to define the isbn part of the GetBookPriceRequest message definition.

The targetNamespace attribute of the XML schema must be a valid non-null value, otherwise the types and element will not belong to a valid namespace. In addition, the XML schema defined in the types element must belong to a namespace specified by the WSDL document (usually in the definitions element) or to a namespace of an imported WSDL document.BP In other words, the WSDL document must be aware of any and all namespaces used in the document. The mechanism for importing WSDL documents is discussed in the next section.

SOAP and WSDL both define attributes and encoding types you can use to define array data types. Such array types and attributes have created a lot of confusion and interoperability problems, however, so the BP strictly prohibits their use. In a nutshell, you are not allowed to use the Array type, or the arrayType attribute defined for SOAP 1.1 Encoding (SOAP 1.1 Note, Section 5), or the WSDL arrayType attribute defined by WSDL. In addition you should not label array types as "ArrayOfXXX" as suggested by the WSDL 1.1 Note.BP These requirements are not a handicap at all, because XML schema provides a much simpler way to define arrays. All you need to do is define a complex type with a maxOccurs value greater than 0 (for example, "10", "32000", or "unbounded") and you have yourself a basic array. The following snippet defines an array-like type in this way.

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="BookQuoteWS"
 targetNamespace="http://www.Monson-Haefel.com/jwsbook/BookQuote"
 xmlns:mh="http://www.Monson-Haefel.com/jwsbook/BookQuote"
 xmlns:soapbind="http://schemas.xmlsoap.org/wsdl/soap/"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns="http://schemas.xmlsoap.org/wsdl/">

  <types>

    <xsd:schema
     targetNamespace="http://www.Monson-Haefel.com/jwsbook/BookQuote">
      <!--A simple array-like type -->
      <xsd:complexType name="IntArray">
        <xsd:sequence>
           <xsd:element name="arg" type="xsd:int" maxOccurs="unbounded"/>
        </xsd:sequence>
      </xsd:complexType>

    </xsd:schema>
  </types>

5.2.4 The import Element

The import element makes available in the present WSDL document the definitions from a specified namespace in another WSDL document. This feature can be useful if you want to modularize WSDL documents—for example, to separate the abstract definitions (the types, message, and portType elements) from the concrete definitions (the binding, service, and port elements). Another reason to use import is to consolidate into one WSDL document several definitions you want to maintain separately. For example, your organization may want to maintain WSDL documents for shipping and order processing separately, but present a complete definition of all Web services in a public directory accessible by business partners. The following snippet illustrates.

<definitions name="AllMhWebServices"
 xmlns="http://schemas.xmlsoap.org/wsdl/">

    <import namespace="http://www.Monson-Haefel.com/jwsbook/BookQuote"
     location="http://www.Monson-Haefel.com/jwsbook/BookPrice.wsdl"/>
    <import namespace="http://www.Monson-Haefel.com/jwsbook/po"
     location="http://www.Monson-Haefel.com/jwsbook/wsdl/PurchaseOrder.wsdl"/>
    <import namespace="http://www.Monson-Haefel.com/jwsbook/Shipping"
     location="http://www.Monson-Haefel.com/jwsbook/wsdl/Shipping.wsdl"/>

</definitions >

The WSDL import element must declare two attributes: namespace and location. The value of the namespace attribute must match the targetNamespace declared by the WSDL document being imported. The location attribute must point to an actual WSDL document; it cannot be empty or null. That said, the location is considered a hint. If the application reading the WSDL document has cached or stored copies of the imported WSDL document locally, it may use those instead.BP

Use of the import element is convenient, but it can also create versioning headaches. If WSDL documents are maintained separately, the risk of an imported document being changed without regard to the WSDL documents that import it is pretty high. Take care to ensure that imported WSDL documents are not changed without considering versioning.

You can use import and types together, but you should list the import elements before the types element in a WSDL document.

There has been a lot of confusion about the purpose of the WSDL import element. Some believed it could be used to import either WSDL documents or XML schema documents, while others believed it was only for importing WSDL documents. Varying interpretations have created interoperability problems, so the Basic Profile specifies that a WSDL import element may refer only to WSDL documents. If you need to import an XML schema element, you should do so in the XML schema definition contained in the WSDL types element, using the standard XML schema import statement as described in Section 3.2.5. It's important to note that you cannot use the XML schema import statement to import an XML schema directly from the types element of some other WSDL document.BP


     Python   SQL   Java   php   Perl 
     game development   web development   internet   *nix   graphics   hardware 
     telecommunications   C++ 
     Flash   Active Directory   Windows