The Java(TM) Web Services Tutorial

The Java^TM Web Services Tutorial

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.

The overview looks at JAXM from three perspectives:

Messages
Connections
Messaging providers

Messages

JAXM messages follow SOAP standards. That is, they conform to the Simple Object Access Protocol (SOAP) 1.1 and SOAP with Attachments specifications, 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 these SOAP specifications simply by making Java API calls.

The Structure of an XML Document

Note: For more complete information on XML documents, see Understanding XML and Java API for XML Processing.

An XML document has a hierarchical structure with elements, subelements, subsubelements, and so on. You will notice that many of the JAXM 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 JAXM 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 shows the very high level structure of a JAXM message with no attachments. Except for the SOAP header, all the parts listed are required.

I. SOAP message

     A. SOAP part

         1. SOAP envelope

              a. SOAP header (optional)

              b. SOAP body

The JAXM 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.

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 than an attachment part can contain any kind of content, so it can contain data in XML format as well.

The following outline shows the high-level structure of a SOAP message that has two attachments, one containing plain text and one containing an image.

I. SOAP message

     A. SOAP part

         1. SOAP envelope

              a. SOAP header (optional)

              b. SOAP body

     B. Attachment part (content is plain text)

     C. Attachment part (content is an image file)

JAXM 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.

Another way to look at JAXM 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 JAXM 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:

SOAPConnection -- a connection from the sender directly to the receiver (a point-to-point connection)
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 a J2EE container. 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. As stated in the previous section, a request-response message will always be sent using the SOAPConnection.call method, which requires that a message be returned to unblock it. Most often, the message being sent is a request, and the message that is returned is the response.

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.

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 result is that the message arrives at its final destination without your being aware of any of 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 Routing, Transport, and Packaging V1.0--Message Service Specification" 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 RI includes APIs for both the ebXML and SOAP-RP profiles. The Javadoc documentation for these profiles is at <JWSDP_HOME>/docs/jaxm/profiles/index.html. (You will find links to the Javadoc documentation for the JAXM API at <JWSDP_HOME>/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 container such as Tomcat or a J2EE container
No configuration is required

The limitations of not using a messaging provider are the following:

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, meaning that you must be 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.

Home
TOC