Message-based SOAP Services

So far, you have examined Web Services largely from an RPC-oriented perspective. For the first part of today, you will examine how message-based Web Services can be used under J2EE.

Message-Style Versus RPC-Style

To a large degree, there is little difference between the mechanics of message-style and RPC-style Web Services. Essentially, a message-style Web Service uses a single operation with a single parameter. This single parameter is an XML document to be processed. There is no reason why you could not define an RPC-style interface that takes a single parameter that is an XML document. Under the covers, in SOAP-land, these interfaces would look largely the same. However, there are some differences in application style:

• RPC services offer a related group of operations. There may be some implication of retained state between operations on the same interface.

• Message services tend to work on document-centric interactions, such as a workflow in which each service accepts the document, changes or processes part of it, and then passes it on.

There are pros and cons to both RPC-style services and message-style services. The choice between them will largely depend on how your application works. This choice is the same as between RMI interfaces and JMS messages in non-Web Service J2EE. As with RMI and JMS in J2EE applications, you can mix and match RPC-style and message-style Web Services as required. RPC-style Web Services can be used to build applications that require synchronous interaction to deliver functionality directly to users, whereas message-style Web Services are used to create more loosely-coupled applications such as order processing and workflow.

Creating a Client

A messaging client must do two things:

• Create a message to send to the service

• Obtain a connection to the service, or some proxy for it, over which the message can be sent

In terms of a SOAP messaging client, it will send an XML document, possibly with some non-XML attachments. As a developer, if you know the SOAP specifications well, you can use the standard Java HTTP support and XML APIs, such as DOM, to create your own SOAP messages. However, it is far preferable to use a standard API to help you create and populate a SOAP message. A SOAP message has a fixed format, as shown in Figure 21.1, so the API will need to reflect this.

As you can see, the overall message is packaged using MIME to delineate the XML part of the message from the attachments. The XML part of the message is encapsulated in a SOAP envelope. Within the SOAP envelope, there is a SOAP header that contains information relating primarily to the transportation of the message and a SOAP body that holds the principal payload of the message. Both the header and the body consist of XML elements with content, attributes, and namespace information. Your chosen API must allow you to access and populate the contents of a SOAP envelope.

To send the message, you could create a direct connection to the target service. Otherwise, you could pass it to an intermediary that will route the message to its eventual destination. In both cases, you will need an address for the target service.

You will frequently require some form of reply to your message. The way this is sent depends on the style of interaction. If you send directly to the service, the response could be returned from the call. Otherwise, if the response is to arrive later, you will have to supply your own endpoint information to the service for it to use as the return address for the message. You will also need some mechanism to handle this response when it arrives.

Creating a Service

A message-based service has a single entry point to which messages are delivered. This follows the same principle you have seen for JMS servers and Message-Driven beans. Messages will be received by the service and processed according to their purpose. A synchronous service will generate a response or acknowledgement during the processing and then return this to the sender. An asynchronous service will delegate the message processing to another thread of execution and then return from the call, allowing the sender to proceed. An asynchronous service can send a response to the original sender at a later time as long as it has a return address of some form.

To receive messages, a service must listen on a named endpoint. In the case of direct, synchronous services, the client will use this endpoint information to send a message directly to the service. For routed services, the routing system must deliver the message to the target service when it arrives at its destination.

A service can potentially process a single type of message or it could process multiple types. In the latter case, there must be some way for it to determine which type of message has been received to process it correctly. One option is to apply a form of the Command pattern where the message contains information about how it should be processed. It is possible to put such information in the SOAP header, SOAP body, or in an attachment. However, embedding the command in the SOAP body is generally the best way.

Sending and Receiving SOAP Messages with SAAJ

The SOAP with Attachments API for Java (SAAJ) provides an API for the creation, manipulation, and exchange of SOAP messages. Figure 21.2 shows how an SAAJ client and server interact. As you can see, the client simply populates a SOAP envelope with an XML message and then sends this directly to the server. An SAAJ client can interact with any Web Service that complies with the SOAP 1.1 standard, and a service based on SAAJ can interact with any Web Service client that complies with that standard. To guarantee such interoperability, Sun delayed the release of J2EE 1.4 so that there was time to ensure it met the requirements of the Web Service Interoperability (WS-I) Basic Profile 1.0.