Java Web Services in a Nutshell

The SOAP Protocol

The web service definition cited earlier in this chapter stated that a web service communicates using “XML-based messages conveyed by Internet protocols.” Although it is expected that there will be a choice of web service protocols in the future, at the present time, web services communicate using Simple Object Access Protocol (SOAP). SOAP is an XML-based protocol that can be carried over any transport mechanism capable of delivering a byte stream. In practice, SOAP messages are usually exchanged between clients and services that are resident in web containers and are typically encapsulated inside an HTTP request or response message. However, nothing in the SOAP 1.1 specification (which can be obtained from the W3C web site at http://www.w3c.org/TR/SOAP^[3]) prevents the use of other transport mechanisms, such as FTP, SMTP or even JMS; in fact, both Apache SOAP and its successor, Axis, support the use of SMTP as the carrier for SOAP messages.

A basic SOAP message consists of an envelope that may contain any number of headers plus a body. These parts are delimited by XML elements called Envelope, Header, and Body, which belong to a namespace defined by the SOAP specification. Although the specification defines rules that implementations must follow when creating the structure of a SOAP message, it says nothing about the application-dependent information that the message may contain, apart from the fact that any content conveyed within the envelope must be valid XML. Example 1-1 shows a typical SOAP message.

Example 1-1. A SOAP message

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" 
              xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
              xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" 
              xmlns:ns0=
                   "urn:jwsnut.chapter6.headerbookservice/types/HeaderBookQuery"
              xmlns:ns1=
                   "urn:jwsnut.chapter6.headerbookservice/wsdl/HeaderBookQuery"
              env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <env:Header>
        <ns1:auth xsi:type="ns0:Authentication">
            <UserName xsi:type="xsd:string">JWSUserName</UserName>
            <Password xsi:type="xsd:string">JWSPassword</Password>
        </ns1:auth>
    </env:Header>
    <env:Body>
        <ns1:getBookAuthor>
            <String_1 xsi:type="xsd:string">Java in a Nutshell</String_1>
            <String_2 xsi:type="xsd:string" xsi:nil="1"/>
        </ns1:getBookAuthor>
    </env:Body>
</env:Envelope>

As you can see, the message consists of an Envelope element that wraps both a Header element and a Body element. This particular Envelope element declares a bewildering number of XML namespaces, the meaning of which will be explained in Chapter 3, as will the rules that govern the way in which the message is constructed. In this case, the message has a single SOAP header that contains a username and a password, and a single element in the body that represents a request to the receiver to return the name of the author of the book Java in a Nutshell. The interpretation of the information in the header and the body is generally determined by the application itself, although in this case the body contains a remote procedure call (RPC) request that is formed according to rules laid down in the SOAP specification and was actually generated by JAX-RPC, which is the subject of the next chapter. In other cases, the body might contain an arbitrary XML document formed according to a schema that both the sender and the receiver have agreed to use. Similarly, although some SOAP headers will be standardized, others are not. In this example, the authentication information is conveyed in a very insecure way using an XML structure defined by the application itself. There is, of course, work in progress to define the standards for web service security that is standardizing the way in which information like this is carried in SOAP messages, but the results of that work are not yet visible in either J2EE 1.4 or the JWSDP.

In many cases, limiting an application to XML is too restrictive. As an example, MyXMLBooks.com might like to include book cover images on its web site. One way to achieve this is to return a URL in the SOAP message and have the client application fetch the image directly using HTTP (i.e., without involving a SOAP message). This approach is not mandatory, however, because there is an extension to the SOAP specification called SOAP with Attachments that allows a SOAP message to have associated MIME attachments that can carry any data with a recognized (or even application-private) representation. Both the SOAP and SOAP with Attachments specifications are covered in detail in Chapter 3, which also contains an example that shows how to use an attachment to return a book cover image to a web service client.

Web Service Profiles

The SOAP specification provides encoding rules for the XML data and attachments that make up an application-level message, but it leaves much in the hands of the application itself. For example, it defines a framework for placing information that might need to be processed alongside the actual message data into message headers. These headers may be directed at either the system containing the web service itself or intermediaries that the message might need to pass through en route to its destination. What it does not do, however, is specify what those headers are or what information they should contain. This flexibility is deliberate because it allows SOAP to be used at one end of the scale as the basis for a private distributed application, where the header and data content need be known only to the implementor of the application, or at the other end as a building block for more open web services, such as that provided by Amazon.com.

In the real world, it is necessary to reduce the level of flexibility available to service implementors in order to make it less likely that incompatible implementations, either of SOAP itself or of the applications it supports, are developed. For this reason, several different web service profiles have been proposed or developed. A profile consists of rules, in addition to those imposed by SOAP, that all participants in that profile agree to abide by to ensure that their implementations can interwork with each other. Three examples of such profiles follow:

The WS-Routing profile

The WS-Routing profile (originally known as SOAP-RP) defines a set of SOAP headers that allow the specification of a route to be followed by a SOAP message as it is being sent from the client application to the server. The specification also allows a reverse path to be constructed as the message is being passed between the intermediary systems that form its output route. Since this profile is concerned only with message routing, it does not specify any standard body content.

The ebXML Transport, Routing, and Packaging profile (ebXML-TRP)

This profile defines a message format for applications engaged in various forms of electronic business. Like WS-Routing, it includes a definition of a set of headers and prescribes their meanings. Unlike WS-Routing, it also includes a set of standard XML elements that can be included in the message body. See Section 4.6 for a discussion of this profile.

The Web Services Interoperaibility (WS-I) profile

WS-Routing and ebXML-TRP are narrow standards that confine themselves to specific aspects of SOAP messaging. Indeed, ebXML-TRP itself applies only to a particular vertical marketplace. By contrast, the WS-I profile, introduced early in 2003, is a broad profile that aims to maximize the potential for interworking across a range of applications by ensuring that the messaging systems on which they are built obey certain specific rules that cover not only SOAP, but also some of the other technologies that you’ll see elsewhere in this book. The WS-I profile creates a greater probability of successful interworking by reducing the number of choices that implementors can make from the wide range allowed by individual specifications to a much smaller number—often just one. Sun Microsystems recently announced that the web services support provided by the J2EE 1.4 platform is WS-I conformant; therefore, developers using J2EE 1.4 do not need to do anything in order to comply with this specification.

---

^[3] Like most web service specifications, SOAP was originally defined by a group of cooperating businesses and has now been taken under the wing of the W3C. The next version of the SOAP specification (Version 1.2) is being produced by the W3C and can be obtained from http://www.w3c.org.