Main Page

Previous Section Next Section


SOAP with Attachments API for Java (SAAJ) is defined to enable applications to take advantage of the SOAP protocol. It defines a Java API for producing, consuming, and manipulating SOAP messages that conform to the SOAP 1.1 specification and SOAP with Attachments note. SAAJ was created as part of the Java API for XML messaging (JAXM) under JSR-67 but was refactored into its own specification, because all the other JAX APIs used it. It made sense to have this common API stand on its own. Let us now take a closer look at SAAJ.

SAAJ provides a level of abstraction that insulates developers from low-level manipulation of angle brackets. Developers create and work with Java classes in the javax.xml.soap package that model different XML elements in a SOAP message and the semantics of connecting and sending SOAP messages.

The API relevant to modeling the SOAP message is shown in Figure 4.7 and explained in Table 4.1.

Table 4.1: The Object Representation of a SOAP Message in SAAJ


Models the attachment in a SOAP message.


An object that stores a MIME header name and its value.


A container for MimeHeader objects, which represent the MIME headers present in a MIME part of a message.


The base interface that represents an XML element. Though it is analogous to the Node in the W3C DOM discussed in Chapter 9, it is not the same.


Models the body from a SOAP message.


Represents the contents in a SOAPBody object.


Subclasses Node to provide the base functionality for all classes that represent SOAP objects defined in the SOAP specification.


Models the envelope in a SOAP message.


Models a fault and is contained in a SOAPBody object.


A representation of the contents in a SOAPFault object.


Models the header element of the SOAP message


Models individual header elements in a SOAPHeader.


The root class for all SOAP messages.


The container for the SOAP-specific portion of a SOAPMessage object.

Click To expand
Figure 4.7: The SAAJ object model

Each part of the SOAP message discussed in this chapter is modeled in SAAJ as a Java class or interface developers can work with in their code. Though Figure 4.7 is self-explanatory, there are two other classes in SAAJ are important. Like the rest of the API that abstracts the SOAP message, these classes abstract the semantics relating to a request-response-based transmission of the message:

To understand how SAAJ works, let us put everything together with an example of this API in action. The BillPay service exposes a Java method with the following syntax:

PaymentConfirmation schedulePayment(Date date, String nickName, doubleamount);

Listing 4.6 shows the SOAP request this Web service expects. We will put aside the part about how the service is implemented until Chapter 11. Listing 4.7 shows the SAAJ code, and Listing 4.8 shows the SOAP response that the service returns. The client code takes the following sequence:

  1. Instantiate the MessageFactory.

  2. Create an empty SOAPMessage from the factory.

  3. Access the SOAPEnvelope from the message.

  4. Access the SOAPBody from the envelope.

  5. Create the elements in the body and save the changes to the message.

  6. Create a SOAPConnection object from a SOAPConnectionFactory.

  7. Send the SOAPMessage to the endpoint, using the connection.

Listing 4.6: The SOAP request message
Start example
<?xml version="1.0" encoding="UTF-8"?>
    <env:Envelope xmlns:env=""
            <Date_1 xsi:type="xsd:dateTime">2002-10-05T04:49:26.769Z</Date_1>
            <String_2 xsi:type="xsd:string">my account at sprint</String_2>
            <double_3 xsi:type="xsd:double">190.0</double_3>
End example
Listing 4.7: A SAAJ client for constructing and sending a SOAP message
Start example
import javax.xml.soap.*;
import java.util.Iterator;
import java.util.Date;
import java.text.SimpleDateFormat;
import javax.xml.messaging.URLEndpoint;

public class SAAJClient{
/** Class to demonstrate how to send a soap message synchronously with SAAJ API. */
   public static void main(String args[]) throws Exception {
       String url = "";
       if (args.length > 0)
           url = args[0];

// Construct a default SOAP message factory.
        MessageFactory mfactory = MessageFactory.newInstance();
// Create an empty message
        SOAPMessage message = mfactory.createMessage();
        SOAPPart soap = message.getSOAPPart();
// Access the envelope
        SOAPEnvelope envelope = soap.getEnvelope();
                                     "" );
        envelope.addNamespaceDeclaration("xmlns:ns0","" );
// Access the body
       SOAPBody body = envelope.getBody();
       Name name = envelope.createName("schedulePayment", "ns0",
       SOAPBodyElement element = body.addBodyElement(name);
// create a name for the attribute name that can be reused
       Name xsitype = envelope.createName("xsi:type");
// create the Date_1 element
       Name dateelement = envelope.createName("Date_1");
       SOAPElement date = element.addChildElement(dateelement);
    date.addAttribute(xsitype," xsd:dateTime");
// Format the Java Date object in the syntax that is compliant with the XML schema
   SimpleDateFormat dateFormatter
                             new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'");
       String xmldate=dateFormatter.format(new Date()).toString();
// create the String_2 element
      Name strelement = envelope.createName("String_2");
      SOAPElement str = element.addChildElement(strelement);
      str.addAttribute(xsitype," xsd:string");
      str.addTextNode("my account at string");
// create the double_3 element
   name dblelement = envelope.createName("double_3");
       SOAPElement dbl = element.addChildElement(dblelement);
    dbl.addAttribute(xsitype," xsd:double");
// save changes to the message
 // Construct a default SOAP connection factory.
        SOAPConnectionFactory factory = SOAPConnectionFactory.newInstance();
 // Get SOAP connection.
        SOAPConnection connection = factory.createConnection();
 // Construct endpoint object.
        URLEndpoint endpoint = new URLEndpoint(url);
// Send SOAP message.
        SOAPMessage response =, endpoint);
// process the return message
        SOAPPart sp = response.getSOAPPart();
        SOAPEnvelope se = sp.getEnvelope();
        SOAPBody sb = se.getBody();
        Iterator it = sb.getChildElements();
        while (it.hasNext()) {
            SOAPBodyElement bodyElement = (SOAPBodyElement);
            System.out.println(bodyElement.getElementName().getQualifiedName() + "
                               namepace uri="+bodyElement.getElementName().getURI());
            Iterator it2 = bodyElement.getChildElements();
            while (it2.hasNext()) {
                SOAPElement element2 = (SOAPElement);
                System.out.print(element2.getElementName().getQualifiedName() +" = ");
 //Debug method, Print response to the std output
        System.out.println("\n\n\n Dumping complete message \n\n---------------\n\n");
 // close the connection

End example
Listing 4.8: The SOAP response from the service
Start example
<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env=""
            <result href="#ID1"/>
        <ns0:PaymentConfirmation id="ID1" xsi:type="ns0:PaymentConfirmation">
            <confirmationNum xsi:type="xsd:int">81263767</confirmationNum>
            <payee xsi:type="xsd:string">Sprint PCS</payee>
            <amt xsi:type="xsd:double">190.0</amt>
End example

Though we have seen how a SOAP request and response can be constructed and sent using SAAJ, the preceding example was meant more as an insight into the workings of SAAJ. We don't envision direct use of this API by developers, because it is unlikely visual inspection of a SOAP request would be necessary. Other APIs, such as JAXM and JAX-RPC, abstract away this usage with higher-level constructs and with tools to interpret the SOAP service descriptions in a WSDL file. SAAJ is more likely to form the underpinnings of these high-level constructs in different vendor implementations. We will talk more about SAAJ and this type of request-response communication in Chapter 11.

Previous Section Next Section

JavaScript Editor Java Tutorials Free JavaScript Editor