XML Reference Guide

Web services weren't created solely to enable other companies to access your functionality, but that's certainly a big part of it. Trouble is, in order for others to access your service, they would have to know what the messages the service is looking for, what messages it would return, and where the messages should go. Web Services Description Language (WSDL) provides a way to tell them.

WSDL 1.1 is the current specification, hosted by the World Wide Web Consortium. (Version 1.2 is currently at the Working Draft stage.) It uses XML to define the structure of both incoming and outgoing messages. Consider, for example a service to take orders for our candy company. It might be run by a simple Java class that creates orders and add items to them:

public class CandyOrder {

   public int createOrder(String custid){
   	...
   }
   
   public boolean addItemToOrder(int orderid, String itemid, int quantity){
      ...
   }

   public String completeOrder(int orderid){
      ...
   }

}

The createOrder() method creates an order on the system and returns an order number. The addItemToOrder() takes the product id, quantity, and order information and addes the item to the order. It returns a boolean value that indicates whether the item was successfully added. Finally, the completeOrder() method sends the order off to the fulfillment house and returns a message telling the custmer the approximate delivery date.

A WSDL file starts with a basic definition pointing to the service itself, with progressive layers of information that get more and more specific. For example, we can start with a basic file:

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="CandyOrder-binding"
    targetNamespace="http://www.candyorder.com/definitions/CandyOrderRemoteInterface"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:tns="http://www.candyorder.com/definitions/CandyOrderRemoteInterface">

    <service name="CandyOrderService">
        <port binding="tns:CandyOrderBinding" name="CandyOrderPort">
            <soap:address location="http://localhost:8080/sampleweb/servlet/rpcrouter"/>
        </port>
    </service>
</definitions>

In this case, we're defining a single service by the name of CandyOrderService. To access that service using SOAP, we have to send a message to http://localhost:8080/sampleweb/servlet/rpcrouter. The message will depend on the information in the binding, CandyOrderBinding:

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="CandyOrder-binding"
    targetNamespace="http://www.candyorder.com/definitions/CandyOrderRemoteInterface"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:tns="http://www.candyorder.com/definitions/CandyOrderRemoteInterface" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">

    <binding name="CandyOrderBinding" type="tns:CandyOrder">
        <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
        <operation name="completeOrder">
            <soap:operation soapAction="" style="rpc"/>
            <input name="completeOrderRequest">
                <soap:body
                    encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                    namespace="http://tempuri.org/CandyOrder" use="encoded"/>
            </input>
            <output name="completeOrderResponse">
                <soap:body
                    encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                    namespace="http://tempuri.org/CandyOrder" use="encoded"/>
            </output>
        </operation>
        <operation name="createOrder">
            <soap:operation soapAction="" style="rpc"/>
            <input name="createOrderRequest">
                <soap:body
                    encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                    namespace="http://tempuri.org/CandyOrder" use="encoded"/>
            </input>
            <output name="createOrderResponse">
                <soap:body
                    encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                    namespace="http://tempuri.org/CandyOrder" use="encoded"/>
            </output>
        </operation>
        <operation name="addItemToOrder">
            <soap:operation soapAction="" style="rpc"/>
            <input name="addItemToOrderRequest">
                <soap:body
                    encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                    namespace="http://tempuri.org/CandyOrder" use="encoded"/>
            </input>
            <output name="addItemToOrderResponse">
                <soap:body
                    encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                    namespace="http://tempuri.org/CandyOrder" use="encoded"/>
            </output>
        </operation>
    </binding>
    <service name="CandyOrderService">
        <port binding="tns:CandyOrderBinding" name="CandyOrderPort">
            <soap:address location="http://localhost:8080/sampleweb/servlet/rpcrouter"/>
        </port>
    </service>
</definitions>

This binding defines three different operations, each of which corresponds to one of the methods in the original web serivce. For each operation, we can define an optional soapAction and a style. The most commonly-used style is rpc, but some services use the more conversational document style. Each operation defines a n input message and an output message, but doesn't indicate their contents. This section is used more to indicate the flow of messages than their contents. For example, some services might not return a response at all.

