Movatterモバイル変換

Overview of SAAJ

This section presents a high-level view of how SAAJ messaging works and explainsconcepts in general terms. Its goal is to give you some terminology anda framework for the explanations and code examples that are presented in thetutorial section.

The overview looks at SAAJ from two perspectives: messages and connections.

SAAJ Messages

SAAJ messages follow SOAP standards, which prescribe the format for messages and alsospecify some things that are required, optional, or not allowed. With the SAAJAPI, you can create XML messages that conform to the SOAP 1.1 or1.2 specification and to the WS-I Basic Profile 1.1 specification simply by makingJava API calls.

The Structure of an XML Document

An XML document has a hierarchical structure made up of elements, subelements, subsubelements,and so on. You will notice that many of the SAAJ classesand interfaces represent XML elements in a SOAP message and have the wordelement orSOAP (or both) in their names.

An element is also referred to as anode. Accordingly, the SAAJ APIhas the interfaceNode, which is the base class for all the classesand interfaces that represent XML elements in a SOAP message. There are alsomethods such asSOAPElement.addTextNode,Node.detachNode, andNode.getValue, which you will see how touse in the tutorial section.

What Is in a Message?

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

Messages with No Attachments

The following outline shows the very high-level structure of a SOAP message withno attachments. Except for the SOAP header, all the parts listed are requiredto be in every SOAP message.

I. SOAP message A. SOAP part 1. SOAP envelope a. SOAP header (optional) b. SOAP body

The SAAJ API provides theSOAPMessage class to represent a SOAP message, theSOAPPart class to represent the SOAP part, theSOAPEnvelope interface to represent the SOAPenvelope, and so on.Figure 19-1 illustrates the structure of a SOAP message withno attachments.

Figure 19-1SOAPMessage Object with No Attachments

Diagram of SOAPMessage Object with SOAPPart, SOAPEnvelope, SOAPHeader, and SOAPBody

Note -Many SAAJ API interfaces extend DOM interfaces. In a SAAJ message, theSOAPPartclass is also a DOM document. SeeSAAJ and DOM for details.

When you create a newSOAPMessage object, it will automatically have the partsthat are required to be in a SOAP message. In other words, anewSOAPMessage object has aSOAPPart object that contains aSOAPEnvelope object. TheSOAPEnvelope object in turn automatically contains an emptySOAPHeader object followed by anemptySOAPBody object. If you do not need theSOAPHeader object, which isoptional, you can delete it. The rationale for having it automatically included isthat more often than not you will need it, so it ismore convenient to have it provided.

TheSOAPHeader object can include one or more headers that contain metadata aboutthe message (for example, information about the sending and receiving parties). TheSOAPBodyobject, which always follows theSOAPHeader object if there is one, contains the messagecontent. If there is aSOAPFault object (seeUsing SOAP Faults), it must bein theSOAPBody object.

Messages with Attachments

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

Figure 19-2SOAPMessage Object with Two AttachmentPart Objects

Diagram of SOAPMessage Object with SOAPPart, SOAPEnvelope, SOAPHeader, SOAPBody, and two AttachmentParts

The SAAJ API provides theAttachmentPart class to represent an attachment part ofa SOAP message. ASOAPMessage object automatically has aSOAPPart object and itsrequired subelements, but becauseAttachmentPart objects are optional, you must create and add themyourself. The tutorial section walks you through creating and populating messages with andwithout attachment parts.

If aSOAPMessage object has one or more attachments, eachAttachmentPart object musthave a MIME header to indicate the type of data it contains. Itmay also have additional MIME headers to identify it or to give itslocation. These headers are optional but can be useful when there are multipleattachments. When aSOAPMessage object has one or moreAttachmentPart objects, itsSOAPPartobject may or may not contain message content.

SAAJ and DOM

The SAAJ APIs extend their counterparts in theorg.w3c.dom package:

TheNode interface extends theorg.w3c.dom.Node interface.
TheSOAPElement interface extends both theNode interface and theorg.w3c.dom.Element interface.
TheSOAPPart class implements theorg.w3c.dom.Document interface.
TheText interface extends theorg.w3c.dom.Text interface.

Moreover, theSOAPPart of aSOAPMessage is also a DOM Level 2Documentand can be manipulated as such by applications, tools, and libraries that useDOM. For details on how to use DOM documents with the SAAJ API,seeAdding Content to theSOAPPart Object andAdding a Document to the SOAP Body.

SAAJ Connections

All SOAP messages are sent and received over a connection. With the SAAJAPI, the connection is represented by aSOAPConnection object, which goes from thesender directly to its destination. This kind of connection is called apoint-to-pointconnection because it goes from one endpoint to another endpoint. Messages sent usingthe SAAJ API are calledrequest-response messages. They are sent over aSOAPConnection object withthecall method, which sends a message (a request) and then blocks untilit receives the reply (a response).

`SOAPConnection` Objects

The following code fragment creates theSOAPConnection objectconnection and then, aftercreating and populating the message, usesconnection to send the message. As statedpreviously, all messages sent over aSOAPConnection object are sent with thecall method,which both sends the message and blocks until it receives the response. Thus,the return value for thecall method is theSOAPMessage object thatis the response to the message that was sent. Therequest parameter is themessage being sent;endpoint represents where it is being sent.

SOAPConnectionFactory factory = SOAPConnectionFactory.newInstance();SOAPConnection connection = factory.createConnection();. . .// create a request message and give it contentjava.net.URL endpoint = new URL("http://fabulous.com/gizmo/order");SOAPMessage response = connection.call(request, endpoint);

Note that the second argument to thecall method, which identifies where the messageis being sent, can be aString object or aURL object. Thus,the last two lines of code from the preceding example could also havebeen the following:

String endpoint = "http://fabulous.com/gizmo/order";SOAPMessage response = connection.call(request, endpoint);

A web service implemented for request-response messaging must return a response to anymessage it receives. The response is aSOAPMessage object, just as the requestis aSOAPMessage object. When the request message is an update, the responseis an acknowledgment that the update was received. Such an acknowledgment implies thatthe update was successful. Some messages may not require any response at all.The service that gets such a message is still required to send backa response because one is needed to unblock thecall method. In thiscase, the response is not related to the content of the message; itis simply a message to unblock thecall method.

Now that you have some background on SOAP messages and SOAP connections, inthe next section you will see how to use the SAAJ API.