You are on page 1of 32


Design of Distributed System Software


SOAP with Attachments API


• SOAP with Attachments API for Java (SAAJ)

– used mainly for the SOAP messaging that goes on behind the scenes in JAX-RPC and JAXR

• An API that can be used to write SOAP messaging applications directly rather than use JAX-

• The SAAJ API allows to do XML messaging from the Java platform:
– making method calls using the SAAJ API, read and write SOAP-based XML messages,
– optionally send and receive such messages over the Internet

• The SAAJ 1.2 specification defines the javax.xml.soap package, which contains the API for
creating and populating a SOAP message.

• APIs necessary for sending request-response messages.


• SAAJ specifies
– messages and
– connections

• Messages:
• without attachments and with attachments
– follow SOAP standards: message format and operations
– called request-response messages
– SAAJ API -- create XML messages that conform to the
SOAP 1.1 and WS-I Basic Profile 1.0 specifications
simply by making Java API calls.

• Connections
– SOAP messages are sent and received over a
– SAAJ API -- the connection is represented by a
SOAPConnection object, which goes from the sender
directly to its destination.
• a point-to-point connection because it goes from one
endpoint to another endpoint.
– SAAJ Messages are sent over a SOAPConnection
object with the call method, which sends a message (a
request) and then blocks until it receives the reply (a

• SAAJ API has the interface Node,

– base class for all the classes and interfaces that
represent XML elements in a SOAP message.
• methods : SOAPElement.addTextNode,
Node.detachNode, and Node.getValue,
Messages with No Attachments
• Required SOAP message .

I. SOAP message
– A. SOAP part
• 1. SOAP envelope
– a. SOAP header (optional)
– b. SOAP body
Messages with Attachments

• A SOAP message may include one or

more attachment parts in addition to the
SOAP part.

• The SOAP part must contain only XML

– if the content of a message is not in XML
format, it must occur in an attachment
• SAAJ 1.2-- APIs extend their counterparts in the org.w3c.dom package:

– Node interface extends org.w3c.dom.Node interface.

– SOAPElement interface extends - Node & org.w3c.dom.Element interfaces.
– SOAPPart class implements org.w3c.dom.Document interface.
– Text interface extends the org.w3c.dom.Text interface.

• SOAPPart is a DOM Level 2 Document and can be manipulated as such

by applications, tools, and libraries that use DOM.
SOAPConnection Objects

SOAPConnectionFactory factory =
SOAPConnection connection = factory.createConnection();
. . .// create a request message and give it content endpoint =
new URL("");
SOAPMessage response =, endpoint);

• Some messages may not require any response at all.

– Service still required to send back a response
Creating a Message

• Create a message using a MessageFactory object.

MessageFactory factory = MessageFactory.newInstance();

SOAPMessage message = factory.createMessage();

• As is true of the newInstance method for SOAPConnectionFactory, the

• method for MessageFactory is static, so you invoke it by calling
• newInstance.
Parts of a Message

• The message, automatically has the following:

– I. A SOAPPart object that contains
• A. A SOAPEnvelope object that contains
– 1. An empty SOAPHeader object
– 2. An empty SOAPBody object
• The SOAPHeader object must precede the SOAPBody object.
• The SOAPBody object can hold either the content of the message or a
fault message that contains status information or details about a
problem with the message.
• The SOAPHeader -- optional
Accessing Elements of a Message

1. Accessing the parts of the message through the

structure of the message.
– getSOAPPart method of message to retrieve it:
SOAPPart soapPart = message.getSOAPPart();
– getEnvelope method of soapPart to retrieve the SOAPEnvelope
object that it contains.
SOAPEnvelope envelope = soapPart.getEnvelope();
– getHeader and
– getBody methods of envelope
• to retrieve its empty SOAPHeader and SOAPBody objects.
SOAPHeader header = envelope.getHeader();
SOAPBody body = envelope.getBody();
Accessing Elements of a Message
2. Accessing the parts of the message by retrieving
the message header and body directly, without
retrieving the SOAPPart or SOAPEnvelope.
– getSOAPHeader and getSOAPBody methods of
SOAPHeader header = message.getSOAPHeader();
SOAPBody body = message.getSOAPBody();
• Because all SOAPElement objects including
SOAPHeader objects, are derived from the Node
interface, use method Node.detachNode to delete
Adding Content to the Body

• Create one or more SOAPBodyElement objects to hold the content.

• Add subelements to the SOAPBodyElement objects by using the
addChildElement method.
• For each element or child element, add content by using the
addTextNode method.
• Needed to create an associated Name object so that it is uniquely
– using SOAPEnvelope methods  use the envelope variable from the
earlier code fragment to create the Name object for the new element.
– use SOAPFactory methods, which are useful if there is no access to
the SOAPEnvelope.
Adding Content to the Body (Cntd)

• Name objects associated with SOAPBodyElement or

SOAPHeaderElement objects must be fully qualified;
– that is, they must be created with a local name, a prefix for the
namespace being used, and a URI for the namespace.

• Specifying a namespace for an element makes clear which

one is meant if more than one element has the same local
• The following code fragment retrieves the SOAPBody
object body from message,
• uses a SOAPFactory to create a Name object for the
element to be added, and adds a new SOAPBodyElement
object to body.

SOAPBody body = message.getSOAPBody();

