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:
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
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 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
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 SOAP 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 SAAJ API provides the
SOAPMessageclass to represent a SOAP message,
SOAPPartto represent the SOAP part,
SOAPEnvelopeto represent the SOAP envelope, and so on.
When you create a new
SOAPMessageobject, it will automatically have the parts that are required to be in a SOAP message. In other words, a new
SOAPMessageobject has a
SOAPPartobject that contains a
SOAPEnvelopeobject in turn automatically contains an empty
SOAPHeaderobject followed by an empty
SOAPBodyobject. If you do not need the
SOAPHeaderobject, 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.
SOAPHeaderobject 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
SOAPBodyobject, which always follows the
SOAPHeaderobject if there is one, provides a simple way to send mandatory information intended for the ultimate recipient. If there is a
SOAPFaultobject (see SOAP Faults), it must be in the
SOAPMessageObject with No Attachments
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. Figure 10-2 shows the high-level structure of a SOAP message that has two attachments.
SOAPMessageObject with Two
The SAAJ API provides the
AttachmentPartclass to represent the attachment part of a SOAP message. A
SOAPMessageobject automatically has a
SOAPPartobject and its required subelements, but because
AttachmentPartobjects 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.
SOAPMessageobject may have one or more attachments. Each
AttachmentPartobject 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
SOAPMessageobject has one or more
SOAPPartobject 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.
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
SOAPConnectionobject, 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
SOAPConnectionobject because it does not need to run in a servlet container (like Tomcat) or in 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
SOAPConnectionobject 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);
SOAPConnectionobject 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
callrequires 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
callmethod. In this case, the response is not related to the content of the message; it is simply a message to unblock the
Because the signature for the
javax.xml.soap.SOAPConnection.callmethod changed in the SAAJ 1.1 specification, a JAXM implementation may elect not to implement the
callmethod. To allow for this, there is a new exception on the
SOAPConnectionFactoryclass stating that
SOAPConnectionis not implemented, which allows for a graceful failure.
Unlike a client with no messaging provider, which is limited to using only a
SOAPConnectionobject, a client that uses a messaging provider is free to use a
SOAPConnectionobject or a
ProviderConnectionobject. It is expected that
ProviderConnectionobjects will be used most of the time.
ProviderConnectionobject represents a connection to a messaging provider. (The next section explains more about messaging providers.) When you send a message via a
ProviderConnectionobject, 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
ProviderConnectionobject, it must use the method
ProviderConnection.sendto 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.
Figure 10-3 Request-response and One-way Messaging
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.
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
sendmethod, 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.
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
SOAPMessageobject 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
>/docs/jaxm/profiles/index.html. You will find links to the Javadoc documentation for the JAXM API (the
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.
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
SOAPHeaderobject. 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.
actoris 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
SOAPHeaderobject uses the method
addAttributeto add these attributes, and the
SOAPHeaderElementinterface provides methods for setting and getting the values of these attributes.
Figure 10-4 One-way Message with Intermediate Destinations
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 container
- No configuration is required
The limitations of not using a messaging provider are the following:
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.
This tutorial contains information on the 1.0 version of the Java Web Services Developer Pack.
All of the material in The Java Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.