The foundation of Web services lies in the sending and receiving of messages in a standard format so that all systems can understand them. Typically, that format is SOAP. A SOAP message can be generated and sent manually, but the SOAP with Attachments API for Java (SAAJ) -- an offshoot of the Java API for XML Messaging (JAXM) -- automates many of the required steps, such as creating connections or creating and sending the actual messages. This tip chronicles the creation and sending of a synchronous SOAP message.
The process involves five steps:
- Creating a SOAP connection
- Creating a SOAP message
- Populating the message
- Sending the message
- Retrieving the reply
SAAJ is available as part of the Java Web Services Developer Pack 1.2 (see Resources). This package also includes a copy of the Tomcat Web server (so you can host your own service) and sample applications.
The structure of a SOAP message
I'll start by showing you the structure of the message itself. A basic SOAP message consists of an envelope with two main parts: the header and the body. The application determines how these parts are used, but the overall message must follow a specific XML structure, such as:
Listing 1. A sample SOAP message
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/1999/XMLSchema">
<SOAP-ENV:Header />
<SOAP-ENV:Body>
<ns1:getPrice xmlns:ns1="urn:xmethods-BNPriceCheck"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<isbn xsi:type="xsd:string">0672324229</isbn>
</ns1:getPrice>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
|
Here, the header is empty and the body contains the payload, or the message to be delivered. In this case, it's a message requesting the price of a book.
Notice the structure of the message. The Envelope contains the Header and Body elements, and all three are part of the http://schemas.xmlsoap.org/soap/envelope/ namespace. The application sends the message using a SOAPConnection.
Creating the connection and the message
The first step is to create the overall class and the connection:
Listing 2. Create the connection
import javax.xml.soap.SOAPConnectionFactory;
import javax.xml.soap.SOAPConnection;
public class SOAPTip {
public static void main(String args[]) {
try {
//First create the connection
SOAPConnectionFactory soapConnFactory =
SOAPConnectionFactory.newInstance();
SOAPConnection connection =
soapConnFactory.createConnection();
//Close the connection
connection.close();
} catch(Exception e) {
System.out.println(e.getMessage());
}
}
}
|
The application can send SOAP messages directly using a SOAPConnection, which is now part of the SAAJ package, or indirectly using a messaging provider, which remains in the JAXM package. In this case, the application creates the SOAPConnection object using a factory.
A factory also creates the message itself:
Listing 3. Creating the message object
import javax.xml.soap.SOAPConnectionFactory;
import javax.xml.soap.SOAPConnection;
import javax.xml.soap.MessageFactory;
import javax.xml.soap.SOAPMessage;
import javax.xml.soap.SOAPPart;
import javax.xml.soap.SOAPEnvelope;
import javax.xml.soap.SOAPBody;
public class SOAPTip {
public static void main(String args[]) {
try {
//First create the connection
SOAPConnectionFactory soapConnFactory =
SOAPConnectionFactory.newInstance();
SOAPConnection connection =
soapConnFactory.createConnection();
//Next, create the actual message
MessageFactory messageFactory = MessageFactory.newInstance();
SOAPMessage message = messageFactory.createMessage();
//Create objects for the message parts
SOAPPart soapPart = message.getSOAPPart();
SOAPEnvelope envelope = soapPart.getEnvelope();
SOAPBody body = envelope.getBody();
//Close the connection
connection.close();
} catch(Exception e) {
System.out.println(e.getMessage());
}
}
}
|
 |
