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

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:

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&connectionFactory=jms/qcf&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.