You are on page 1of 32

ELG5191

Design of Distributed System Software

Chapter8

SOAP with Attachments API


forJava
Introduction

• SOAP with Attachments API for Java (SAAJ)


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

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

• 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

• SAAJ specifies
– messages and
– connections
SAAJ

• 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.
SAAJ

• Connections
– SOAP messages are sent and received over a
connection.
– 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
response).
SAAJ

• 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


content;
– if the content of a message is not in XML
format, it must occur in an attachment
part.
SAAJ and DOM
• 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 =
SOAPConnectionFactory.newInstance();
SOAPConnection connection = factory.createConnection();
. . .// create a request message and give it content
java.net.URL endpoint =
new URL("http://fabulous.com/gizmo/order");
SOAPMessage response = connection.call(request, 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


newInstance
• method for MessageFactory is static, so you invoke it by calling
MessageFactory.
• 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
SOAPMessage:
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
header.
header.detachNode();
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
identified.
– 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
name.
• 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", "http://wombat.ztrade.com");
SOAPBodyElement bodyElement =
body.addBodyElement(bodyName);
• 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 =
bodyElement.addChildElement(name);
symbol.addTextNode("SUNW");
• SAAJ API builds the appropriate XML constructs automatically when you
call methods such as addBodyElement, addChildElement, and
addTextNode.

• Do not call addTextNode on a SOAPHeader or SOAPBody object


because they contain elements and not text.

<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<m:GetLastTradePrice xmlns:m="http://wombat.ztrade.com">
<symbol>SUNW</symbol>
</m:GetLastTradePrice>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
• SAAJ code:
SOAPMessage message = messageFactory.createMessage();
SOAPHeader header = message.getSOAPHeader();
SOAPBody body = message.getSOAPBody();

• XML it produces:
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
...
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

• Adding content to the body.


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

– The XML it produced:


<m:GetLastTradePrice
xmlns:m="http://wombat.ztrade.com">
....
</m:GetLastTradePrice>
• SAAJ code:
Name name = soapFactory.createName("symbol");
SOAPElement symbol = bodyElement.addChildElement(name);
symbol.addTextNode("SUNW");

• XML produced:
<symbol>SUNW</symbol>
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:

<PO:PurchaseLineItems
xmlns:PO="http://sonata.fruitsgalore.com">
<Order>
<Product>Apple</Product>
<Price>1.56</Price>
</Order>
<Order>
<Product>Peach</Product>
<Price>1.48</Price>
</Order>
</PO:PurchaseLineItems>
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 =
SOAPConnectionFactory.newInstance();
– use soapConnectionFactory to create a SOAPConnection object.
SOAPConnection connection =
soapConnectionFactory.createConnection();

– 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.
java.net.URL endpoint = new URL(
"http://wombat.ztrade.com/quotes");
SOAPMessage response = connection.call(message, endpoint);

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

connection.close();
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
soapBody.
– 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 =
(SOAPBodyElement)iterator.next();
String lastPrice = bodyElement.getValue();
System.out.print("The last price for SUNW is ");
System.out.println(lastPrice);
}
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.
Procedure:
- retrieve the SOAPHeader object from message and add a new
SOAPHeaderElement object to it.
SOAPHeader header = message.getSOAPHeader();
Name headerName = soapFactory.createName("Claim",
"wsi", "http://ws-i.org/schemas/conformanceClaim/");
SOAPHeaderElement headerElement =
header.addHeaderElement(headerName);
headerElement.addAttribute(soapFactory.createName(
"conformsTo"), "http://ws-i.org/profiles/basic1.0/");
• the XML header:
<SOAP-ENV:Header>
<wsi:Claim conformsTo="http://ws-i.org/profiles/basic1.0/"
xmlns:wsi="http://ws-i.org/schemas/conformanceClaim/"/>
</SOAP-ENV:Header>

• Add content to headerElement.

headerElement.addTextNode("order");

• 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
object.
– use a javax.xml.transform.Source object from JAXP (the Java API for XML
Processing).
• 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 =
DocumentBuilderFactory.newInstance();
dbFactory.setNamespaceAware(true);
DocumentBuilder builder = dbFactory.newDocumentBuilder();
Document document =
builder.parse("file:///music/order/soap.xml");
DOMSource domSource = new DOMSource(document);
• the appropriate header for the SOAPHeader object.
SOAPPart soapPart = message.getSOAPPart();
soapPart.setContent(domSource);
• The XML file used to set the content of the SOAPPart object
must include Envelope and Body elements:
<SOAP-ENV:Envelope
xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
...
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
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);