One of the core interfaces of Spring Web Services is the WebServiceMessage. This interface represents a protocol-agnostic XML message. The interface contains methods that provide access to the payload of the message, in the form of a javax.xml.transform.Source or a javax.xml.transform.Result. Source and Result are tagging interfaces that represent an abstraction over XML input and output. Concrete implementations wrap various XML representations, as indicated in the following table.

In addition to reading from and writing to the payload, a Web service message can write itself to an output stream.

The SoapMessage is a subclass of WebServiceMessage. It contains SOAP-specific methods, such as getting SOAP Headers, SOAP Faults, etc. Generally, your code should not be dependent on SoapMessage, because the content of the SOAP Body (the payload of the message) can be obtained via getPayloadSource() and getPayloadResult() in the WebServiceMessage. Only when it is necessary to perform SOAP-specific actions, such as adding a header, getting an attachment, etc., should you need to cast WebServiceMessage to SoapMessage.

Concrete message implementations are created by a WebServiceMessageFactory. This factory can create an empty message, or read a message based on an input stream. There are two concrete implementations of WebServiceMessageFactory; one is based on SAAJ, the SOAP with Attachments API for Java, the other based on Axis 2's AXIOM, the AXis Object Model.

SaajSoapMessageFactory

The SaajSoapMessageFactory uses the SOAP with Attachments API for Java to create SoapMessage implementations. SAAJ is part of J2EE 1.4, so it should be supported under most modern application servers. Here is an overview of the SAAJ versions supplied by common application servers:

Application Server	SAAJ Version
BEA WebLogic 8	1.1
BEA WebLogic 9	1.1/1.2[1]
IBM WebSphere 6	1.2
SUN Glassfish 1	1.3
[1] Weblogic 9 has a known bug in the SAAJ 1.2 implementation: it implement all the 1.2 interfaces, but throws a UnsupportedOperationException when called. Spring Web Services has a workaround: it uses SAAJ 1.1 when operating on WebLogic 9.

Additionally, Java SE 6 includes SAAJ 1.3. You wire up a SaajSoapMessageFactory like so:

<bean id="messageFactory" class="org.springframework.ws.soap.saaj.SaajSoapMessageFactory" />

	Note
	SAAJ is based on DOM, the Document Object Model. This means that all SOAP messages are stored in memory. For larger SOAP messages, this may not be very performant. In that case, the AxiomSoapMessageFactory might be more applicable.

<bean id="messageFactory" class="org.springframework.ws.soap.axiom.AxiomSoapMessageFactory">
    <property name="payloadCaching" value="true"/>
</bean>

SOAP 1.1 or 1.2

Both the SaajSoapMessageFactory and the AxiomSoapMessageFactory have a soapVersion property, where you can inject a SoapVersion constant. By default, the version is 1.1, but you can set it to 1.2 like so:

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:util="http://www.springframework.org/schema/util"
       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
       http://www.springframework.org/schema/util
       http://www.springframework.org/schema/util/spring-util-2.0.xsd">

    <bean id="messageFactory" class="org.springframework.ws.soap.saaj.SaajSoapMessageFactory">
        <property name="soapVersion">
            <util:constant static-field="org.springframework.ws.soap.SoapVersion.SOAP_12"/>
        </property>
    </bean>

</beans>

In the example above, we define a SaajSoapMessageFactory that only accepts SOAP 1.2 messages.

Caution

Even though both versions of SOAP are quite similar in format, the 1.2 version is not backwards compatible with 1.1 because it uses a different XML namespace. Other major differences between SOAP 1.1 and 1.2 include the different structure of a Fault, and the fact that SOAPAction HTTP headers are effectively deprecated, thought they still work. One important thing to note with SOAP version numbers, or WS-* specification version numbers in general, is that the latest version of a specification is generally not the most popular version. For SOAP, this means that currently, the best version to use is 1.1. Version 1.2 might become more popular in the future, but currently 1.1 is the safest bet.

Typically, messages come in pairs: a request and a response. A request is created on the client-side, which is sent over some transport to the server-side, where a response is generated. This response gets sent back to the client, where it is read.

In Spring Web Services, such a conversation is contained in a MessageContext, which has properties to get request and response messages. On the client-side, the message context is created by the WebServiceTemplate. On the server-side, the message context is read from the transport-specific input stream. For example, in HTTP, it is read from the HttpServletRequest and the response is written back to the HttpServletResponse.

The XPathExpression is an abstraction over a compiled XPath expression, such as the Java 5 javax.xml.xpath.XPathExpression, or the Jaxen XPath class. To construct an expression in an application context, there is the XPathExpressionFactoryBean. Here is an example which uses this factory bean:

<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">

    <bean id="nameExpression" class="org.springframework.xml.xpath.XPathExpressionFactoryBean">
        <property name="expression" value="/Contacts/Contact/Name"/>
    </bean>

    <bean id="myEndpoint" class="sample.MyXPathClass">
        <constructor-arg ref="nameExpression"/>
    </bean>

</beans>

The expression above does not use namespaces, but we could set those using the namespaces property of the factory bean. The expression can be used in the code as follows:

package sample;

public class MyXPathClass {

    private final XPathExpression nameExpression;

    public MyXPathClass(XPathExpression nameExpression) {
        this.nameExpression = nameExpression;
    }

    public void doXPath(Document document) {
        String name = nameExpression.evaluateAsString(document.getDocumentElement());
        System.out.println("Name: " + name);
    }

}

For a more flexible approach, you can use a NodeMapper, which is similar to the RowMapper in Spring's JDBC support. The following example shows how we can use it:

package sample;

public class MyXPathClass  {

   private final XPathExpression contactExpression;

   public MyXPathClass(XPathExpression contactExpression) {
      this.contactExpression = contactExpression;
   }

   public void doXPath(Document document) {
      List contacts = contactExpression.evaluate(document,
        new NodeMapper() {
           public Object mapNode(Node node, int nodeNum) throws DOMException {
              Element contactElement = (Element) node;
              Element nameElement = (Element) contactElement.getElementsByTagName("Name").item(0);
              Element phoneElement = (Element) contactElement.getElementsByTagName("Phone").item(0);
              return new Contact(nameElement.getTextContent(), phoneElement.getTextContent());
           }
        });
      // do something with list of Contact objects
   }
}

Similar to mapping rows in Spring JDBC's RowMapper, each result node is mapped using an anonymous inner class. In this case, we create a Contact object, which we use later on.

The XPathExpression only allows you to evaluate a single, pre-compiled expression. A more flexible, though slower, alternative is the XpathTemplate. This class follows the common template pattern used throughout Spring (JdbcTemplate, JmsTemplate, etc.). Here is an example:

package sample;

public class MyXPathClass {

    private XPathOperations template = new Jaxp13XPathTemplate();

    public void doXPath(Source source) {
        String name = template.evaluateAsString("/Contacts/Contact/Name", request);
        // do something with name
    }

}