<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">

 <description>
  This web application context contains Spring-WS beans. The beans
  defined in this context are automatically detected by Spring-WS,
  similar to the way Controllers are picked up in Spring Web MVC.
 </description>

 <bean
  class="org.springframework.ws.server.endpoint.mapping.PayloadRootAnnotationMethodEndpointMapping">
  <description>
   Detects @PayloadRoot annotations on @Endpoint bean methods.
   The MarshallingAirlineEndpoint has such annotations. It uses
   two interceptors: one that logs the message payload, and the
   other validates it accoring to the 'airline.xsd' schema
   file.
  </description>
 </bean>
 <bean id="echo"
  class="org.springframework.ws.wsdl.wsdl11.DynamicWsdl11Definition">
  <description>
   This bean definition represents a WSDL definition that is
   generated at runtime, based on the builder defined below. It
   can be retrieved by going to /echo/echo.wsdl (i.e. the bean
   name corresponds to the filename).
  </description>
  <property name="builder">
   <description>
    The builder creates a WSDL from the 'echo.xsd' schema.
    It detects all elements that ends with 'Request', finds
    corresponding 'Response' messages, and creates an
    operation based on that. All operations are put in a
    portType with name 'Echo', and binding and service are
    created.
   </description>
   <bean
    class="org.springframework.ws.wsdl.wsdl11.builder.XsdBasedSoap11Wsdl4jDefinitionBuilder">
    <property name="schema" value="/WEB-INF/echo.xsd" />
    <property name="portTypeName" value="Echo" />
    <property name="locationUri"
     value="http://localhost:8080/echoweb/services" />
   </bean>
  </property>
 </bean>
 <bean id="echoEndpoint" class="com.vanad.EchoEndpoint">
  <description>This endpoint handles echo requests.</description>
  <property name="echoService" ref="echoService" />
 </bean>
 <bean id="echoService" class="com.vanad.EchoServiceImpl">
  <description>This bean is our "business" service.</description>
 </bean>

 <bean id="payloadLoggingInterceptor"
  class="org.springframework.ws.server.endpoint.interceptor.PayloadLoggingInterceptor">
 </bean>

 <bean id="soapEnvelopeLoggingInterceptor"
  class="org.springframework.ws.soap.server.endpoint.interceptor.SoapEnvelopeLoggingInterceptor">
 </bean>
 <bean
  class="org.springframework.ws.server.endpoint.adapter.GenericMarshallingMethodEndpointAdapter">
  <constructor-arg ref="marshaller" />
 </bean>
 <bean id="marshaller"
  class="org.springframework.oxm.jaxb.Jaxb2Marshaller">
  <property name="contextPath" value="com.vanad.schema" />
 </bean>
</beans>

The process involves five steps:

1. Creating a SOAP connection
2. Creating a SOAP message
3. Populating the message
4. Sending the message
5. 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.