Java Web Services in a Nutshell

Chapter 4. JAXM

SAAJ is a convenient API that allows applications to exchange SOAP messages containing information encoded in XML, together with arbitrary data held in message attachments. Although it is useful on its own, SAAJ is also the basis for JAX-RPC and for the Java API for XML Messaging (JAXM). This chapter looks at the features that JAXM adds to SAAJ and describes how to configure and use the JAXM reference implementation.

Warning

Although JAXM is part of the Java Web Services Developers Pack, it is not one of the APIs that was selected for inclusion in Version 1.4 of the J2EE platform. The examples in this chapter can therefore only be used with the JWSDP. JAXM may be integrated into a future release of J2EE, but at the time of this writing, there is no commitment on Sun’s part to do this.

JAXM Overview

SAAJ allows you to construct SOAP messages and send them directly and synchronously to a web service. JAXM builds on SAAJ to provide a higher-level API with the following additional features:

Messaging profiles

The SOAP messages returned by the SAAJ MessageFactory consist of an empty body and an empty header. However, there are established uses of SOAP that make use of message headers to convey information from the message sender to the receiver, or to intermediate nodes that the message might traverse along its delivery path. JAXM provides the concept of messaging profiles , where a profile represents a specific and standardized way of constructing a SOAP message, such as the ebXML Message Service. A JAXM messaging profile is represented by a profile-specific MessageFactory that can build SOAP messages according to the rules applicable to the profile.

Asynchronous messaging

Using SAAJ, you can only send a message directly to a service and then wait for the service to send a reply. This mode of operation is well-suited to RPC-style interaction, in which the server is able to reply almost immediately to an incoming message. In many cases, however, it is not possible to operate in this way. If a client submits a purchase order to a company’s online business web service, for example, it may not be possible to respond immediately with an order confirmation or an invoice for payment. In these circumstances, it is useful to be able to simply send a message and be prepared to receive a reply at a later time. JAXM supports this by providing several asynchronous messaging modes, described in Section 4.1.1 next.

More robust message delivery

SAAJ requires both the sender and receiver of a message to be active at the same time and works only if it is possible to make a direct connection between the two (although transparent hops — i.e., proxies — are supported in the same way as they are by the generic HTTP support in the JRE). JAXM removes both of these restrictions by providing an intermediary messaging provider that is responsible for the handling of all messages. A messaging provider delivers a message by forwarding it, not to the intended recipient, but to another messaging provider, which may or may not be directly connected to the message destination. If delivery to the next provider fails, perhaps because it is not active or because of a temporary lack of network connectivity, the sending provider can be configured to retransmit the message a specified number of times. If a provider receives a message for a recipient that is not currently active, it can store it until the recipient becomes active.

JAXM Message Delivery Modes

The JAXM specification (available at http://jcp.org/jsr/detail/67.jsp) requires support for three asynchronous message delivery modes in addition to the synchronous reply/response mode supported by SAAJ.^[40]

Asynchronous inquiry

In an asynchronous inquiry, shown in Figure 4-1, the sender constructs a request (such as a purchase order) and sends it to the web service, then continues with other processing.

Figure 4-1. Message flow for an asynchronous inquiry

When the target web service receives the request, it may or may not process it immediately. Either way — possibly days after the request was received — it creates a reply message (perhaps containing an order confirmation) and returns it to the sender of the request.

When asynchronous messaging is used, it is necessary for the sender to be able to match each reply to the original request message. JAXM does not concern itself with how this is done, assuming that it is part of the application-level protocol. The SOAP-RP profile, for example, defines a SOAP header that allows a message reference to be included with a request and a matching cross-reference to be sent with the response. See Section 4.5 later in this chapter for details.

Asynchronous update

From the messaging viewpoint, an asynchronous update (shown in Figure 4-2) is identical to an asynchronous inquiry. At the application level, however, there is a difference: the reply to an update is simply an acknowledgement that the request was received, which may or may not imply that the request has been successfully actioned. The exact semantics of the acknowledgement are application-dependent.

Figure 4-2. Message flow for an asynchronous update

Fire-and-forget

Fire-and-forget, shown in Figure 4-3, simply involves sending a message to a receiver. Since the sender does not receive any acknowledgement from the receiver, it cannot rely on the safe delivery of the message; therefore, this mode cannot be used when reliability is a concern. This mode is suited to noncritical functions, such as logging, in which the overhead involved in generating or waiting for confirmation of receipt is unacceptable, and in which the loss of messages does not have any direct impact on the integrity of the business process.

Figure 4-3. Message flow for fire-and-forget

---

^[40] In fact, the JAXM specification describes five message delivery modes. In addition to the three listed here, the other two are synchronous inquiry and synchronous update, both of which result in the sender blocking until a reply to its request is received. In the first case, the reply message contains some useful information, while in the second case, it is an acknowledgment that the request was received. These two cases are not covered here, because they are provided by SAAJ, not JAXM.