Intro to the JAXM Client Programming Model

Print-friendly Version

Articles Index

This article is intended for developers who want to learn more about the Java API for XML Messaging (JAXM) client programming model before delving into the JAXM specification.

There's a quick review of XML messaging concepts to illustrate how they relate to the overall JAXM model, but most of the article concentrates on the client view and the two types of JAXM clients that you can implement. I describe differences between the two clients, weigh their advantages and disadvantages, and then summarize the implementation details.

XML Messaging and JAXM

The Java API for XML Messaging assists developers in creating business-to-business messaging applications using XML. This API allows applications to create, send, and receive XML messages, such as the messages typical of Web services applications. You can break down those aspects of XML messaging that JAXM covers into the following four functional elements:

• The message
• The message sender
• The message receiver
• The message exchange

Figure 1 depicts the four functional elements that are covered by JAXM.

Figure 1: Elements of XML messaging covered by JAXM

JAXM Overview

To enable developers to write applications that use XML messaging, JAXM provides multiple elements that work together to provide the messaging facility. Table 1 outlines the mapping between the various portions of XML messaging and the functionality introduced by JAXM.

Table 1: Mapping XML messaging functionality to JAXM

Now let's move on to how the JAXM client fits into the overall JAXM model.

JAXM Client

A JAXM client sends XML messages to a recipient. The final recipient tends to be a service. JAXM clients can send the messages either directly to the service or to an intermediate provider called a JAXM messaging provider. Depending on how the client and recipient are configured, the client can function independently or use a provider. (Later in this article I go into more detail on the two types of clients.)

JAXM Messaging Provider

A JAXM messaging provider is an intermediate service that handles the transmission and routing of messages on behalf of the JAXM client. It also provides added functionality, such as reliable messaging, to the JAXM client. Once the JAXM client sends its message to the provider, the provider forwards the message to the final recipient. The messaging provider is used only if the JAXM client is configured to support it, not if the JAXM client is a standalone entity.

JAXM Messages

JAXM-compatible implementations must conform to the Simple Object Access Protocol (SOAP) 1.1 and the SOAP with Attachments specifications. Due to these compatibility requirements, a JAXM message must be a SOAP message, either with or without attachments. Figures 2 and 3 illustrate the format of these two types of messages.

Figure 2: SOAP message with attachment

Figure 3: SOAP message without attachment

The main difference between the two messages shown in Figure 2 and Figure 3 is that one message has at least one attachment while the other message has no attachments. Attachments can be any type of data included with the XML message, such as an image file or plain text. Multiple attachments are allowed. Messages with attachments require an extra MIME envelope to wrap both the message and the attachment together; the outer wrapper is not necessary for messages without attachments. For more background about these two types of SOAP messages, see For More Information at the end of this article.

The JAXM client creates the JAXM messages, which are exchanged between a client and a service, either directly or through a messaging provider. The JAXM API includes default messages that abide by the SOAP specification. The client can use the API to create and customize the message body and optional attachment prior to delivery.

JAXM Message Exchange

JAXM messages are exchanged between a client, the sender, and a final service -- the recipient. JAXM message exchanges fall into two categories: asynchronous and synchronous communication.

• Asynchronous exchange (one-way) The sender transmits a message to a recipient and does not wait for a response back from the recipient. It continues processing after it has sent the message. Once the receiver gets the message, it must read and process it. If a reply is necessary, the receiver sends a message to the sender with an appropriate response. The original sender might have to process the reply.
• Synchronous exchange (request-response) The sender transmits a message to a recipient and does not proceed until the receiver responds with a message. The receiver must process the message and reply to the sender with an acknowledgment or other information. This response unblocks the sender, which can then continue processing other work. A connection failure also unblocks the sender.

JAXM Service

A JAXM service consumes XML messages sent by a JAXM client. The service reads and processes the message from the client. The service's reaction to the client depends on the type of message exchange that is established between the two. This, in part, depends on the type of client sending the message, whether it's a standalone JAXM client, or a JAXM client that uses a messaging provider.

A Closer Look at JAXM Clients

So far you've met the two types of JAXM clients: The standalone client connects directly with a JAXM service for message exchange. The second type of JAXM client utilizes a messaging provider to transmit messages to a service.

This section describes the differences between the two types of clients, including their benefits and disadvantages. The following section outlines the implementation details and specification requirements of both clients.

Standalone JAXM Client

A standalone JAXM client is an independent Java 2 Platform Standard Edition (J2SE) application. A servlet could function as a standalone JAXM client. According to the JAXM specification, standalone clients can act only as clients, not as both clients and services. Due to this limitation, standalone clients must implement only the client portion of the JAXM API. Without a messaging provider, the standalone JAXM client connects directly to the desired service. The interaction between the client and the service must be a synchronous, request-response exchange. In other words, after the client sends a message to the service, it must block until the service responds. Figure 4 illustrates that interaction between the standalone client and service.


Figure 4: Standalone JAXM Client Interacting with a Service

JAXM Client That Uses a Messaging Provider

According to the JAXM specification, most JAXM clients use a messaging provider because of the added flexibility and functionality a messaging provider supplies. The only requirement for this type of client is that it must be deployed within a container. The container can either be a Java 2 Platform, Enterprise Edition (J2EE) Web container or a J2EE Enterprise JavaBeans (EJB) container. If the client is deployed in a Web container, the SOAP protocol must be bound to HTTP. In either case, the name of the provider must be supplied to the container at deploy time. Typically that is done by registering the provider with a naming service based on the Java Naming and Directory Interface (JNDI). Using JNDI, the client then establishes and maintains a connection with the messaging provider. The messaging provider handles both asynchronous and synchronous message exchanges on behalf of the client. The client knows nothing about the messaging provider except that it has a connection to it. Figure 5 illustrates a typical interaction between a JAXM client, a messaging provider, and a service.

