The Department Directory: A Use Case for Abstract Interfaces in Service References

The Department Directory: A Use Case for Abstract Interfaces in Service 
References
Arthur Ryman
2003-11-04
Introduction
In this application, a company plans to make its organization chart 
available by hosting a directory of departments and making it accessible 
as Web services. The directory contains information about each department, 
such as the department name, number, manager, employees, and other 
departments the report to it. There is a set of operations for querying 
and updating the department information. It is therefore natural to define 
a Web service interface for querying and updating a department. Each 
department will be represented as the endpoint of a Web service. 
Furthermore, our company wants to make the department directory available 
by several transports. Java applications within the firewall will use SOAP 
over JMS. Other users will use SOAP over HTTP. 

The point of this example is that two different transports use the same 
abstract interface. This is an important design goal for WSDL. Interfaces 
should not be coupled to bindings. Any support for service references 
should preserver this design goal.
SOAP Messages
Let's focus exclusively on the department reporting structure since that 
involves Web service references. For simplicity, let's define a single 
operation, getDepartments, which returns the set of departments that 
report to the current department. In this application, the address of each 
department service is defined by a URI. SOAP over HTTP uses the http or 
https scheme, while SOAP over JMS uses the jms scheme. We can therefore 
XML Schema simple type anyURI to represent the endpoint address of each 
department service.

For simplicity, suppose our company is W3C, the top level department is 
D001 and that D002, D003, and D004 report to it. For SOAP over HTTP, we'll 
use endpoint addresses like:
http://www.w3c.org/Department/D001
http://www.w3c.org/Department/D002
http://www.w3c.org/Department/D003
http://www.w3c.org/Department/D004
The SOAP request to getDepartments is:

<SOAP-ENV:Envelope
     xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
     xmlns:q0="http://example.w3c.org/Department">
     <SOAP-ENV:Body>
          <q0:getDepartmentsRequest /> 
      </SOAP-ENV:Body>
</SOAP-ENV:Envelope>


The SOAP response from getDepartments is:

<SOAP-ENV:Envelope
     xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
     xmlns:q0="http://example.w3c.org/Department">
     <SOAP-ENV:Body>
          <q0:getDepartmentsResponse>
            
<q0:Department>http://www.w3c.org/Department/D002</q0:Department>
            
<q0:Department>http://www.w3c.org/Department/D003</q0:Department>
            
<q0:Department>http://www.w3c.org/Department/D004</q0:Department>
        </q0:getDepartmentsResponse> 
      </SOAP-ENV:Body>
</SOAP-ENV:Envelope>


For SOAP over JMS, the message formats will be the same but the endpoints 
with use the jms scheme instead of the http scheme.
WSDL Description
The following listing is a WSDL 1.1 description of the service:

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="Department" 
targetNamespace="http://example.w3c.org/Department" 
    xmlns:tns="http://example.w3c.org/Department" 
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
    xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <wsdl:types>
        <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
elementFormDefault="qualified" 
targetNamespace="http://example.w3c.org/Department">
            <xsd:element name="getDepartmentsResponse">
                <xsd:complexType>
                    <xsd:sequence>
                        <xsd:element name="Department" type="xsd:anyURI" 
minOccurs="0" maxOccurs="unbounded"></xsd:element>
                    </xsd:sequence>
                </xsd:complexType>
            </xsd:element>
            <xsd:element name="getDepartmentsRequest">
                <xsd:complexType></xsd:complexType>
            </xsd:element>

        </xsd:schema>
    </wsdl:types>
    <wsdl:message name="getDepartmentsInput">
        <wsdl:part name="body" 
element="tns:getDepartmentsRequest"></wsdl:part>
    </wsdl:message>
    <wsdl:message name="getDepartmentsOutput">
        <wsdl:part name="body" 
element="tns:getDepartmentsResponse"></wsdl:part>
    </wsdl:message>
    <wsdl:portType name="DepartmentInterface">
        <wsdl:operation name="getDepartments">
            <wsdl:input message="tns:getDepartmentsInput"></wsdl:input>
            <wsdl:output message="tns:getDepartmentsOutput"></wsdl:output>
        </wsdl:operation>
    </wsdl:portType>
    <wsdl:binding name="DepartmentSOAPHTTPBinding" 
type="tns:DepartmentInterface">
        <soap:binding style="document" 
transport="http://schemas.xmlsoap.org/soap/http" />
        <wsdl:operation name="getDepartments">
            <soap:operation 
soapAction="http://example.w3c.org/Department/getDepartments" />
            <wsdl:input>
                <soap:body use="literal" />
            </wsdl:input>
            <wsdl:output>
                <soap:body use="literal" />
            </wsdl:output>
        </wsdl:operation>
    </wsdl:binding>
    <wsdl:binding name="DepartmentSOAPJMSBinding" 
type="tns:DepartmentInterface">
        <soap:binding style="document" 
transport="http://schemas.xmlsoap.org/soap/jms" />
        <wsdl:operation name="getDepartments">
            <soap:operation 
soapAction="http://example.w3c.org/Department/getDepartments" />
            <wsdl:input>
                <soap:body use="literal" />
            </wsdl:input>
            <wsdl:output>
                <soap:body use="literal" />
            </wsdl:output>
        </wsdl:operation>
    </wsdl:binding>
    <wsdl:service name="DepartmentService">
        <wsdl:port name="SOAPHTTPPort" 
binding="tns:DepartmentSOAPHTTPBinding">
            <soap:address location="http://www.w3c.org/Department/D001" />
        </wsdl:port>
        <wsdl:port name="SOAPJMSPort" 
binding="tns:DepartmentSOAPJMSBinding">
            <soap:address 
location="jms:/queue?destination=jms/queue&amp;connectionFactory=jms/qcf&amp;targetService=Department/D001" 
/>
        </wsdl:port>
    </wsdl:service>
</wsdl:definitions>


The service contains two bindings, one for SOAP over HTTP and one for SOAP 
over JMS, each of which uses the same abstract interface, 
DepartmentInterface. To anchor the service, we publish the endpoint of the 
top level department in each of the bindings. If a message is sent using 
SOAP over HTTP then the response contains service references that are 
bound using SOAP over HTTP. Similarly, requests that use SOAP over JMS 
result in responses that contain SOAP over JMS responses. A client 
application can select the most appropriate binding, for a request, and 
the same binding is used in the response.

WSDL 1.1 gives no way to formally describe the interface and binding 
associated with the URIs that appear in the messages. WSDL Requirement R085 states that WSDL 2.0 should provide a way to do so.
Summary
This document describes a realistic use case for service references and 
shows the desirability of defining an abstract interface that can be used 
with multiple bindings. WSDL 2.0 should provide a way to describe the 
interface and binding type associated with service references in a way 
that enables reuses of interfaces with multiple bindings.


Arthur Ryman