.
一、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: