Overview of JAXM

This overview presents a high-level view of how JAXM messaging works and explains concepts in general terms. Its goal is to give you some terminology and a framework for the explanations and code examples that are presented in the tutorial section.

Messages

JAXM messages follow SOAP standards, which prescribe the format for messages and also specify some things that are required, optional, or not allowed. With the JAXM API, you can create XML messages that conform to the SOAP specifications simply by making Java API calls.

The Structure of an XML Document

An XML document has a hierarchical structure with elements, subelements, subsubelements, and so on. You will notice that many of the SAAJ classes and interfaces represent XML elements in a SOAP message and have the word element or SOAP or both in their names.

An element is also referred to as a node. Accordingly, the SAAJ API has the interface Node, which is the base class for all the classes and interfaces that represent XML elements in a SOAP message. There are also methods such as SOAPElement.addTextNode, Node.detachNode, and Node.getValue, which you will see how to use in the tutorial section.

What Is in a Message?

The two main types of SOAP messages are those that have attachments and those that do not.

Messages with No Attachments

The following outline and Figure 10-1 show the very high-level structure of a SOAP message with no attachments. Except for the SOAP header, all the parts listed are required.

The SAAJ API provides the SOAPMessage class to represent a SOAP message, SOAPPart to represent the SOAP part, SOAPEnvelope to represent the SOAP envelope, and so on.

When you create a new SOAPMessage object, it will automatically have the parts that are required to be in a SOAP message. In other words, a new SOAPMessage object has a SOAPPart object that contains a SOAPEnvelope object. The SOAPEnvelope object in turn automatically contains an empty SOAPHeader object followed by an empty SOAPBody object. If you do not need the SOAPHeader object, which is optional, you can delete it. The rationale for having it automatically included is that more often than not you will need it, so it is more convenient to have it provided.

The SOAPHeader object may contain one or more headers with information about the sending and receiving parties and about intermediate destinations for the message. Headers may also do things such as correlate a message to previous messages, specify a level of service, and contain routing and delivery information. The SOAPBody object, which always follows the SOAPHeader object if there is one, provides a simple way to send mandatory information intended for the ultimate recipient. If there is a SOAPFault object (see SOAP Faults), it must be in the SOAPBody object.

Messages with Attachments

A SOAP message may include one or more attachment parts in addition to the SOAP part. The SOAP part may contain only XML content; as a result, if any of the content of a message is not in XML format, it must occur in an attachment part. So, if for example, you want your message to contain an image file or plain text, your message must have an attachment part for it. Note that an attachment part can contain any kind of content, so it can contain data in XML format as well. Figure 10-2 shows the high-level structure of a SOAP message that has two attachments.

The SAAJ API provides the AttachmentPart class to represent the attachment part of a SOAP message. A SOAPMessage object automatically has a SOAPPart object and its required subelements, but because AttachmentPart objects are optional, you have to create and add them yourself. The tutorial section will walk you through creating and populating messages with and without attachment parts.

A SOAPMessage object may have one or more attachments. Each AttachmentPart object has a MIME header to indicate the type of data it contains. It may also have additional MIME headers to identify it or to give its location, which can be useful when there are multiple attachments. When a SOAPMessage object has one or more AttachmentPart objects, its SOAPPart object may or may not contain message content.

Another way to look at SOAP messaging is from the perspective of whether or not a messaging provider is used, which is discussed at the end of the section Messaging Providers.

Connections

All SOAP messages are sent and received over a connection. The connection can go directly to a particular destination or to a messaging provider. (A messaging provider is a service that handles the transmission and routing of messages and provides features not available when you use a connection that goes directly to its ultimate destination. Messaging providers are explained in more detail later.)

The JAXM API supplies the following class and interface to represent these two kinds of connections:

javax.xml.soap.SOAPConnection -- a connection from the sender directly to the receiver (a point-to-point connection)

javax.xml.messaging.ProviderConnection -- a connection to a messaging provider

SOAPConnection

A SOAPConnection object, which represents a point-to-point connection, is simple to create and use. One reason is that you do not have to do any configuration to use a SOAPConnection object because it does not need to run in a servlet container (like Tomcat) or in a J2EE server. It is the only kind of connection available to a client that does not use a messaging provider.

The following code fragment creates a SOAPConnection object and then, after creating and populating the message, uses the connection to send the message. The parameter request is the message being sent; endpoint represents where it is being sent.

SOAPConnectionFactory factory =
    SOAPConnectionFactory.newInstance();
SOAPConnection con = factory.createConnection();

. . .// create a request message and give it content

SOAPMessage response = con.call(request, endpoint);

When a SOAPConnection object is used, the only way to send a message is with the method call, which transmits its message and then blocks until it receives a reply. Because the method call requires that a response be returned to it, this type of messaging is referred to as request-response messaging.

A Web service implemented for request-response messaging must return a response to any message it receives. When the message is an update, the response is an acknowledgement that the update was received. Such an acknowledgement implies that the update was successful. Some messages may not require any response at all. The service that gets such a message is still required to send back a response because one is needed to unblock the call method. In this case, the response is not related to the content of the message; it is simply a message to unblock the call method.

Because the signature for the javax.xml.soap.SOAPConnection.call method changed in the SAAJ 1.1 specification, a JAXM implementation may elect not to implement the call method. To allow for this, there is a new exception on the SOAPConnectionFactory class stating that SOAPConnection is not implemented, which allows for a graceful failure.

Unlike a client with no messaging provider, which is limited to using only a SOAPConnection object, a client that uses a messaging provider is free to use a SOAPConnection object or a ProviderConnection object. It is expected that ProviderConnection objects will be used most of the time.

ProviderConnection

A ProviderConnection object represents a connection to a messaging provider. (The next section explains more about messaging providers.) When you send a message via a ProviderConnection object, the message goes to the messaging provider. The messaging provider forwards the message, following the message's routing instructions, until the message gets to the ultimate recipient's messaging provider, which in turn forwards the message to the ultimate recipient.

When an application is using a ProviderConnection object, it must use the method ProviderConnection.send to send a message. This method transmits the message one way and returns immediately, without having to block until it gets a response. The messaging provider that receives the message will forward it to the intended destination and return the response, if any, at a later time. The interval between sending a request and getting the response may be very short, or it may be measured in days. In this style of messaging, the original message is sent as a one-way message, and any response is sent subsequently as a one-way message. Not surprisingly, this style of messaging is referred to as one-way messaging.

Messaging Providers

A messaging provider is a service that handles the transmission and routing of messages. It works behind the scenes to keep track of messages and see that they are sent to the proper destination or destinations.

Transparency

One of the great features of a messaging provider is that you are not even aware of it. You just write your JAXM application, and the right things happen. For example, when you are using a messaging provider and send a message by calling the ProviderConnection.send method, the messaging provider receives the message and works with other parts of the communications infrastructure to perform various tasks, depending on what the message's header contains and how the messaging provider itself has been implemented. The message arrives at its final destination without your even knowing about the details involved in accomplishing the delivery.

Profiles

JAXM offers the ability to plug in additional protocols that are built on top of SOAP. A JAXM provider implementation is not required to implement features beyond what the SOAP 1.1 and SOAP with Attachments specifications require, but it is free to incorporate other standard protocols, called profiles, that are implemented on top of SOAP. For example, the "ebXML Message Service Specification" (available at http://www.oasis-open.org/committees/ebxml-msg/) defines levels of service that are not included in the two SOAP specifications. A messaging provider that is implemented to include ebXML capabilities on top of SOAP capabilities is said to support an ebXML profile. A messaging provider may support multiple profiles, but an application can use only one at a time and must have a prior agreement with each of the parties to whom it sends messages about what profile is being used.

Profiles affect a message's headers. For example, depending on the profile, a new SOAPMessage object will come with certain headers already set. Also a profile implementation may provide API that makes it easier to create a header and set its content. The JAXM reference implementation includes APIs for both the ebXML and SOAP-RP profiles. The Javadoc documentation for these profiles is at <S1STUDIO_HOME>/jwsdp/docs/jaxm/profiles/index.html. You will find links to the Javadoc documentation for the JAXM API (the javax.xml.soap and javax.xml.messaging packages) at <S1STUDIO_HOME>/jwsdp/docs/api/index.html.

Continuously Active

A messaging provider works continuously. A JAXM client may make a connection with its provider, send one or more messages, and then close the connection. The provider will store the message and then send it. Depending on how the provider has been configured, it will resend a message that was not successfully delivered until it is successfully delivered or until the limit for the number of resends is reached. Also, the provider will stay in a waiting state, ready to receive any messages that are intended for the client. The provider will store incoming messages so that when the client connects with the provider again, the provider will be able to forward the messages. In addition, the provider generates error messages as needed and maintains a log where messages and their related error messages are stored.

Intermediate Destinations

When a messaging provider is used, a message can be sent to one or more intermediate destinations before going to the final recipient. These intermediate destinations, called actors, are specified in the message's SOAPHeader object. For example, assume that a message is an incoming Purchase Order. The header might route the message to the order input desk, the order confirmation desk, the shipping desk, and the billing department. Each of these destinations is an actor that will take the appropriate action, remove the header information relevant to it, and send the message to the next actor. The default actor is the final destination, so if no actors are specified, the message is routed to the final recipient.

The attribute actor is used to specify an intermediate recipient. A related attribute is mustUnderstand, which, when its value is true, means that an actor must understand what it is supposed to do and carry it out successfully. A SOAPHeader object uses the method addAttribute to add these attributes, and the SOAPHeaderElement interface provides methods for setting and getting the values of these attributes.

When to Use a Messaging Provider

A JAXM client may or may not use a messaging provider. Generally speaking, if you just want to be a consumer of Web services, you do not need a messaging provider. The following list shows some of the advantages of not using a messaging provider:

The application can be written using the J2SE platform

The application is not required to be deployed in a servlet container or a J2EE server

No configuration is required

The client can send only request-response messages

The client can act in the client role only

It follows that if you want to provide a Web service that is able to get and save requests that are sent to you at any time, you must use a messaging provider. You will also need to run in a container, which provides the messaging infrastructure used by the provider. A messaging provider gives you the flexibility to assume both the client and service roles, and it also lets you send one-way messages. In addition, if your messaging provider supports a protocol such as ebXML or SOAP-RP on top of SOAP, you can take advantage of the additional quality of service features that it provides.

Messaging with and without a Provider

JAXM clients can be categorized according to whether or not they use a messaging provider. Those that do not use a messaging provider can be further divided into those that run in a container and those that do not. A JAXM client that does not use a messaging provider and also does not run in a container is called a standalone client.