Version differences
If you've using another version of SAAJ, such as the Axis 1.2 beta SAAJ library, you may need to use addBodyElement instead of addChildElement. |
|
First, you create the message itself by using the MessageFactory. This message already contains empty versions of the basic parts, such as the envelope and header. The SOAPPart contains the envelope, and the envelope contains the body. Create references to the needed objects, such as the SOAPBody.
Next, populate the SOAPBody:
Listing 4. Populating the body
...
import javax.xml.soap.SOAPBody;
import javax.xml.soap.SOAPElement;
public class SOAPTip {
public static void main(String args[]) {
try {
...
//Create objects for the message parts
SOAPPart soapPart = message.getSOAPPart();
SOAPEnvelope envelope = soapPart.getEnvelope();
SOAPBody body = envelope.getBody();
//Populate the body
//Create the main element and namespace
SOAPElement bodyElement =
body.addChildElement(envelope.createName("getPrice" ,
"ns1",
"urn:xmethods-BNPriceCheck"));
//Add content
bodyElement.addChildElement("isbn").addTextNode("0672324229");
//Save the message
message.saveChanges();
//Check the input
System.out.println("\nREQUEST:\n");
message.writeTo(System.out);
System.out.println();
//Close the connection
connection.close();
} catch(Exception e) {
System.out.println(e.getMessage());
}
}
}
|
The body of the SOAP message is just like any other XML element in that you can add a child element, such as getPrice. You can then add the isbn element and its text node just as you might with a typical DOM element.
With SAAJ you also have the opportunity to directly create the SOAPPart of the message using an external file. For example, the file prepped.msg contains the XML structure in the first listing, and can be called in lieu of building the document manually:
Listing 5. Creating the message from an external file
...
import javax.xml.soap.SOAPElement;
import java.io.FileInputStream;
import javax.xml.transform.stream.StreamSource;
public class SOAPTip {
public static void main(String args[]) {
...
//Create objects for the message parts
SOAPPart soapPart = message.getSOAPPart();
SOAPEnvelope envelope = soapPart.getEnvelope();
SOAPBody body = envelope.getBody();
//Populate the Message
StreamSource preppedMsgSrc = new StreamSource(
new FileInputStream("prepped.msg"));
soapPart.setContent(preppedMsgSrc);
//Save the message
message.saveChanges();
...
}
}
|
The StreamSource class is typically used as part of an XSL Transformation, but here you can use it simply to obtain the FileInputStream. The result is a SOAP message that's ready to send.
Sending the message
With a synchronous message, sending the SOAP message and receiving a reply take place in a single step:
Listing 6. Sending the message
...
public class SOAPTip {
public static void main(String args[]) {
...
//Check the input
System.out.println("\nREQUEST:\n");
message.writeTo(System.out);
System.out.println();
//Send the message and get a reply
//Set the destination
String destination =
"http://services.xmethods.net:80/soap/servlet/rpcrouter";
//Send the message
SOAPMessage reply = connection.call(message, destination);
//Close the connection
connection.close();
...
}
}
|
The actual message is sent using the call() method, which takes the message itself and a destination as arguments and returns a second SOAPMessage as a reply. In earlier versions of JAXM, the destination had to be an Endpoint object or a URLEndpoint, but now it simply has to be an object. This example uses the "Book price checker" Web service hosted by XMethods, which returns the price of the book whose ISBN is listed in the request.
The call() method blocks until it receives the returned SOAPMessage.
The response
The returned SOAPMessage, reply, is a SOAP message in the same form as the message sent, and as such can be manipulated just like any other XML message. SOAP allows you to transform the reply directly using XSLT:
Listing 7. Reading the response
...
import javax.xml.transform.TransformerFactory;
import javax.xml.transform.Transformer;
import javax.xml.transform.Source;
import javax.xml.transform.stream.StreamResult;
public class SOAPTip {
public static void main(String args[]) {
try {
...
//Send the message
SOAPMessage reply = connection.call(message, destination);
//Check the output
System.out.println("\nRESPONSE:\n");
//Create the transformer
TransformerFactory transformerFactory =
TransformerFactory.newInstance();
Transformer transformer =
transformerFactory.newTransformer();
//Extract the content of the reply
Source sourceContent = reply.getSOAPPart().getContent();
//Set the output for the transformation
StreamResult result = new StreamResult(System.out);
transformer.transform(sourceContent, result);
System.out.println();
//Close the connection
connection.close();
...
}
}
|
Create the Transformer object as you would in any XSLT application. In this case, you just want to output the content, so there's no stylesheet. Here, the content itself is the entire SOAP part of the message (as opposed to the SOAP message itself, which might include attachments). You could also extract the envelope and body before processing. The result in this case is simply System.out, but can be any choice normally available to a transformation. Transform as usual.