Back to Web Services Resources and Tutorials

The SOAP with Attachments API for Java, or SAAJ ("sage"), was developed to facilitate working with attachments in SOAP messages; however, it is generally useful and can be used in place of JAX-RPC to process any SOAP message. Since there is a thorough treatment of this topic in the J2EE Tutorial, Chapter 9 (see Resources), this tutorial will gloss over the basics and will instead cover material specific to the example web services created in this tutorial.

In your classpath you will need the saaj-api.jar and saaj-impl.jar files, both of which can be found in the lib directory of the Sun Application Server.

If you examined the SOAP request expected by the tutorial web services, you would have seen something similar to the following document:

  <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" 
                xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" 
                xmlns:ns0="http://example.com/schema/tutorial">
    <env:Body>
      <ns0:PingRequest>
        <requestParam>Ping</requestParam>
      </ns0:PingRequest>
    </env:Body>
  </env:Envelope>

Simple Web Service, no Attachments and no WS-Security:

An example client for this section can be found at SAAJClient.java.

We use the MessageFactory class to create new SOAPMessages. Note that an empty header is always included in a new default SOAPMessage. We aren't using headers for the simple version of our tutorial web service, so the first thing we do is delete the header:

SOAPHeader soapHeader = soapEnvelope.getHeader();
soapHeader.detachNode();

Name bodyName = soapFactory.createName("PingRequest", 
                                       "tutorial", 
                                       "http://example.com/schema/tutorial");
SOAPBodyElement bodyElement = body.addBodyElement(bodyName);
Name paramName = soapFactory.createName("requestParam");
SOAPElement requestParam = bodyElement.addChildElement(paramName);
requestParam.addTextNode(args[1]);

Having constructed our document, we can use the SOAPMessage.writeTo() method to output the document to stdout. For the example code here, with a ping request parameter of "Ping", we would get a document like this:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Body>
    <tutorial:PingRequest xmlns:tutorial="http://example.com/schema/tutorial">
      <requestParam>Ping</requestParam>
    </tutorial:PingRequest>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The final step is to create a SOAPConnection using the web service endpoint URL, make the call, and get the response SOAPMessage:

SOAPConnectionFactory soapConnFactory = SOAPConnectionFactory.newInstance();
SOAPConnection soapConn = soapConnFactory.createConnection();
SOAPMessage responseMsg = soapConn.call(msg, args[0]);

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" 
              xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
              xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" 
              xmlns:ns0="http://example.com/schema/tutorial">
  <env:Body>
    <ns0:PingResponse>
      <responseParam>This is the response to request 'Ping'</responseParam>
    </ns0:PingResponse>
  </env:Body>
</env:Envelope>

Specific command lines for each of the three example web services in this tutorial follow, with the assumption of host = "localhost" and port 8080, and that %CP% (as a Windows example) refers to the saaj-api.jar and saaj-impl.jar files:

• JBoss 3.2.7

  java -cp %CP%;. SAAJClient http://localhost:8080/jboss-net/services/TutorialService_Port Ping

• JBoss 4.0.3

  java -cp %CP%;. SAAJClient http://localhost:8080/tutorial/ping Ping

• Sun Application Server:

  java -cp %CP%;. SAAJClient http://localhost:8080/tutorial/ping Ping

Back to Top
Back to Web Services Resources and Tutorials