SAAJ

.

一、SAAJ简介

SAAJ(SOAP with Attachments API for Java)contains APIs for creating and populating SOAP messages which might or might not contain attachments. It also
contains APIs for sending point to point, non-provider-based, request and response SOAP messages.

SOAP message is made of SOAP Envelope and zero or more attachments. The SOAP Envelope is then made of SOAP Header and SOAP Body. SOAP attachment allows the 

SOAP message to contain not only the XML data but also non-XML data such as JPG file. And it uses the MIME multipart as container for these non-XML data.

The SAAJ API provides the SOAPMessage class to represent a SOAP message, the SOAPPart class to represent the SOAP part, the SOAPEnvelope interface to represent the SOAP envelope, and so on. 

When you create a new SOAPMessage object, it will automatically have the parts that are required to be in a SOAP message. In other words, a new SOAPMessage 

object has a SOAPPart object that contains a SOAPEnvelope object. The SOAPEnvelope object in turn automatically contains an empty SOAPHeader object followed by an empty SOAPBody object. If you do not need the SOAPHeader object, 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. The SOAPHeader object may contain one or more headers with information about the sending and receiving parties. The SOAPBody object, which always follows the SOAPHeader object if there is one, provides a simple way to send information intended for the ultimate recipient. For example, if there is a SOAPFault object, it must be in the SOAPBody object.

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 a binary file, your
message must have an attachment part for it. Note that an attachment part can contain any kind of content, so it can contain data in XML format as well.

The SAAJ API provides the AttachmentPart class to represent the attachment part of a SOAP message. A SOAPMessage object automatically has a SOAPPart object 

and its required subelements, but because AttachmentPart objects are optional, you have to create and add them yourself.

javax.xml.soap.SOAPMessage is a Java technology abstraction for a SOAP 1.1 message. Contains EXACTLY ONE SOAPPart and ZERO OR MORE AttachmentParts. 

public abstract class SOAPMessage {
public abstract SOAPPart getSOAPPart();
public abstract Iterator getAttachments();
public abstract Iterator getAttachments(MimeHeaders headers);
…
}

javax.xml.soap.SOAPPart is the first part of a multi-part message when there are attachments. 

public abstract class SOAPPart implements org.w3c.dom.Document {
public abstract SOAPEnvelope getEnvelope() throws SOAPException;
…
}

javax.xml.soap.AttachmentPart can contain any data (for example: JPEG images, XML business documents, etc.) If a SOAPMessage object has one or more attachments, each AttachmentPart object must have 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 are optional but can be useful when there are multiple attachments. When a SOAPMessage object has one or more AttachmentPart objects, its SOAPPart object may or may not contain message content.

二、使用步骤

Steps of SAAJ Programming

（1）Creating a message (SOAPMessage)
Use MessageFactory as a factory of messages. SOAPMessage object has the following:

SOAPPart object

SOAPEnvelope object

empty SOAPHeader object

empty SOAPBody object

Example:
MessageFactory factory = MessageFactory.newInstance();
SOAPMessage message = factory.createMessage();

Result:

（2）Accessing elements of a message

Approach 1: from SOAPEnvelope object:

SOAPPart soapPart = message.getSOAPPart();
SOAPEnvelope envelope = soapPart.getEnvelope();
SOAPHeader header = envelope.getHeader();
SOAPBody body = envelope.getBody();

Approach 2: from SOAPMessage object:

SOAPHeader header = message.getSOAPHeader();
SOAPBody body = message.getSOAPBody();

（3）Adding contents to the body

Example:

SOAPBody body = message.getSOAPBody();
SOAPFactory soapFactory = SOAPFactory.newInstance();
Name bodyName = soapFactory.createName(“GetLastTradePrice”,
“m”, “http://wombat.ztrade.com“);
SOAPBodyElement bodyElement = body.addBodyElement(bodyName);

Will produce following XML:

…

Example:

Name name = soapFactory.createName(“symbol”);
SOAPElement symbol = bodyElement.addChildElement(name);
symbol.addTextNode(“SUNW”);

Generates XML fragment like following:

SUNW

（4）Getting a SOAPConnection object

SOAPConnectionFactory soapConnectionFactory = SOAPConnectionFactory.newInstance();
SOAPConnection connection = soapConnectionFactory.createConnection();

All SOAP messages are sent and received over a connection. With the SAAJ API, the connection is represented by a SOAPConnection object, which goes from the

sender directly to its destination. This kind of connection is called a point-to-point connection because it goes from one endpoint to another endpoint.

Messages sent using the SAAJ API are called request-response messages. They are sent over a SOAPConnection object with the method call, which sends a message

(a request) and then blocks until it receives the reply (a response).

（5）Sending a message

// Create an endpint point which is either URL or String type
java.net.URL endpoint = new URL(“http://wombat.ztrade.com/quotes“);

// Send a SOAPMessage (request) and then wait for SOAPMessage (response)
SOAPMessage response = connection.call(message, endpoint);

A SAAJ client calls the SOAPConnection method call on a SOAPConnection object to send a message. The call method takes two arguments, the message being sent

and the destination to which the message should go. This message is going to the stock quote service indicated by the URL object endpoint.

（6）Getting the content of a message

SOAPBody soapBody = response.getSOAPBody();
java.util.Iterator iterator = soapBody.getChildElements(bodyName);
SOAPBodyElement bodyElement = (SOAPBodyElement)iterator.next();
String lastPrice = bodyElement.getValue();

System.out.print(“The last price for SUNW is “);
System.out.println(lastPrice);

In order to access bodyElement, you need to call the method getChildElements on soapBody. Passing bodyName to getChildElements returns a java.util.Iterator

object that contains all of the child elements identified by the Name object bodyName. You already know that there is only one, so just calling the method

next on it will return the SOAPBodyElement you want. Note that the method Iterator.next() returns a Java Object, so it is necessary to cast the Object it

returns to a SOAPBodyElement object before assigning it to the variable bodyElement.

三、添加header和内容
Adding content to SOAPHeader

To add content to the header, you need to create a SOAPHeaderElement object. As with all new elements, it must have an associated Name object, which you can

create using the message’s SOAPEnvelope object or a SOAPFactory object. For example, suppose you want to add a conformance claim header to the message to

state that your message conforms to the WS-I Basic Profile. The following code fragment retrieves the SOAPHeader object from message and adds a new

SOAPHeaderElement object to it. This SOAPHeaderElement object contains the correct qualified name and attribute for a WS-I conformance claim header:

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/“);

At this point, header contains the SOAPHeaderElement object headerElement identified by the Name object headerName. Note that the addHeaderElement method

both creates headerElement and adds it to header.
XML fragment generated: