WSDL

We introduce the WSDL. This talk is based on:

• James Snell, Doug Tidwell, and Pavel Kulchenko. Programming Web Services with SOAP [1]. 2002. Chapter 5
• Erik Christensen, Francisco Curbera, Greg Meredith, and Sanjiva Weerawarana Web Services Description Language (WSDL) 1.1 [2]. 2001

• SOAP does not specify which encoding to use.
• Each SOAP client must have compile-time knowledge of the protocol the server implements.
• SOAP does not declare an equivalent to IDL.
• The Web Services Description Language (WSDL) is the de facto standard specification which handles this functionality.
• WSDL can be used to describe what a service does, how it does it, and how clients can use it.

1. WSDL provides a structured approach to defining web service interfaces.
2. WSDL can be used by clients to reduce the amount of code needed to access a service.
3. Changes can be made to an existing WSDL description which the clients can understand, at runtime. This allows for some dynamic upgrades.

• For example, Microsoft's .NET platform will automatically generate a WSDL description for any deployed assembly. To get it just add ?WSDL to the URL of a running service created with VS .NET and deployed on IIS.
• Axis has the java2wsdl tool.

• A WSDL document defines services as a collection of network endpoints or ports, where the port types are abstract collection of operations, and the concrete protocol and data format specifications for a particular port type constitutes a reusable binding.
• Types: a container for data type definitions using some type system such as XSD.
• Message: an abstract, typed definition of the data being communicated.
• Operation: an abstract description of an action supported by the service.
• Port Type: an abstract set of operations supported by one or more endpoints.
• Binding: a concrete protocol and data format specification for a particular port type.
• Port: a single endpoint defined as a combination of a binding and a network address.
• Service: a collection of related endpoints.

Data Types <wsdl:types/>

Messages <wsdl:message/>

Interfaces <wsdl:portType/>

Services <wsdl:binding/> <wsdl:service/>

• Its a set of definitions.

<wsdl:definitions name="nmtoken"? targetNamespace="uri">

  <import namespace="uri" location="uri"/>*
  <wsdl:documentation .... /> ?

  <wsdl:types> ?
    <wsdl:documentation .... />?
    <xsd:schema .... />*
    <!-- extensibility element --> *
  </wsdl:types>

  <wsdl:message name="nmtoken"> *
    <wsdl:documentation .... />?
    <part name="nmtoken" element="qname"? type="qname"?/> *
  </wsdl:message>

 <wsdl:portType name="nmtoken">*
    <wsdl:documentation .... />?
    <wsdl:operation name="nmtoken">*
      <wsdl:documentation .... /> ?
      <wsdl:input name="nmtoken"? message="qname">?
        <wsdl:documentation .... /> ?
      </wsdl:input>
      <wsdl:output name="nmtoken"? message="qname">?
         <wsdl:documentation .... /> ?
      </wsdl:output>
      <wsdl:fault name="nmtoken" message="qname"> *
         <wsdl:documentation .... /> ?
       </wssdl:fault>
    </wsdl:operation>
  </wsdl:portType>

  <wsdl:binding name="nmtoken" type="qname">*
    <wsdl:documentation .... />?
      <!-- extensibility element --> *
    <wsdl:operation name="nmtoken">*
      <wsdl:documentation .... /> ?
      <!-- extensibility element --> *
      <wsdl:input> ?
        <wsdl:documentation .... /> ?
        <!-- extensibility element -->
      </wsdl:input>
      <wsdl:output> ?
        <wsdl:documentation .... /> ?
        <!-- extensibility element --> *
      </wsdl:output>
      <wsdl:fault name="nmtoken"> *
        <wsdl:documentation .... /> ?
        <!-- extensibility element --> *
      </wsdl:fault>
    </wsdl:operation>
 </wsdl:binding>

 <wsdl:service name="nmtoken"> *
   <wsdl:documentation .... />?
   <wsdl:port name="nmtoken" binding="qname"> *
     <wsdl:documentation .... /> ?
     <!-- extensibility element -->
   </wsdl:port>
   <!-- extensibility element -->
 </wsdl:service>

<!-- extensibility element --> *

</wsdl:definitions>

• The types element holds data definitions relevant to the messages.
• WSDL prefers the use of XML Schema Data (XSD) types as the canonical type system.
• However, WSDL does allow for any other type system to be added.

• Messages consist of one or more logical parts
• Each part is associated with a type from some type system.
• Parts are a flexible mechanism for describing the logical abstract content of a message.
• In RPC a part may represent a parameter in the message.
• The following message consists of a purchase order and an invoice.

<definitions .... >
  <types>
    <schema .... >
      <element name="PO" type="tns:POType"/>
      <complexType name="POType">
        <all>
          <element name="id" type="string/>
          <element name="name" type="string"/>
          <element name="items">
            <complexType>
              <all>
                <element name="item" type="tns:Item" minOccurs="0" maxOccurs="unbounded"/>
              </all>
            </complexType>
          </element>
        </all>
      </complexType>

      <complexType name="Item">
        <all>
          <element name="quantity" type="int"/>
          <element name="product" type="string"/>
        </all>
      </complexType>
      <element name="Invoice" type="tns:InvoiceType"/>
      <complexType name="InvoiceType">
        <all>
          <element name="id" type="string"/>
        </all>
      </complexType>
    </schema>
  </types>

  <message name="PO">
    <part name="po" element="tns:PO"/>
    <part name="invoice" element="tns:Invoice"/>
  </message>
</definitions>

• A portType is a named set of abstract operations and the abstract messages involved.
• They are equivalent to interfaces.
• The name attribute provides a unique name among all port types defined within in the enclosing WSDL document.
• An operation is named via the name attribute.
• WSDL has four transmission primitives that an endpoint can support:
  • One-way. The endpoint receives a message.
  • Request-response. The endpoint receives a message, and sends a correlated message.
  • Solicit-response. The endpoint sends a message, and receives a correlated message.
  • Notification. The endpoint sends a message.

<wsdl:definitions .... > 
  <wsdl:portType .... > *
    <wsdl:operation name="nmtoken">
      <wsdl:input name="nmtoken"? message="qname"/>
    </wsdl:operation>
  </wsdl:portType >
</wsdl:definitions>

• The input element specifies the abstract message format for the one-way operation.

<wsdl:definitions .... >
  <wsdl:portType .... > *
    <wsdl:operation name="nmtoken" parameterOrder="nmtokens">
      <wsdl:input name="nmtoken"? message="qname"/>
      <wsdl:output name="nmtoken"? message="qname"/>
      <wsdl:fault name="nmtoken" message="qname"/>*
    </wsdl:operation>
  </wsdl:portType >
</wsdl:definitions>

• The input and output elements specify the abstract message format for the request and response, respectively.
• The optional fault elements specify the abstract message format for any error messages that may be output as the result of the operation.

<wsdl:definitions .... >
  <wsdl:portType .... > *
    <wsdl:operation name="nmtoken" parameterOrder="nmtokens">
      <wsdl:output name="nmtoken"? message="qname"/>
      <wsdl:input name="nmtoken"? message="qname"/>
      <wsdl:fault name="nmtoken" message="qname"/>*
    </wsdl:operation>
  </wsdl:portType >
</wsdl:definitions>

• The input and output elements specify the abstract message format for the request and response, respectively.
• The optional fault elements specify the abstract message format for any error messages that may be output as the result of the operation.

<wsdl:definitions .... >
  <wsdl:portType .... > *
    <wsdl:operation name="nmtoken">
      <wsdl:output name="nmtoken"? message="qname"/>
    </wsdl:operation>
  </wsdl:portType >
</wsdl:definitions>

• The output element specifies the abstract message format for the notification operation.

• A binding defines message format and protocol details for operations and messages defined by a particular portType.
• The interfaces are bound to specific network and transport protocols. It is akin to implementing an interface.
• The name attribute provides a unique name among all bindings defined within in the enclosing WSDL document.
• A binding references the portType that it binds using the type attribute.
• A binding must specify exactly one protocol

<binding name="StockQuoteSoap" type="tns:StockQuotePortType">
  <soap:binding style="document" transport="http://example.com/smtp"/>
  <operation name="SubscribeToQuotes">
    <input message="tns:SubscribeToQuotes">
      <soap:body parts="body" use="literal"/>
      <soap:header message="tns:SubscribeToQuotes" part="subscribeheader" use="literal"/>
    </input>
  </operation>
</binding>

• A port defines an individual endpoint by specifying a single address for a binding.
• It is the network location where the web service is implemented.
• The name attribute provides a unique name among all bindings defined within in the enclosing WSDL document.
• The binding attribute (of type QName) refers to the binding using the linking rules defined by WSDL.
• A port must not specify more than one address.
• A port must not specify any binding information other than address information.

<wsdl:service name="HelloService">
  <wsdl:port name="HelloPort"
    binding="tns:HelloWorldBinding"><!--defined by a previous binding-->
    <soap:address location="http://localhost:8080"/>
  </wsdl:port>
</wsdl:service>

• A service can also define multiple ports, each of which may implement a different binding at a different network location.

