Download
FAQ History |
![]() ![]() ![]() |
API
Search Feedback |
SAAJ
The SOAP with Attachments API for Java (SAAJ) provides a standard way to send XML documents over the Internet from the Java platform. It is based on the SOAP 1.1 and SOAP with Attachments specifications, which define a basic framework for exchanging XML messages.
See Chapter 13 to see how to use the SAAJ API and run the SAAJ examples that are included with this tutorial.
A SAAJ client is a standalone client. That is, it sends point-to-point messages directly to a Web service that is implemented for request-response messaging. Request-response messaging is synchronous, meaning that a request is sent and its response is received in the same operation. A request-response message is sent over a
SOAPConnection
object via the methodSOAPConnection.call
, which sends the message and blocks until it receives a response. A standalone client can operate only in a client role, that is, it can only send requests and receive their responses.A
SOAPMessage
object represents an XML document that is a SOAP message. ASOAPMessage
object always has a required SOAP part, and it may also have one or more attachment parts. The SOAP part must always have aSOAPEnvelope
object, which must in turn always contain aSOAPBody
object. TheSOAPEnvelope
object may also contain aSOAPHeader
object, to which one or more headers can be added.The
SOAPBody
object can hold XML fragments as the content of the message being sent. If you want to send content that is not in XML format or that is an entire XML document, your message will need to contain an attachment part in addition to the SOAP part. There is no limitation on the content in the attachment part, so it can include images or any other kind of content, including XML fragments and documents. Common types of attachment include sound, picture, and movie data:.mp3
,.jpg
, and.mpg
files.Getting a Connection
The first thing a SAAJ client needs to do is get a connection in the form of a
SOAPConnection
object. ASOAPConnection
object is a point-to-point connection that goes directly from the sender to the recipient. The connection is created by aSOAPConnectionFactory
object. A client obtains the default implementation forSOAPConnectionFactory
by calling the following line of code.The client can use
factory
to create aSOAPConnection
object.Creating a Message
Messages, like connections, are created by a factory. To obtain a
MessageFactory
object, you get an instance of the default implementation for theMessageFactory
class. This instance can then be used to create aSOAPMessage
object.MessageFactory messageFactory = MessageFactory.newInstance(); SOAPMessage message = messageFactory.createMessage();All of the
SOAPMessage
objects thatmessageFactory
creates, includingmessage
in the previous line of code, will be SOAP messages. This means that they will have no pre-defined headers.The new
SOAPMessage
objectmessage
automatically contains the required elementsSOAPPart
,SOAPEnvelope
, andSOAPBody
, plus the optional elementSOAPHeader
(which is included for convenience). TheSOAPHeader
andSOAPBody
objects are initially empty, and the following sections will illustrate some of the typical ways to add content.Populating a Message
Content can be added to the
SOAPPart
object, to one or moreAttachmentPart
objects, or to both parts of a message.Populating the SOAP Part of a Message
As stated earlier, all messages have a
SOAPPart
object, which has aSOAPEnvelope
object containing aSOAPHeader
object and aSOAPBody
object. One way to add content to the SOAP part of a message is to create aSOAPHeaderElement
object or aSOAPBodyElement
object and add an XML fragment that you build with the methodSOAPElement.addTextNode
. The first three lines of the following code fragment access theSOAPBody
objectbody
, which is used to create a newSOAPBodyElement
object and add it tobody
. The argument passed to thecreateName
method is aName
object identifying theSOAPBodyElement
being added. The last line adds the XML string passed to the methodaddTextNode
.SOAPPart soapPart = message.getSOAPPart(); SOAPEnvelope envelope = soapPart.getSOAPEnvelope(); SOAPBody body = envelope.getSOAPBody(); SOAPBodyElement bodyElement = body.addBodyElement( envelope.createName("text", "hotitems", "http://hotitems.com/products/gizmo"); bodyElement.addTextNode("some-xml-text");Another way is to add content to the
SOAPPart
object by passing it aj
avax.xml.transform.Source
object, which may be aSAXSource
,DOMSource
, orStreamSource
object. TheSource
object contains content for the SOAP part of the message and also the information needed for it to act as source input. AStreamSource
object will contain the content as an XML document; theSAXSource
orDOMSource
object will contain content and instructions for transforming it into an XML document.The following code fragments illustrates adding content as a
DOMSource
object. The first step is to get theSOAPPart
object from theSOAPMessage
object. Next the code uses methods from the JAXP API to build the XML document to be added. It uses aDocumentBuilderFactory
object to get aDocumentBuilder
object. Then it parses the given file to produce the document that will be used to initialize a newDOMSource
object. Finally, the code passes theDOMSource
objectdomSource
to the methodSOAPPart.setContent
.SOAPPart soapPart = message.getSOAPPart(); DocumentBuilderFactory dbFactory= DocumentBuilderFactory.newInstance(); DocumentBuilder builder = dbFactory.newDocumentBuilder(); Document document = builder.parse("file:///foo.bar/soap.xml"); DOMSource domSource = new DOMSource(document); soapPart.setContent(domSource);This code would work equally well with a
SAXSource
or aStreamSource
object.You use the
setContent
method when you want to send an existing SOAP message. If you have an XML document that you want to send as the content of a SOAP message, you use theaddDocument
method on the body of the message:This allows you to keep your application data in a document that is separate from the SOAP envelope unless and until it is time to send that data as a message.
Populating the Attachment Part of a Message
A
Message
object may have no attachment parts, but if it is to contain anything that is not in XML format, that content must be contained in an attachment part. There may be any number of attachment parts, and they may contain anything from plain text to image files. In the following code fragment, the content is an image in a JPEG file, whose URL is used to initialize thejavax.activation.DataHandler
objecthandler
. TheMessage
objectmessage
creates theAttachmentPart
objectattachPart
, which is initialized with the data handler containing the URL for the image. Finally, the message addsattachPart
to itself.URL url = new URL("http://foo.bar/img.jpg"); DataHandler handler = new DataHandler(url); AttachmentPart attachPart = message.createAttachmentPart(handler); message.addAttachmentPart(attachPart);A
SOAPMessage
object can also give content to anAttachmentPart
object by passing anObject
and its content type to the methodcreateAttachmentPart
.AttachmentPart attachPart = message.createAttachmentPart("content-string", "text/plain"); message.addAttachmentPart(attachPart);Sending a Message
Once you have populated a
SOAPMessage
object, you are ready to send it. A client uses theSOAPConnection
methodcall
to send a message. This method sends the message and then blocks until it gets back a response. The arguments to the methodcall
are the message being sent and aURL
object that contains the URL specifying the endpoint of the receiver.
Download
FAQ History |
![]() ![]() ![]() |
API
Search Feedback |
All of the material in The Java(TM) Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.