The javax.xml.messaging package contains the classes and interfaces that make up the Java API for XML-based Messaging (JAXM). JAXM is a software layer above SAAJ that provides the same access to the low-level features of SOAP messaging and adds the following features:

Asynchronous message transmission

Whereas a SAAJ client blocks after sending a message until the server sends a response, JAXM clients resume execution shortly after the message is sent. In fact, JAXM does not recognize the concept of request-response messaging, viewing these instead as the transmission and receipt of two independent messages.

More reliable delivery

If the intended recipient of a SOAP message is not active or not reachable when a SAAJ client transmits it, the message is not delivered and the application is responsible for error recovery. By contrast, messages sent by JAXM clients are resent a configurable number of times before being considered undeliverable. As a consequence of this, a JAXM receiver may receive messages that were sent to it while it was inactive.

Profiles

JAXM implementations may support one or more industry-standard profiles that represent agreed ways to construct SOAP messages. Application code is required to specify the profile to be used and supply the values to be included in the message, but the JAXM implementation is responsible for ensuring that the message is constructed as required by the profile.

JAXM provides these features by interposing message providers between the JAXM sender and the JAXM receiver. Instead of addressing and sending a SOAP message directly to its ultimate recipient, the sender instead delivers it to a local messaging provider. The destination address in the message is typically not that of the receiver, but a URI (actually an instance of the Endpoint class) that the provider will map to a real address using internal configuration information. The resolved address will actually be that of another JAXM provider that is local to receiver. Having chosen the destination, the sending provider transmits the message one or more times until it is successfully delivered to the peer JAXM provider or a configurable retry limit is reached. Since the call made by the JAXM client to send the message returns before it is known whether the message will be successfully delivered, no reporting of errors to the client is possible when using JAXM.

When a JAXM provider receives a message, it maps the destination address to a local endpoint and looks for a receiver willing to receive messages for that endpoint. If such a receiver exists, the message is delivered to it. If not, the provider retains the message for a configurable period, waiting for a receiver to register to receive messages addressed to that endpoint. If no such client registers within the time-out period, the message is discarded.

The asynchronous nature of the message delivery path means that a provider must be able to deliver a message to a receiver at any time. Since all communication takes place over HTTP, this means that the message receiver must be prepared to accept an HTTP connection. Since J2SE does not provide a server-side implementation of HTTP, the practical implication of this is that all JAXM clients that wish to receive messages must be container-resident.

The configuration information required to allow a JAXM provider to map between logical Endpoint addresses and real network addresses, and the mechanism used by a receiver to specify the Endpoint address or addresses on which it is prepared to listen are implementation-dependent. Refer to Chapter 4 for a description of the mechanism used by the JAXM reference implementation.

JAXM providers typically support only profiled messages. The reference implementation provides basic support for the WS-Routing profile (formerly known as SOAP-RP) and the ebXML TRP profile. The API required for these profiles is not part of the JAXM specification and cannot, therefore, be considered portable. No coverage of these APIs is provided in this chapter, although there is some discussion of both profiles in Chapter 4.

Since JAXM senders and receivers always communicate directly with a provider rather than with each other, they are both in the client role relative to the provider, even though one of them may play the server role in respect of their (indirect) interaction with each other. Throughout this section, the term "JAXM client" will be used to refer to both a JAXM sender or a receiver.

Unlike SAAJ, JAXM was not incorporated in the J2EE 1.4 platform. There is, however, an implementation available in the JWSDP, although its applicability is clearly going to be limited for the time being unless the J2EE vendors provide their own implementations.

Interfaces

public interface OnewayListener;
public interface ProviderConnection;
public interface ProviderMetaData;
public interface ReqRespListener;

Classes

public class Endpoint;
public class URLEndpoint extends Endpoint;
public abstract class JAXMServlet extends javax.servlet.http.HttpServlet;
public abstract class ProviderConnectionFactory;

Exceptions

public class JAXMException extends javax.xml.soap.SOAPException;