To determine the contetn of the differetn messages, you need to know what type of message system you're using. In this case, we're looking for the candyOrder portType:

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="CandyOrder-binding"
    targetNamespace="http://www.candyorder.com/definitions/CandyOrderRemoteInterface"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:tns="http://www.candyorder.com/definitions/CandyOrderRemoteInterface" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">

    <portType name="CandyOrder">
        <operation name="completeOrder" parameterOrder="orderid">
            <input message="tns:completeOrderRequest" name="completeOrderRequest"/>
            <output message="tns:completeOrderResponse" name="completeOrderResponse"/>
        </operation>
        <operation name="createOrder" parameterOrder="custid">
            <input message="tns:createOrderRequest" name="createOrderRequest"/>
            <output message="tns:createOrderResponse" name="createOrderResponse"/>
        </operation>
        <operation name="addItemToOrder" parameterOrder="orderid itemid quantity">
            <input message="tns:addItemToOrderRequest" name="addItemToOrderRequest"/>
            <output message="tns:addItemToOrderResponse" name="addItemToOrderResponse"/>
        </operation>
    </portType>
    <binding name="CandyOrderBinding" type="tns:CandyOrder">
        <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
        <operation name="completeOrder">
            <soap:operation soapAction="" style="rpc"/>
            <input name="completeOrderRequest">
                <soap:body
                    encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                    namespace="http://tempuri.org/CandyOrder" use="encoded"/>
            </input>
            <output name="completeOrderResponse">
                <soap:body
                    encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                    namespace="http://tempuri.org/CandyOrder" use="encoded"/>
            </output>
        </operation>
...
    </binding>
    <service name="CandyOrderService">
        <port binding="tns:CandyOrderBinding" name="CandyOrderPort">
            <soap:address location="http://localhost:8080/sampleweb/servlet/rpcrouter"/>
        </port>
    </service>
</definitions>

This portType defines all three operations, but in this case points to message definitions:

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="CandyOrder-binding"
    targetNamespace="http://www.candyorder.com/definitions/CandyOrderRemoteInterface"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:tns="http://www.candyorder.com/definitions/CandyOrderRemoteInterface" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">

    <message name="completeOrderRequest">
        <part name="orderid" type="xsd:int"/>
    </message>
    <message name="completeOrderResponse">
        <part name="result" type="xsd:string"/>
    </message>
    <message name="createOrderRequest">
        <part name="custid" type="xsd:string"/>
    </message>
    <message name="createOrderResponse">
        <part name="result" type="xsd:int"/>
    </message>
    <message name="addItemToOrderRequest">
        <part name="orderid" type="xsd:int"/>
        <part name="itemid" type="xsd:string"/>
        <part name="quantity" type="xsd:int"/>
    </message>
    <message name="addItemToOrderResponse">
        <part name="result" type="xsd:boolean"/>
    </message>
    <portType name="CandyOrder">
        <operation name="completeOrder" parameterOrder="orderid">
            <input message="tns:completeOrderRequest" name="completeOrderRequest"/>
            <output message="tns:completeOrderResponse" name="completeOrderResponse"/>
        </operation>
        <operation name="createOrder" parameterOrder="custid">
            <input message="tns:createOrderRequest" name="createOrderRequest"/>
            <output message="tns:createOrderResponse" name="createOrderResponse"/>
        </operation>
        <operation name="addItemToOrder" parameterOrder="orderid itemid quantity">
            <input message="tns:addItemToOrderRequest" name="addItemToOrderRequest"/>
            <output message="tns:addItemToOrderResponse" name="addItemToOrderResponse"/>
        </operation>
    </portType>
...
</definitions>

In this case, each message is defined by its parts, each of which is of a specific type. The type for each message is defined in terms of XML Schema types, which actually gives us a great degree of flexibility. In this case we're dealing with only simple values, but it's also possible to create a service that expects an XML structure. For example, we can add a schema section:

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="CandyOrder-binding"
    targetNamespace="http://www.candyorder.com/definitions/CandyOrderRemoteInterface"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:tns="http://www.candyorder.com/definitions/CandyOrderRemoteInterface" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">

    <types> 
        <schema targetNamespace=
               "http://www.candyorder.com/definitions/CandyOrderRemoteInterface"
                       xmlns="http://www.w3.org/2000/10/XMLSchema"> 
            <element name="orderAddition"> 
                <complexType> 
                    <sequence> 
                       <element name="orderid" type="int"/>
                       <element name="itemid" type="string"/>
                       <element name="quantity" type="int"/>
                   </sequence> 
                 </complexType> 
            </element> 
        </schema> 
    </types> 

    <message name="completeOrderRequest">
        <part name="orderid" type="xsd:int"/>
    </message>
    <message name="completeOrderResponse">
        <part name="result" type="xsd:string"/>
    </message>
    <message name="createOrderRequest">
        <part name="custid" type="xsd:string"/>
    </message>
    <message name="createOrderResponse">
        <part name="result" type="xsd:int"/>
    </message>
    <message name="addItemToOrderRequest">
        <part name="body" element="tns:orderAddition"/>
    </message>
    <message name="addItemToOrderResponse">
        <part name="result" type="xsd:boolean"/>
    </message>
...

In this way, you can create services that require (or return) complex messages.

WSDL isn't limited to defining SOAP messages. You can use WSDL to define messages that are sent using SMTP or other protocols, as well. Check out some of the resources for more possibilities.

WSDL 1.2 is currently at the Working Draft level, and makes several changes. For example portTypes have been renamed as intefaces, and ports are now called endpoints. Make sure you know what version your system is expecting.