<?xml version="1.0"?>
<definitions name="StockQuote"
             targetNamespace="http://example.com/stockquote.wsdl"
             xmlns:tns="http://example.com/stockquote.wsdl"
  xmlns:xsd="http://www.w3.org/2000/10/XMLSchema"
  xmlns:xsda="http://example.com/stockquote/schema"
  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
  xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns="http://schemas.xmlsoap.org/wsdl/">

  <types>
    <schema targetNamespace="http://example.com/stockquote/schema"
            xmlns="http://www.w3.org/2000/10/XMLSchema">
      <complexType name="TimePeriod">
        <all>
          <element name="startTime" type="xsd:timeInstant"/>
          <element name="endTime" type="xsd:timeInstant"/>
        </all>
      </complexType>
      <complexType name="ArrayOfFloat">
        <complexContent>
          <restriction base="soapenc:Array">
            <attribute ref="soapenc:arrayType" wsdl:arrayType="xsd:float[]"/>
          </restriction>
        </complexContent>
      </complexType>
    </schema>
  </types>

  <message name="GetTradePricesInput">
    <part name="tickerSymbol" element="xsd:string"/>
    <part name="timePeriod" element="xsda:TimePeriod"/>
  </message>

  <message name="GetTradePricesOutput">
    <part name="result" type="xsda:ArrayOfFloat"/>
    <part name="frequency" type="xsd:float"/>
  </message>

  <portType name="StockQuotePortType">
    <operation name="GetLastTradePrice" parameterOrder="tickerSymbol timePeriod frequency">
      <input message="tns:GetTradePricesInput"/>
      <output message="tns:GetTradePricesOutput"/>
    </operation>
  </portType>

  <binding name="StockQuoteSoapBinding" type="tns:StockQuotePortType">
    <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
      <operation name="GetTradePrices">
        <soap:operation soapAction="http://example.com/GetTradePrices"/>
          <input>
            <soap:body use="encoded" namespace="http://example.com/stockquote"
              encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
          </input>
          <output>
            <soap:body use="encoded" namespace="http://example.com/stockquote"
              encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
          </output>
      </operation>
  </binding>

  <service name="StockQuoteService">
    <documentation>My first service</documentation>
    <port name="StockQuotePort" binding="tns:StockQuoteBinding">
      <soap:address location="http://example.com/stockquote"/>
    </port>
  </service>
</definitions>

• This example describes that a GetTradePrices SOAP 1.1 request may be sent to a StockQuote service via the SOAP 1.1 HTTP binding.
• The request takes a stock quote symbol string, an application defined TimePeriod structure containing a start and end time and returns an array of stock prices recorded by the service within that period of time, as well as the frequency at which they were recorded as the SOAP response.
• The RPC signature that corresponds to this service has in parameters tickerSymbol and timePeriod followed by the output parameter frequency, and returns an array of floats.

<?xml version="1.0"?>

<!-- WSDL description of the Google Web APIs.
     The Google Web APIs are in beta release. All interfaces are subject to
     change as we refine and extend our APIs. Please see the terms of use
     for more information. -->