SOAPFactory soapFactory = SOAPFactory.newInstance();
Name bodyName = soapFactory.createName("GetLastTradePrice",
"m", "");
SOAPBodyElement bodyElement =
• Assuming that a quote for the stock of Sun Microsystems, Inc.
is looked for

• Create a child element for the symbol using the

addChildElement method.
• Give it the stock symbol using the addTextNode method.
• The Name object for the new SOAPElement object symbol is
initialized with only a local name because child elements
inherit the prefix and URI from the parent element.
Name name = soapFactory.createName("symbol");
SOAPElement symbol =
• SAAJ API builds the appropriate XML constructs automatically when you
call methods such as addBodyElement, addChildElement, and

• Do not call addTextNode on a SOAPHeader or SOAPBody object

because they contain elements and not text.

<m:GetLastTradePrice xmlns:m="">
• SAAJ code:
SOAPMessage message = messageFactory.createMessage();
SOAPHeader header = message.getSOAPHeader();
SOAPBody body = message.getSOAPBody();

• XML it produces:

• Adding content to the body.

– the SAAJ code:
Name bodyName = soapFactory.createName("GetLastTradePrice",
"m", "");
SOAPBodyElement bodyElement = body.addBodyElement(bodyName);

– The XML it produced:

• SAAJ code:
Name name = soapFactory.createName("symbol");
SOAPElement symbol = bodyElement.addChildElement(name);

• XML produced:
Adding Multiple SOAPElement Objects
• Add multiple SOAPElement objects and add text to each of them.
• create the SOAPBodyElement object purchaseLineItems, which has
a fully qualified name associated with it
– a local name,
– a namespace prefix,
– namespace
• The SAAJ code produces the following XML in the SOAP body:

Getting a SOAPConnection Object

• SAAJ API -- reading and writing messages.

• To send a message, a SAAJ client can use a SOAPConnection object.

• A SOAPConnection object is a point-to-point connection, meaning that

it goes directly from the sender to the destination (usually a URL) that
the sender specifies.
– obtain a SOAPConnectionFactory object that you can use to create your
connection –
– get an instance of this implementation using the following line of code.

SOAPConnectionFactory soapConnectionFactory =
– use soapConnectionFactory to create a SOAPConnection object.
SOAPConnection connection =

– use connection to send the messages.

Sending a Message

• A SAAJ client calls the SOAPConnection method call on a

SOAPConnection object to send a message.

• Two arguments:
– the message being sent and
– the destination to which the message should go.
• e.g. going to the stock quote service indicated by the URL object
endpoint. endpoint = new URL(
SOAPMessage response =, endpoint);

• close a connection as soon as it finished sending the message

Getting the Content of a Message
• Use the Message object to get the SOAPBody object,
– Alternative: access the SOAPBody object through the SOAPPart and
SOAPEnvelope objects.
• Access the SOAPBody object’s SOAPBodyElement object,
• Get the content added with the method SOAPElement.addText-Node,
– call the method Node.getValue
• returns the value of the immediate child of the element that calls the method.
• getValue method -- called on bodyElement, the element on which the
addTextNode method was called.
• Accessing bodyElement-- call the getChildElements method on
– returns a java.util.Iterator object that contains all the child elements
identified by the Name object bodyName.
• More than one element had the name bodyName,
– use awhile loop using the Iterator.hasNext method \

while (iterator.hasNext()) {
SOAPBodyElement bodyElement =
String lastPrice = bodyElement.getValue();
System.out.print("The last price for SUNW is ");
Adding Content to the Header

• Create a SOAPHeaderElement object.

– Needs an associated Name object
• create using the message’s SOAPEnvelope object or a SOAPFactory object.
• Example:
– add a conformance claim header to the message to state that the
message conforms to the WS-I Basic Profile.
- retrieve the SOAPHeader object from message and add a new
SOAPHeaderElement object to it.
SOAPHeader header = message.getSOAPHeader();
Name headerName = soapFactory.createName("Claim",
"wsi", "");
SOAPHeaderElement headerElement =
"conformsTo"), "");
• the XML header:
<wsi:Claim conformsTo=""

• Add content to headerElement.


• SOAPHeader object header that contains a SOAPHeaderElement

object whose content is "order“ os created.
Adding Content to the SOAPPart Object
• SAAJ provides add the content in a file directly to the SOAPPart
– use a javax.xml.transform.Source object from JAXP (the Java API for XML
• Three types of Source objects:
– SAXSource: holds content along with the instructions for transforming the
content into an XML document
– DOMSource: same as above
– StreamSource object holds an XML document in text form.
• Uses the JAXP API to build a DOMSource object that is passed to the
SOAPPart.setContent method.
• builder parses the content file to produce a Document object.
DocumentBuilderFactory dbFactory =
DocumentBuilder builder = dbFactory.newDocumentBuilder();
Document document =
DOMSource domSource = new DOMSource(document);
• the appropriate header for the SOAPHeader object.
SOAPPart soapPart = message.getSOAPPart();
• The XML file used to set the content of the SOAPPart object
must include Envelope and Body elements:
Adding a Document to the SOAP Body
• a DOM document can be added directly to the body of the message.
• there is no need to create a javax.xml.transform.Source object.
• Parse the document then add it directly to the message body:

SOAPBody body = message.getSOAPBody();

SOAPBodyElement docElement = body.addDocument(document);