Section 15.3. Web Service Descriptions

15.3. Web Service Descriptions

This section explains how the description of the Web services involved in this scenario should be written. To focus on the fundamental aspects of the description, Web Services Description Language (WSDL) 1.1 service definitions are shown but the details of schema and policy definitions are omitted (the latter because the definition of policy assertion dialects is in an early stage). Note also that, for simplicity and readability, XML namespace declarations are omitted in this and in the next section's examples, and we limit the use of namespace prefixes to element names. Thus, the examples are meant to be illustrative rather than executable.

This example has five services: the ordering service and inventory checking at the car manufacturer, and the ordering services at the warehouse systems at the supplier (the one where orders are sent, and one in each of the two production plants). All three warehouse Web services implement the same port type.

The port type of the ordering Web service at the manufacturer provides three operations: retrieving the list of outstanding orders, checking the status of an order, and placing a new order:

 <definitions targetNamespace="..."> <!-- WSDL definitions in this document    --> <!-- referenced using "mfr" prefix        -->   <types>     <xsd:schema>     <!-- XSD definitions for this service  -->     <!-- referenced using "mfx" prefix     -->       <xsd:import namespace=                    "http://www.car- manufacturer.com/xsd/customer"/>     </xsd:schema>         </types>   <message name="customerID">     <part name="customer" element="mfx:custID"/>   </message>   <message name="orderID">     <part name="order" element="mfx:orderID"/>   </message>   <message name="orderInfo">     <part name="order" element="mfx:orderInfo"/>   </message>   <message name="orderList">    <part name="ID" element="mfx:orderList"/>   </message>      <portType name="partOrderPortType">     <operation name="requestOrderList">        <input message="mfr:customerID"/>        <output message="mfr:orderList"/>     </operation>      <operation name="requestOrderStatus">        <input message="mfr:orderID"/>        <output message="mfr:orderInfo"/>    </operation>    <operation name="newOrder">        <input message="mfr:orderInfo"/>         <output message="mfr:orderID"/>        <fault name="notAccepted" message="mfr:orderFault"/>    </operation> </portType>   <binding name="partOrderBinding"           type="mfr:partOrderPortType">   <wsp:PolicyReference URI=          "http://www.car-manufacturer.com/policies/DSig"/>   <soap:binding style="document"    transport="http://schemas.xmlsoap.org/soap/http"/>  </binding> <service name="partOrderService">    <port name="partOderPort" binding="mfr:partOrderBinding">        <soap:address location=          "http://www.car-manufacturer/partOrder-svc"/>    </port> </service> </definitions> 

Note that these three operations use four WSDL message definitions. TwocustomerID and orderIDare used for customer and order identification. The orderInfo message encodes all information necessary to place an order and is used to transmit order information and status, also. A list of orders is encoded as an orderList message, which relies on a schema element definition containing a variable number of orderInfo elements. Note also that the binding that the service provides is a SOAP document/literal-style binding.

The manufacturer offers a second service, this time to its parts supplier. This service offers a single operation for retrieving the list of parts and the inventory levels for each of them. Access to this service requires both the digital signing and encryption of the bodies of the messages that are exchanged. This is expressed in the next block of code by the two policy attachment elements in the port type binding.

<definitions targetNamespace="..."> <!-- WSDL definitions in this document    --> <!-- referenced using "mfr" prefix        -->   <types>     <xsd:schema>      <!-- XSD definitions for this service -->      <!-- referenced using "mfx" prefix    -->       <xsd:import namespace=                  "http://www.car-manufacturer.com/xsd/inventory"/>     </xsd:schema>         </types>   <message name="supplierID">     <part name="suppplier" element="mfx:supplierID"/>   </message>   <message name="inventoryList">     <part name="ID" element="mfx:inventoryList"/>   </message> <portType name="inventoryPortType">    <operation name="requestInventoryList">       <input message="mfr:supplierID"/>       <output message="mfr:inventoryList"/>    </operation> </portType> <binding name="inventoryBinding"             type="mfr:inventoryPortType">     <wsp:PolicyReference URI=          "http://www.car-manufacturer.com/policies/DSig"/>     <wsp:PolicyReference URI=          "http://www.car-manufacturer.com/policies/Encrypt"/>     <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> </binding> <service name="inventoryService">    <port name="partOderPort" binding="mfr:inventoryBinding">        <soap:address location=         "http://www.car-manufacturer/inventory-svc"/>    </port> </service> </definitions> 

Finally, all the internal warehouse systems at the supplier implement the same warehouse order port type. The port type offers a one-way "warehouseOrder" operation, which is shown in the definition that follows for the central warehouse service. For completeness and to support the message examples included in the next section, we also provide XML Schema element definitions for the service.

<definitions targetNamespace="..."> <!-- WSDL definitions in this document    --> <!-- referenced using "spl" prefix        --> <types>    <xsd:schema targetNamespace="...">    <!-- XSD definitions in this document  -->    <!-- referenced using "spx" prefix     -->       <xsd:element="warehouseOrder">          <xsd:complexType>             <xsd:complexContent>                <xsd:sequence>                   <xsd:element name="Date" type="xsd:date"/>                   <xsd:element name="Originator"                                 type="xsd:anyURI"/>                   <xsd:element name="CustomerId"                                 type="xsd:string"/>                   <xsd:element name="ItemNo"                                 type="xsd:unsignedLong"/>                   <xsd:element name="Qty"                                 type="xsd:unsignedLong"/>               </xsd:sequence>             </xsd:complexContent>          <xsd:complexType>       <xsd:element>    </xsd:schema> </types> <message name="warehouseOrder">    <part element="spx:warehouseOrder"/> </message> <portType name="warehouseOrderingPortType">    <operation name="placeOrder">       <input message="spl:warehouseOrder"/>    </operation> </portType> <binding name="reliableWarehouseBinding"           type="spl:warehouseOrderingPortType">    <soap:binding style="document"            transport="http://schemas.xmlsoap.org/soap/http"/>    <wsp:PolicyReference URI=       "http://www.supplier.com/policies/ReliableMsgPolicy"/> </binding> <service name="warehouseOrderService">    <port name="warehouseorderPort"          binding="spl:reliableWarehouseBinding">        <soap:address location=              "http://www.car-manufacturer/inventory-svc"/>    </port> </service> </definitions> 

The receiving warehouse responds to the requesting application that sent the order message with a confirmation or an error message, which is sent back asynchronously. (We do not include here the definition of the port type where these messages are received.) The bindings for all warehouse services have attached policies to indicate that certain QoS protocols must be followed. As shown in the preceding service definition, the initial order is transmitted to the central warehouse service over a reliable connection using WS-Reliable Messaging. The binding attaches a policy that requires the use of the WS-Reliable Messaging protocol when the service is accessed.