Figure 5: A typical message exchange between a JAXM client, messaging provider, and service

The Client as Service

JAXM clients that use a messaging provider have the flexibility to also act as a service for other clients. Exactly how that works goes beyond the scope of this article, but you can learn more in the JAXM specification and tutorial.

Comparing the Two Clients

Although JAXM clients that use a messaging provider have more flexibility and added functionality, that type of client may not always be the right choice. Depending on the situation, one JAXM client will better suit your project than the other. To help you determine which JAXM client to use, consult the list of advantages and disadvantages in Table 2.

Table 2. Comparing the two types of JAXM clients

JAXM Client Implementation Details

Basically the JAXM clients work by setting up a connection, creating a message, sending it, and then concluding the processing. The process differs a bit for the two types of JAXM clients, as you'll see as you read on in this section.

Using the Standalone JAXM Client to Transmit Over a Point-to-Point Connection

Here's how a standalone JAXM client transmits a message to a service over a point-to-point connection.

The standalone JAXM client first establishes a direct SOAP connection with the service using a SOAPConnection object, which is created by the createConnection method of the SOAPConnectionFactory object:

SOAPConnectionFactory soapConnFactory = 
  SOAPConnectionFactory.newInstance ();
SOAPConnection soapConn = 
  soapConnFactory.createConnection ();

Then, the client creates a message to exchange with the service by creating a SOAPMessage object. A default SOAPMessage object is created through the MessageFactory object:

MessageFactory mesgFactory = 
  MessageFactory.newInstance ();
SOAPMessage soapMesg = 
  mesgFactory.createMessage ();

The default SOAPMessage object, soapMesg, returned by the createMessage method contains all of the necessary parts of a SOAP message. All the client has to do is populate the message.

Once the client has created the connection and the SOAP message, it sends the message to the service using the previously established direct connection. The message is sent to the service using the call method of the SOAPConnection object. Two parameters must be passed. The first one is the SOAP message and the second one is the URL of the service, represented by a URLEndpoint object:

SOAPMessage reply = soapConn.call ( soapMesg, serviceURL );

At this point, the client cannot continue processing until it receives the reply object from the JAXM service. Hence, the client is blocked until the recipient responds with a SOAP message; the only purpose of this message is to unblock the client. Of course, a connection failure also unblocks the client.

Transmitting Messages with a JAXM Client That Uses a Messaging Provider

Here's how a JAXM client that uses a messaging provider transmits a message to a service via the provider.

The JAXM client establishes a connection to the messaging provider using a ProviderConnection object. The connection is created by the createConnection method of the ProviderConnectionFactory object. The ProviderConnectionFactory object is created by retrieving the information about the provider using JNDI:

ProviderConnectionFactory providerConnFactory =
  /* retrieve provider using JNDI */
ProviderConnection providerConn = 
  providerConnFactory.createConnection ();

Before the client can send a message, it must understand what types of SOAP messages, or profiles, the messaging provider understands. The client can obtain this information by using the getMetaData method of the ProviderConnection object. Once the client picks a profile that the message provider supports, it can create a SOAPMessage object. A default SOAPMessage object, based on the profile, is created through the MessageFactory object:

MessageFactory mesgFactory = 
  providerConn.createMessageFactory (profile );
MesgImpl mesg = ( MesgImpl) 
  factory.createMessage ();

MesgImpl is a dummy implementation of a profile that is supported by the messaging provider. You must include Endpoint objects for both the client and the final destination in the message. The client must also populate the remainder of the message.

Next the client sends the message to the messaging provider using the ProviderConnection object, providerConn. The message is sent to the messaging provider using the send method of the ProviderConnection object. Because the messaging provider can determine the final recipient from the message itself, the only parameter that needs to be passed to the messaging provider by the send method is the message itself:

providerConn.send ( mesg );

At this point, whether the client blocks or continues processing depends on the type of message exchange that the final service is able to handle. JAXM services can handle either one-way messages or request-response messages, but not both. If the final JAXM service handles one-way message exchange, the JAXM client continues processing. On the other hand, if the service handles request-response message exchange, then the client blocks until the service returns a reply.

Sending SOAP Messages with Attachments

The application determines whether a message includes an attachment. Both types of JAXM clients can send SOAP messages with attachments. No matter how many attachments you expect, you need only one SOAPMessage, but the client needs an AttachmentPart object added to the SOAPMessage for every attachment.

Summary

From reading this article, you should have a clear picture of what a JAXM client is, including the two types of clients. While you understand that the two clients share similarities, you also know the differences that you must consider prior to implementation. In short, a standalone JAXM client is easier to implement, but it is limited by the fact that it can act only as a client and must communicate with a service using the request-response style of exchange. On the other hand, although a JAXM client that uses a messaging provider is more complicated to develop, it gives you more freedom for the style of exchange and its messaging provider adds flexibility. Depending on the situation, one client will be a better option than the other.

With this basic introduction to the client programming model in hand, you can explore further details of implementation in the materials suggested in For More Information.

For More Information

• Java API for XML Messaging (JAXM) v1.0 Specification
• The Java Web Services Tutorial: Java API for XML Messaging
• The Java Web Services Developer pack
• Java Web Services Developer Pack Tutorial
• Introduction to Web Services by Ed Ort
• Java Technology & Web Services home page
• Forums for Web services
• SOAP
• SOAP with Attachments

About the Author

Jennifer Rodoni is an engineer at Sun Microsystems, Inc. Currently, she works in the Market Development Engineering Organization and helps evangelize Java technology. She is also the author of An Introduction to the Java Connector Architecture. You can contact her at jennifer.rodoni@sun.com.