<definitions name="urn:GoogleSearch"
             targetNamespace="urn:GoogleSearch"
             xmlns:typens="urn:GoogleSearch"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema"
             xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
             xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
             xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
             xmlns="http://schemas.xmlsoap.org/wsdl/">

  <!-- Types for search - result elements, directory categories -->

  <types>
    <xsd:schema xmlns="http://www.w3.org/2001/XMLSchema" 
                targetNamespace="urn:GoogleSearch">
            
      <xsd:complexType name="GoogleSearchResult">
        <xsd:all>
          <xsd:element name="documentFiltering"           type="xsd:boolean"/>
          <xsd:element name="searchComments"              type="xsd:string"/>
          <xsd:element name="estimatedTotalResultsCount"  type="xsd:int"/>
          <xsd:element name="estimateIsExact"             type="xsd:boolean"/>
          <xsd:element name="resultElements"              type="typens:ResultElementArray"/>
          <xsd:element name="searchQuery"                 type="xsd:string"/>
          <xsd:element name="startIndex"                  type="xsd:int"/>
          <xsd:element name="endIndex"                    type="xsd:int"/>
          <xsd:element name="searchTips"                  type="xsd:string"/>
          <xsd:element name="directoryCategories"         type="typens:DirectoryCategoryArray"/>
          <xsd:element name="searchTime"                  type="xsd:double"/>
        </xsd:all>
      </xsd:complexType>

      <xsd:complexType name="ResultElement">
        <xsd:all>
          <xsd:element name="summary" type="xsd:string"/>
          <xsd:element name="URL" type="xsd:string"/>
          <xsd:element name="snippet" type="xsd:string"/>
          <xsd:element name="title" type="xsd:string"/>
          <xsd:element name="cachedSize" type="xsd:string"/>
          <xsd:element name="relatedInformationPresent" type="xsd:boolean"/>
          <xsd:element name="hostName" type="xsd:string"/>
          <xsd:element name="directoryCategory" type="typens:DirectoryCategory"/>
          <xsd:element name="directoryTitle" type="xsd:string"/>
        </xsd:all>
      </xsd:complexType>
  
      <xsd:complexType name="ResultElementArray">
        <xsd:complexContent>
          <xsd:restriction base="soapenc:Array">
             <xsd:attribute ref="soapenc:arrayType" wsdl:arrayType="typens:ResultElement[]"/>
          </xsd:restriction>
        </xsd:complexContent>
      </xsd:complexType>

      <xsd:complexType name="DirectoryCategoryArray">
        <xsd:complexContent>
          <xsd:restriction base="soapenc:Array">
             <xsd:attribute ref="soapenc:arrayType" wsdl:arrayType="typens:DirectoryCategory[]"/>
          </xsd:restriction>
        </xsd:complexContent>
      </xsd:complexType>

      <xsd:complexType name="DirectoryCategory">
        <xsd:all>
          <xsd:element name="fullViewableName" type="xsd:string"/>
          <xsd:element name="specialEncoding" type="xsd:string"/>
        </xsd:all>
      </xsd:complexType>

    </xsd:schema>
  </types> 

  <!-- Messages for Google Web APIs - cached page, search, spelling. -->
             
  <message name="doGetCachedPage">
    <part name="key"            type="xsd:string"/>
    <part name="url"            type="xsd:string"/>
  </message>

  <message name="doGetCachedPageResponse">
    <part name="return"         type="xsd:base64Binary"/>
  </message>

  <message name="doSpellingSuggestion">
    <part name="key"            type="xsd:string"/>
    <part name="phrase"         type="xsd:string"/>
  </message>

  <message name="doSpellingSuggestionResponse">
    <part name="return"         type="xsd:string"/>
  </message>

  <message name="doGoogleSearch">
    <part name="key"            type="xsd:string"/>
    <part name="q"              type="xsd:string"/>
    <part name="start"          type="xsd:int"/>
    <part name="maxResults"     type="xsd:int"/>
    <part name="filter"         type="xsd:boolean"/>
    <part name="restrict"       type="xsd:string"/>
    <part name="safeSearch"     type="xsd:boolean"/>
    <part name="lr"             type="xsd:string"/>
    <part name="ie"             type="xsd:string"/>
    <part name="oe"             type="xsd:string"/>
  </message>

  <message name="doGoogleSearchResponse">
    <part name="return"         type="typens:GoogleSearchResult"/>           
  </message>

  <!-- Port for Google Web APIs, "GoogleSearch" -->

  <portType name="GoogleSearchPort">

    <operation name="doGetCachedPage">
      <input message="typens:doGetCachedPage"/>
      <output message="typens:doGetCachedPageResponse"/>
    </operation>

    <operation name="doSpellingSuggestion">
      <input message="typens:doSpellingSuggestion"/>
      <output message="typens:doSpellingSuggestionResponse"/>
    </operation>

    <operation name="doGoogleSearch">
      <input message="typens:doGoogleSearch"/>
      <output message="typens:doGoogleSearchResponse"/>
    </operation>

  </portType>


  <!-- Binding for Google Web APIs - RPC, SOAP over HTTP -->

  <binding name="GoogleSearchBinding" type="typens:GoogleSearchPort">
    <soap:binding style="rpc"
                  transport="http://schemas.xmlsoap.org/soap/http"/>

    <operation name="doGetCachedPage">
      <soap:operation soapAction="urn:GoogleSearchAction"/>
      <input>
        <soap:body use="encoded"
                   namespace="urn:GoogleSearch"
                   encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
      </input>
      <output>
        <soap:body use="encoded"
                   namespace="urn:GoogleSearch"
                   encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
      </output>
    </operation>

    <operation name="doSpellingSuggestion">
      <soap:operation soapAction="urn:GoogleSearchAction"/>
      <input>
        <soap:body use="encoded"
                   namespace="urn:GoogleSearch"
                   encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
      </input>
      <output>
        <soap:body use="encoded"
                   namespace="urn:GoogleSearch"
                   encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
      </output>
    </operation>

    <operation name="doGoogleSearch">
      <soap:operation soapAction="urn:GoogleSearchAction"/>
      <input>
        <soap:body use="encoded"
                   namespace="urn:GoogleSearch"
                   encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
      </input>
      <output>
        <soap:body use="encoded"
                   namespace="urn:GoogleSearch"
                   encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
      </output>
    </operation>
  </binding>

  <!-- Endpoint for Google Web APIs -->
  <service name="GoogleSearchService">
    <port name="GoogleSearchPort" binding="typens:GoogleSearchBinding">
      <soap:address location="http://api.google.com/search/beta2"/>
    </port>
  </service>

</definitions>