This recipe requires the installation of the following software or tools:

An alternative way to include the Maven repositories to your Maven build is to include repository data in the POM file directly. Samples of both ways to include repositories are included under the Using Maven folder in the resource bundle of this chapter.

mvn clean package installs the required components into a local repository and creates a WAR/JAR file of the project:

[INFO] Building war: ...LiveRestaurant.war

mvn tomcat:run runs a WAR file of the project on the Tomcat plugin. mvn jetty:run runs the WAR file of the project on the Jetty plugin:

INFO] --- tomcat-maven-plugin:1.1:... LiveRestaurant ---
[INFO] Running war on http://localhost:8080/LiveRestaurant
[INFO] Creating Tomcat server configuration at

Initially, the input and output sample messages are required. In this book, there are four XML messages (placeOrderRequest.xml, placeOrderResponse, cancelOrderRequest.xml, and cancelOrderResponse.xml) and all the recipes use these message data formats for communication. Inst2xsd generates a schema file from the existing XML sample messages. Resources of this recipe are included under the Create Data Contract folder in the resource bundle of this chapter.

In this recipe, the project's name is LiveRestaurant_R-1.2 with the following Maven dependencies:

DispatcherServlet receives all the incoming requests, and based on request context, it forwards the request to the endpoint (the general form of a request URL is http://<host>:<port>/<appcontext>/<requestcontext> (here appcontext is Liverestaurant and requestcontext should start with /Dispatcher/). The requests context that ends with /OrderService go to OrderSeviceMessageReceiverEndpoint and requests that end with *.wsdl go to SimpleWsdl11Definition).

DispatcherServlet configured in web.xml is responsible for receiving all requests with a URL mapping [/Dispatcher/*].

  <servlet>
        <servlet-name>Dispatcher</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>Dispatcher</servlet-name>
        <url-pattern>/Dispatcher/*</url-pattern>
    </servlet-mapping>

DispatcherServlet plays a major role in intercepting the HTTP requests and then loads the Spring bean configuration file. By default, it detects the bean configuration file by name <servlet-name>-servlet.xml. Since we have named the DispatcherServlet as Dispatcher in web.xml file, the server looks for Dispatcher-servlet.xml as application context filename. You may configure another file, using the following context param in the web.xml:

   <context-param>
    <param-name>contextConfigLocation</param-name>
    <param-value>/WEB-INF/classes/applicationContext.xml</param-value>
  </context-param>

DispatcherServlet needs separate instances of WebServiceMessageReceiverHandlerAdapter , MessageDispatcher , and WsdlDefinitionHandlerAdapter that in this recipe are configured inside Dispatcher-servlet.xml. The DispatcherServlet, by default, delegates to controllers for handling requests, but in the configuration file, it is configured to delegate to a MessageDispatcher (WebServiceMessageReceiverHandlerAdapter). SaajSoapMessageFactory is a specific message factory for message creation in Spring-WS.

<beans ...">
    <bean class="org.springframework.ws.transport.http.WebServiceMessageReceiverHandlerAdapter">
      <property name="messageFactory">
        <bean class="org.springframework.ws.soap.saaj.SaajSoapMessageFactory"></bean>
      </property>
    </bean>
    …....

To let DispatcherServlet handle the WSDL contract, WsdlDefinitionHandlerAdapter , which is registered in the configuration file; it reads the WSDL file source using the WsdlDefinition implementation (SimpleWsdl11Definition) and writes that as the result to the HttpServletResponse .

SimpleUrlHandlerMapping is to redirect the client requests to the appropriate endpoints using the URL patterns. Here the request URL that ends with *.wsdl will be redirected to sampleServiceDefinition (that is, SimpleWsdl11Definition that uses OrderService.wsdl to generate the response), and if the request URL contains /OrderService, it will be redirected to OrderSeviceMessageReceiverEndpoint. SOAPMessageDispatcher is to dispatch a SOAP message to the registered endpoint(s) (OrderSeviceMessageReceiverEndpoint).

…....
<bean class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping">
        <property name="mappings">
           <props>
             <prop key="*.wsdl">sampleServiceDefinition</prop>
             <prop key="/OrderService">OrderServiceEndpoint</prop>
           </props>
        </property>
        <property name="defaultHandler" ref="messageDispatcher"/>
    </bean>
    <bean id="messageDispatcher" class="org.springframework.ws.soap.server.SoapMessageDispatcher"/>
  <bean id="OrderServiceEndpoint" class="com.packtpub.liverestaurant.service.endpoint.OrderSeviceMessageReceiverEndpoint"/>    
    <bean class="org.springframework.ws.transport.http.WsdlDefinitionHandlerAdapter"/>
       <bean id="sampleServiceDefinition" class="org.springframework.ws.wsdl.wsdl11.SimpleWsdl11Definition">
       <property name="wsdl" value="/WEB-INF/OrderService.wsdl"/>
    </bean>
</beans>
OrderSeviceMessageReceiverEndpoint is a very basic endpoint that get incoming message (messageContext.getRequest().getPayloadSource()) and prin it out:
….....
public class OrderSeviceMessageReceiverEndpoint implements
    WebServiceMessageReceiver {

  public OrderSeviceMessageReceiverEndpoint() {
  }
  public void receive(MessageContext messageContext) throws Exception {
    
    System.out
        .println("Inside method, OrderSeviceMethodEndpoint.receive - message content = "
            + xmlToString(messageContext.getRequest().getPayloadSource()));
  }

You can change the URL pattern to suit your requirement.

  private  String xmlToString(Source source) {
    try {
      StringWriter stringWriter = new StringWriter();
      Result result = new StreamResult(stringWriter);
      TransformerFactory factory = TransformerFactory.newInstance();
      Transformer transformer = factory.newTransformer();
      transformer.transform(source, result);
      return stringWriter.getBuffer().toString();
    } catch (TransformerConfigurationException e) {
      e.printStackTrace();
    } catch (TransformerException e) {
      e.printStackTrace();
    }
    return null;
  }

}

The Setting up a Web-Service using MessageDispatcherServlet recipe in this chapter.

In this recipe, the project's name is LiveRestaurant_R-1.3 with the following Maven dependencies:

The MessageDispatcherServlet is configured in the web configuration file web.xml:

  <servlet>
    <servlet-name>spring-ws</servlet-name>
    <servlet-class>
      org.springframework.ws.transport.http.MessageDispatcherServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>

  <servlet-mapping>
    <servlet-name>spring-ws</servlet-name>
    <url-pattern>/*</url-pattern>
  </servlet-mapping>

MessageDispatcherServlet is the central element that handles the incoming SOAP requests, with the help of other components (EndpointAdapters, EndpointMappings, EndpointExceptionResolvers, and WsdlDefinition). It combines the attributes of both DispatcherServlet and MessageDispatcher that dispatch to the appropriate endpoint. This is the standard servlet recommended to build Web-Services with Spring-WS.

Since the MessageDispatcherServlet is inherited from FrameworkServlet, it looks for a configuration file named <servlet-name>-servlet.xml in the class path (you can change the configuration filename using the context-param, contextConfigLocation settings in the web.xml, as described in the recipe Setting up a Web-Service using DispatcherServlet ). In the example, since the servlet name in the web.xml file is set to Spring-WS, the file spring-ws-servlet.xml is the Web-Services configuration file.

MessageDispatcherServlet then looks up for an endpoint mapping element in the configuration file, for the purpose of mapping the client requests to the endpoint. Here, <sws:static-wsdl sets the data contract in the WSDL format. This is the element to be configured in spring-ws-servlet.xml to set up a Web-Service:

<bean class="org.springframework.ws.server.endpoint.mapping.SimpleMethodEndpointMapping">
    <property name="endpoints">
      <ref bean="OrderServiceEndpoint"/>
    </property>
    <property name="methodPrefix" value="handle"></property>
  </bean>
  <sws:static-wsdl id="OrderService" location="/WEB-INF/orderService.wsdl"/>
  
  <bean id="OrderServiceEndpoint" class="com.packtpub.liverestaurant.service.endpoint.OrderSeviceMethodEndpoint">
  </bean>

The example uses SimpleMethodEndpointMapping that maps the client requests to MethodEnpoints. It maps the incoming request to a method that starts with the handle+root element of the message (handle+placeOrderRequest). In the endpoint class (OrderSeviceMethodEndpoint), a method with the name handleplaceOrderRequest should be defined.

In this method, the parameter source includes the incoming message and input parameters to call order service could be extracted from this parameter, then the method calls to the orderService method and wraps the outgoing message in the StringSource that is to be sent back to the client:

public class OrderSeviceMethodEndpoint {  
  OrderService orderService;
  public void setOrderService(OrderService orderService) {
    this.orderService = orderService;
  }
  public @ResponsePayload
  Source handleplaceOrderRequest(@RequestPayload Source source) throws Exception {
    //extract data from input parameter
    String fName="John";
    String lName="Smith";
    String refNumber="1234";
    return new StringSource(
        "<tns:placeOrderResponse xmlns:tns=\"http://www.packtpub.com/liverestaurant/OrderService/schema\"><tns:refNumber>"+orderService.placeOrder(fName,lName,refNumber)+"</tns:refNumber></tns:placeOrderResponse>");
  }

The endpoint mappings will be detailed in the later recipes.

The recipes Setting up a Web-Service using DispatcherServlet, Setting up a simple endpoint mapping for the Web-Service, and Setting up a contract-first Web-Service discussed in this chapter.

In this recipe, the project's name is LiveRestaurant_R-1.4 with the following Maven dependencies:

In this recipe, Apache ActiveMQ is used to set up a JMS server and to create JMS server-related objects (queue and broker are used here). Spring-WS family JARs provide a functionality to set up a Spring-WS and spring-jms and jms JARs provide the JMS functionality that the Spring-WS, over JMS, is built upon it.

DefaultMessageListenerContainer listens to destinationName (RequestQueue) for incoming messages. When a message arrives, this listener will use the message factory (messageFactory) to extract the message and use the dispatcher (messageDispatcher) to dispatch the message to the endpoint (SimplePayloadEndpoint).

In the application context, WebServiceMessageListener is a listener inside MessageListenerContainer. The message container uses connectionfactory to connect to the destination (RequestQueue):

    <bean id="connectionFactory" class="org.apache.activemq.ActiveMQConnectionFactory">
        <property name="brokerURL" value="vm://localhost?broker.persistent=false"/>
    </bean>

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

    <bean class="org.springframework.jms.listener.DefaultMessageListenerContainer">
        <property name="connectionFactory" ref="connectionFactory"/>
        <property name="destinationName" value="RequestQueue"/>
        <property name="messageListener">
            <bean class="org.springframework.ws.transport.jms.WebServiceMessageListener">
                <property name="messageFactory" ref="messageFactory"/>
                <property name="messageReceiver" ref="messageDispatcher"/>
            </bean>
        </property>
    </bean>

This listener uses message Dispatcher and messageFactory to receive incoming messages and to send outgoing SOAP messages. Inside messageDiapatcher, endpoint's mapping is included, which sets the endpoint (SimplePayloadEndpoint) and type of endpoint mapping (PayloadRootQNameEndpointMapping):

    <bean id="messageDispatcher" class="org.springframework.ws.soap.server.SoapMessageDispatcher">
        <property name="endpointMappings">
            <bean class="org.springframework.ws.server.endpoint.mapping.PayloadRootQNameEndpointMapping">
                <property name="defaultEndpoint">
                    <bean class="com.packtpub.liverestaurant.service.endpoint.SimplePayloadEndpoint">
                    <property name="orderService">
                     <bean class="com.packtpub.liverestaurant.service.OrderServiceImpl"/>
                    </property>
                    </bean>
                </property>
            </bean>
        </property>
    </bean>

The invoke method from the endpoint (SimplePayloadEndpoint) will be called when a request comes to the server, and the response will be returned to be sent back to the client:

public class SimplePayloadEndpoint implements PayloadEndpoint {
  OrderService orderService;
  public void setOrderService(OrderService orderService) {
    this.orderService = orderService;
  }

    public Source invoke(Source request) throws Exception {
      //extract data from input parameter
    String fName="John";
    String lName="Smith";
    String refNumber="1234";
    
      return new StringSource(
    "<tns:placeOrderResponse xmlns:tns=\"http://www.packtpub.com/liverestaurant/OrderService/schema\"><tns:refNumber>"+orderService.placeOrder(fName, lName, refNumber)+"</tns:refNumber></tns:placeOrderResponse>");
    }

JmsTransportWebServiceIntegrationTest is included in the project to load the application context, set up the JMS server, and test the Web-Service. However, these details are not discussed here. The client of JMS transport will be discussed in the next chapter.

The Creating a Web-Service client on JMS transport recipe discussed in Chapter 2, Building Clients for SOAP Web-Services and the Exposing Web-Services using JMS as the underlying communication protocol recipe discussed in Chapter 10, Spring Remoting.

In this recipe, the project's name is LiveRestaurant_R-1.5 with the following Maven dependencies:

Setting up a mail server outside a system that is using JavaMail for testing purpose is difficult. Mock JavaMail addresses this issue and provides a pluggable component to the system using JavaMail. The system can use this component to send/receive e-mails against the temporary in-memory mailbox.

Messages sent to an address will be saved in an inbox. The message receiver (messageReceiver) monitors the inbox at continuous intervals and as soon as it detects a new E-mail, it reads the E-mail, extracts the message, and forwards the message to a message dispatcher (messageDispatcher). The message dispatcher will call the invoke method inside its default endpoint (SamplePayloadEndpoint), and inside the handler method (invoke), the response will be sent back to the client.

When the application context is being loaded, MailMessageReceiver starts up a mail receiver and its inbox folder (imap://[email protected]/INBOX ), that is, a temporary in-memory inbox. After loading the application context, the messageReceiver bean acts as a server monitor for the incoming messages based on a pluggable strategy (monotoringStrategy) that monitors the INBOX folder (imap://[email protected]/INBOX) for new messages on pollingInterval of 1000 ms. storeUri is the location to be monitored for the incoming messages (imap://[email protected]/INBOX) and transportUri is the mail server for sending the responses:

    <bean id="messageFactory" class="org.springframework.ws.soap.saaj.SaajSoapMessageFactory"/>
    <bean id="messagingReceiver" class="org.springframework.ws.transport.mail.MailMessageReceiver">
        <property name="messageFactory" ref="messageFactory"/>
        <property name="from" value="[email protected]"/>
        <property name="storeUri" value="imap://[email protected]/INBOX"/>
        <property name="transportUri" value="smtp://smtp.packtpubtest.com"/>
        <property name="messageReceiver" ref="messageDispatcher"/>
        <property name="session" ref="session"/>
        <property name="monitoringStrategy">
            <bean class="org.springframework.ws.transport.mail.monitor.Pop3PollingMonitoringStrategy">
                <property name="pollingInterval" value="1000"/>
            </bean>
        </property>
    </bean>

Inside messageDiapatcher, endpoint mapping is included that sets the endpoint (SimplePayloadEndpoint) and type of the endpoint mapping (PayloadRootQNameEndpointMapping):

    <bean id="messageDispatcher" class="org.springframework.ws.soap.server.SoapMessageDispatcher">
        <property name="endpointMappings">
            <bean class="org.springframework.ws.server.endpoint.mapping.PayloadRootQNameEndpointMapping">
                <property name="defaultEndpoint">
                    <bean class="com.packtpub.liverestaurant.service.endpoint.SimplePayloadEndpoint">
                    <property name="orderService">
                        <bean class="com.packtpub.liverestaurant.service.OrderServiceImpl"/>
                    </property>
                    </bean>
                </property>
            </bean>
        </property>
    </bean>

SimplePayloadEndpoint receives a request and returns a fixed dummy response using OrderService. When a request comes to the server, the invoke method will be called and the response will be returned that is to be sent back to the client:

public class SimplePayloadEndpoint implements PayloadEndpoint {
  OrderService orderService;
  public void setOrderService(OrderService orderService) {
    this.orderService = orderService;
  }

    public Source invoke(Source request) throws Exception {
      //extract data from input parameter
    String fName="John";
    String lName="Smith";
    String refNumber="1234";
    
      return new StringSource(
    "<tns:placeOrderResponse xmlns:tns=\"http://www.packtpub.com/liverestaurant/OrderService/schema\"><tns:refNumber>"+orderService.placeOrder(fName, lName, refNumber)+"</tns:refNumber></tns:placeOrderResponse>");
    }

To test this recipe, a webServiceTemplate is used. We will discuss it in the next chapter.

MailTransportWebServiceIntegrationTest is included in the project to load the application context, set up the mail server, and to test the Web-Service.

The Creating Web-Service client on E-mail transport recipe, discussed in Chapter 2, Building Clients for SOAP Web-Services.

In this recipe, the project's name is LiveRestaurant_R-1.6 with the following Maven dependencies:

In the application context, SimpleHttpFactoryBean creates a simple HTTP server (from embedded Sun's JRE 1.6) and it starts the HTTP server on initialization and stops it on destruction.

The HTTP server that has a context property sets up a Web-Service with the service class (orderServiceImpl) set as the endpoint and specifies the URL defined by the properties inside the context (localhost:3478/OrderService). This service interface is registered within the context property.

However, the service implementation is autodetected using component-scan. HttpInvokerProxyFactoryBean creates a client's proxy for a specific server URL.

  <context:annotation-config />
  <context:component-scan base-package="com.packtpub.liverestaurant.service.endpoint" />
  <bean id="httpServer" class="org.springframework.remoting.support.SimpleHttpServerFactoryBean">
    <property name="contexts">
      <util:map>
        <entry key="/OrderService">
          <bean class="org.springframework.remoting.httpinvoker.SimpleHttpInvokerServiceExporter">
            <property name="serviceInterface" value="com.packtpub.liverestaurant.service.endpoint.IOrderServiceEndPoint" />
            <property name="service" ref="orderServiceImpl" />
          </bean>
        </entry>
      </util:map>
    </property>
    <property name="port" value="3478" />
    <property name="hostname" value="localhost" />
  </bean>

IOrderServiceEndPointImpl and IOrderServiceEndPoint are simple service interface and implementation classes. IOrderServiceEndPointImpl is annotated by @Service (orderServiceImpl) and is to be detected as a service implementation.

package com.packtpub.liverestaurant.service.endpoint;
public interface OrderService {
    String invoke(String request) throws Exception;
}


package com.packtpub.liverestaurant.service.endpoint;
import org.apache.log4j.Logger;
import org.springframework.stereotype.Service;
@Service("orderServiceImpl")
public class OrderServiceImpl implements OrderService {
  static Logger logger = Logger.getLogger(OrderServiceImpl.class);
   private static final String responseContent = "<tns:placeOrderResponse xmlns:tns=\"http://www.packtpub.com/liverestaurant/OrderService/schema\"><refNumber>Order Accepted!</refNumber></tns:placeOrderResponse>";

   public String invoke(String request) throws Exception {
     logger.info("invoke method request:"+request);
        return responseContent;
   
    }
}

ServerStartUp.java is used to load the application context and start up the server:

package com.packtpub.liverestaurant.server;
public class ServerStartUp {
  public static void main(String[] args) throws  IOException {
      ClassPathXmlApplicationContext appContext = new ClassPathXmlApplicationContext("/applicationContext.xml");
      System.out.println(appContext);
     char c;
        // Create a BufferedReader using System.in
        BufferedReader br = new BufferedReader(new 
                           InputStreamReader(System.in));
        System.out.println("Enter any character  to quit.");
        c = (char) br.read();
        appContext.close();
  }

In this recipe, the project's name is LiveRestaurant_R-1.7, which has the following Maven dependencies:

In the application context, the messageFactory bean is responsible for creating the incoming and outgoing SOAP messages. The messageReceiver bean acts as a server, using a connection (to XMPP server:google talk), and listens to the host on a specific service with a username and password.

    <bean id="messageFactory" class="org.springframework.ws.soap.saaj.SaajSoapMessageFactory"/>
    <bean id="connection" class="org.springframework.ws.transport.xmpp.support.XmppConnectionFactoryBean">
        <property name="host" value="talk.google.com"/>
        <property name="username" value="[email protected]"/>
        <property name="password" value="yourPassword"/>
        <property name="serviceName" value="gmail.com"/>
    </bean>

    <bean id="messagingReceiver" class="org.springframework.ws.transport.xmpp.XmppMessageReceiver">
        <property name="messageFactory" ref="messageFactory"/>
        <property name="connection" ref="connection"/>
        <property name="messageReceiver" ref="messageDispatcher"/>
    </bean>

Once the message is sent by the client, it will be forwarded to the endpoint (SamplePlayLoadEndPoint that is configured within messageDispatcher) by the message dispatcher and the response will be returned to the client:

  <bean id="messageDispatcher"
    class="org.springframework.ws.soap.server.SoapMessageDispatcher">
    <property name="endpointMappings">
     <bean class="org.springframework.ws.server.endpoint.mapping.PayloadRootQNameEndpointMapping"> 
        <property name="defaultEndpoint"> <bean class="com.packtpub.liverestaurant.service.endpoint.SamplePlayLoadEndPoint"/> 
      </property> </bean>
    </property>
  </bean>

Webservicetemplate is used here as a client; it will be discussed in the next chapter.

SamplePlayLoadEndPoint just receives a request and returns a response:

public class SamplePlayLoadEndPoint implements PayloadEndpoint {
  static Logger logger = Logger.getLogger(SamplePlayLoadEndPoint.class);
  public Source invoke(Source request) throws Exception {
      return  request;
    }

A test class is included in the project to load the application context, set up the XMPP Web-Service server, and test the Web-Service.

The Creating Web-Service client on XMPP transport recipe discussed in Chapter 2, Building Clients for SOAP Web-Services.

In this recipe, the project's name is LiveRestaurant_R-1.8, with the following Maven dependencies:

The steps of this recipe are the same as that of the recipe Simplifying the creation of a Web-Service using MessageDispatcherServlet, except the implementation of endpoint handling methods.

This annotation serves as a specialization of @Component, allowing for the implementation classes to be autodetected through classpath scanning, which is configured in the server application context file (spring-ws-servlet.xml):

   <context:component-scan base-package="com.packtpub.liverestaurant.service"/>
    <sws:annotation-driven/>

OrderEndpoint is the endPoint of this recipe and the @Endpoint annotation is also the same as @service, allowing for the implementation classes to be autodetected through classpath scanning. A request with the root element placeOrderRequest (localPart = "placeOrderRequest") and the namespace http://www.packtpub.com/liverestaurant/OrderService/schema will be forwarded to call the corresponding method (handlePlaceOrderRequest).

@Endpoint
public class OrderEndpoint {
  private static final Log logger = LogFactory.getLog(OrderEndpoint.class);
    private static final String NAMESPACE_URI = "http://www.packtpub.com/liverestaurant/OrderService/schema";
  private OrderService orderService;
    @Autowired
  public OrderEndpoint(OrderService orderService) {
    this.orderService = orderService;
  }
    @PayloadRoot(namespace = NAMESPACE_URI, localPart = "placeOrderRequest")
    @ResponsePayload
    public Source handlePancelOrderRequest(@RequestPayload Element placeOrderRequest) throws Exception {
      String refNumber=placeOrderRequest.getElementsByTagNameNS(NAMESPACE_URI, "refNumber") .item(0).getTextContent();
      String fName=placeOrderRequest.getElementsByTagNameNS(NAMESPACE_URI, "fName") .item(0).getTextContent();
      String lName=placeOrderRequest.getElementsByTagNameNS(NAMESPACE_URI, "lName") .item(0).getTextContent();
        return new StringSource(
    "<tns:placeOrderResponse xmlns:tns=\"http://www.packtpub.com/liverestaurant/OrderService/schema\"><tns:refNumber>"+orderService.placeOrder(fName,lName, refNumber)+"</tns:refNumber></tns:placeOrderResponse>");
    }
  }

Other details about annotations and how the request will be mapped to an endpoint method are contained in this chapter.

The following setting in the spring-ws-servlet.xml file causes the application to automatically generate the WSDL file from the data contract (orderService.xsd).

        <sws:dynamic-wsdl id="OrderService" portTypeName="OrderService" locationUri="http://localhost:8080/LiveRestaurant/spring-ws/OrderService"
                      targetNamespace="http://www.packtpub.com/liverestaurant/OrderService/schema">
        <sws:xsd location="/WEB-INF/orderService.xsd"/>
    </sws:dynamic-wsdl>

The recipes Setting up an endpoint by annotating the payload-root, Simplifying the creation of a Web-Service using MessageDispatcherServlet, discussed in this chapter and the Creating a Web-Service client on HTTP transport recipe, discussed in Chapter 2, Building Clients for SOAP Web-Services.

Also see the recipes discussed in Chapter 10, Spring Remoting, to find out how to set up contract-last Web-Services.

In this recipe, the project's name is LiveRestaurant_R-1.9, with the following Maven dependencies:

The steps of this recipe are the same as that of the previous recipe, Setting up a contract-first Web-Service, except that the registration of the endpoint, that is, method endpoint mapping and is configured in spring-ws-servlet.xml.

SimpleMethodEndpointMapping maps from the local name of the request payload (placeOrderRequest) to the methods of the POJO classes. Here is a sample of the request payload (note the local name of the request payload):

</tns:placeOrderRequest>
  <tns:order>
......
  </tns:order>
</tns:placeOrderRequest>

The endpoint bean is registered using the endpoints property. This property tells you that there should be a method in the endpoint class (OrderServiceEndpoint) with a name that starts with methodPrefix(handle) and ends with the request payload local name (placeOrderRequest). This increases the flexibility of the endpoint naming by using the configuration in spring-ws-servlet.xml:

  <bean class="org.springframework.ws.server.endpoint.mapping.SimpleMethodEndpointMapping">
    <property name="endpoints">
      <ref bean="OrderServiceEndpoint"/>
    </property>
    <property name="methodPrefix" value="handle"></property>
    <property name="interceptors">
      <list>
        <bean
          class="org.springframework.ws.server.endpoint.interceptor.PayloadLoggingInterceptor">
          <property name="logRequest" value="true" />
          <property name="logResponse" value="true" />
        </bean>
      </list>
    </property>
  </bean>
  <bean id="OrderServiceEndpoint" class="com.packtpub.liverestaurant.service.endpoint.OrderSeviceMethodEndpoint">
  </bean>

The endpoint method name should match the handle+request message root name (handleplaceOrderRequest). In the body of the method, we should process the request and finally return the response in the form of javax.xml.transform.Source:

public class OrderSeviceMethodEndpoint {
  private OrderService orderService;
  @Autowired
    public void setOrderService(OrderService orderService) {
    this.orderService = orderService;
  }    
  public @ResponsePayload Source handleplaceOrderRequest(@RequestPayload Source source) throws Exception {
    //extract data from input parameter
    String fName="John";
    String lName="Smith";
    String refNumber="1234";    
      return new StringSource(
    "<tns:placeOrderResponse xmlns:tns=\"http://www.packtpub.com/liverestaurant/OrderService/schema\"><tns:refNumber>"+orderService.placeOrder(fName, lName, refNumber)+"</tns:refNumber></tns:placeOrderResponse>");
  }
}

The recipes Setting up a transport-neutral WS-Addressing endpoint and Setting up an endpoint by annotating the payload-root, discussed in this chapter.

In this recipe, the project's name is LiveRestaurant_R-1.10, with the following Maven dependencies:

The steps of this recipe are the same as that of Setting up a contract-first Web-Service and here we want to describe the endpoint mapping using annotation in the endpoint class.

By including component scan and annotation-driven settings in the Spring-WS configuration file (spring-ws-servlet.xml), the Spring container will scan the entire package for endpoints, services, and dependencies to inject and autowire each other to build the Web-Service blocks. You cannot see the adapters and other handlers here, since the container smartly picks the right/default adapter, dynamically (messageDispatcher runs support method of an adapter from a list of existing adapters for the endponit, and if support method returns true, that adapter is the right adapter):

    <context:component-scan base-package="com.packtpub.liverestaurant.service"/>

    <sws:annotation-driven/>

    <sws:dynamic-wsdl id="OrderService" portTypeName="OrderService" locationUri="http://localhost:8080/LiveRestaurant/spring-ws/OrderService"
                      targetNamespace="http://www.packtpub.com/liverestaurant/OrderService/schema">
        <sws:xsd location="/WEB-INF/orderService.xsd"/>
    </sws:dynamic-wsdl>

The @Endpoint annotation of OrderSeviceAnnotationEndpoint makes it an endpoint, with PayloadRootAnnotationMethodEndpointMapping, with the exact pointers to the method-endpoint mapping with the method-level annotations:

@Endpoint
public class OrderSeviceAnnotationEndpoint {  
  private final String SERVICE_NS = "http://www.packtpub.com/liverestaurant/OrderService/schema";
  private OrderService orderService;
  @Autowired
  public OrderSeviceAnnotationEndpoint(OrderService orderService) {
    this.orderService = orderService;
  }
  @PayloadRoot(localPart = "placeOrderRequest", namespace = SERVICE_NS)
  public @ResponsePayload
  Source handlePlaceOrderRequest(@RequestPayload Source source) throws Exception {    

    //extract data from input parameter
    String fName="John";
    String lName="Smith";
    String refNumber="1234";
    
      return new StringSource(
    "<tns:placeOrderResponse xmlns:tns=\"http://www.packtpub.com/liverestaurant/OrderService/schema\"><tns:refNumber>"+orderService.placeOrder(fName, lName, refNumber)+"</tns:refNumber></tns:placeOrderResponse>");
  }
  
  @PayloadRoot(localPart = "cancelOrderRequest", namespace = SERVICE_NS)
  public @ResponsePayload
  Source handleCancelOrderRequest(@RequestPayload Source source) throws Exception {
    //extract data from input parameter
    boolean cancelled =true ;  
      return new StringSource(
          "<tns:cancelOrderResponse xmlns:tns=\"http://www.packtpub.com/liverestaurant/OrderService/schema\"><cancelled>"+(cancelled?"true":"false")+"</cancelled></tns:cancelOrderResponse>");
  }

@PayloadRoot helps the MessageDispatcher to map the request to the method, with the help of an argument annotation, @RequestPayload , which specifies the exact message payload part of the entire SOAP message as an argument into the method (it finds the method by root element of a request equal to localPart, for example, placeOrderRequest or placeCancelRequest). @RequestPayload tells the container that the argument RequestPayload is to be extracted from the SOAP message and injected to the method as an argument at runtime.

The return type annotation, @ResponsePayload, instructs MessageDispatcher that the instance of javax.xml.transform.Source is ResponsePayload. The smart Spring-WS framework detects the type of these objects at runtime and delegates to the appropriate PayloadMethodProcessor. In this case, it is SourcePayloadMethodProcessor, since the input argument and the return value are of the type javax.xml.transform.Source.

The recipes Setting up a transport-neutral WS-Addressing endpoint and Setting up a simple endpoint mapping for the Web-Service, discussed in this chapter.

In this recipe, the project's name is LiveRestaurant_R-1.11 with the following Maven dependencies:

The steps of this recipe are the same as that of Setting up an endpoint by annotating the payload-root, except for the endpoint class. So, follow the steps of the mentioned recipe and define a new endpoint with WS-Addressing standards.

Same as the previous recipe, Setting up an endpoint by annotating the payload-root, the incoming WS-Addressing SOAP messages will be forwarded to the endpoint (OrderEndpoint, which is autodetected by @Endpoint). As you can see from the output, a header is added to the SOAP envelop that WS-Addressing uses for mapping and dispatching purposes of the endpoint method.

<SOAP-ENV:Header ...>

<wsa:To SOAP-..>http://www.packtpub.com/liverestaurant/OrderService/schema</wsa:To>
<wsa:Action>http://www.packtpub.com/OrderService/OrdReq</wsa:Action>
<wsa:MessageID>...</wsa:MessageID>
</SOAP-ENV:Header>

In this recipe, the server applies AnnotationActionEndpointMapping, which uses @Action (http://www.packtpub.com/OrderService/OrdReq). @Action is similar to @PayloadRoot for recognizing the handling methods (handleOrderRequest) in the endpoint (OrderEndpoint).

@Endpoint
public class OrderEndpoint {
  private OrderService orderService;
  @Autowired
    public void setOrderService(OrderService orderService) {
    this.orderService = orderService;
  }
  @Action("http://www.packtpub.com/OrderService/OrdReq")
  public @ResponsePayload
  Source handleOrderRequest(@RequestPayload Source source) throws Exception {
    //extract data from input parameter
    String fName="John";
    String lName="Smith";
    String refNumber="1234";
    
      return new StringSource(
    "<tns:placeOrderResponse xmlns:tns=\"http://www.packtpub.com/liverestaurant/OrderService/schema\"><tns:refNumber>"+orderService.placeOrder(fName, lName, refNumber)+"</tns:refNumber></tns:placeOrderResponse>");
  }
}

The recipe Creating Web-Service client for WS-Addressing endpoint, discussed in Chapter 2, Building Clients for SOAP Web-Services, and the recipe Setting up an endpoint by annotating the payload root, discussed in this chapter.

In this recipe, the project's name is LiveRestaurant_R-1.12 with the following Maven dependencies:

The steps of this recipe are the same as that of Setting up an endpoint by annotating the payload-root, except for the implementation of endpoint handling methods. So, follow the steps of the mentioned recipe and use XPath expressions to extract data from incoming message and create a response.

Passing the method parameter is the same as the recipe Setting up an endpoint by annotating the payload-root, except that it uses @XPathParam , which specifies the path of the data in a message that is to be passed as an argument into the method. Here XpathParamMethodArgumentResolver is responsible for extracting the value from the message and passing it to the method.

The annotation XpathParam helps the MethodArgumentResolvers (XpathParamMethodArgumentResolver) to extract information out of the XML and binds a node value to a method argument (using // cause, the whole message is searched recursively, for example, //lName searches the whole placeRequestRequest message). The same implementation is used for the method cancelOrderRequest:

@Endpoint
public class OrderEndpoint {
  
  private final String SERVICE_NS = "http://www.packtpub.com/liverestaurant/OrderService/schema";

  private OrderService orderService;

  @Autowired
  public OrderEndpoint(OrderService orderService) {
    this.orderService = orderService;
  }

  @PayloadRoot(localPart = "placeOrderRequest", namespace = SERVICE_NS)
  public @ResponsePayload
  Source handleOrderRequest(@XPathParam("//fName") String fName,@XPathParam("//lName") String lName,@XPathParam("//refNumber") String refNumber) throws Exception {
    return new StringSource(
    "<tns:placeOrderResponse xmlns:tns=\"http://www.packtpub.com/liverestaurant/OrderService/schema\"><tns:refNumber>" + orderService.placeOrder(fName, lName, refNumber)+"</tns:refNumber></tns:placeOrderResponse>");
  }

  @PayloadRoot(localPart = "cancelOrderRequest", namespace = SERVICE_NS)
  public @ResponsePayload
  Source handleCancelOrderRequest(@XPathParam("//refNumber") String refNumber) throws Exception {
    boolean cancelled = orderService.cancelOrder(refNumber);    
      return new StringSource(
          "<tns:cancelOrderResponse xmlns:tns=\"http://www.packtpub.com/liverestaurant/OrderService/schema\"><cancelled>"+(cancelled?"true":"false")+"</cancelled></tns:cancelOrderResponse>");
  }

The method argument can be any of the following:

The recipe Setting up an endpoint by annotating the payload-root, discussed in this chapter.

In this recipe, the project's name is LiveRestaurant_R-1.13, with the following Maven dependencies:

The steps of this recipe are the same as that of the recipe Setting up an endpoint by annotating the payload-root, except for the implementation of the endpoint-handling methods. So, follow the steps of the mentioned recipe and use DOM to extract data from the incoming message and create the response.

Passing the method parameter is the same as the recipe Setting up an endpoint by annotating the payload-root, except that we use @RequestPayload, which specifies the DOM element of data in a message to be passed as an argument into the method. Here, DomPayloadMethodProcessor is responsible for extracting the value from the message and passing it to the method. Since the return type which is specified by @ResponsePayload is also a DOM element type, DomPayloadMethodProcessor is being used as return handler.

The @PayloadRoot annotation informs Spring-WS that the handleCancelOrderRequest method is a handling method for XML messages. The sort of message that this method can handle is indicated by the annotation values (the @RequestPayload element tells it is of the DOM element type). In this case, it can handle XML elements that have the placeOrderRequest local part and the http://www.packtpub.com/liverestaurant/OrderService/schema namespace.

 @PayloadRoot(namespace = NAMESPACE_URI, localPart = "placeOrderRequest")
    @ResponsePayload
    public Element handlePlaceOrderRequest(@RequestPayload Element placeOrderRequest) throws Exception {
      
      String refNumber=placeOrderRequest.getElementsByTagNameNS(NAMESPACE_URI, "refNumber") .item(0).getTextContent();
      String fName=placeOrderRequest.getElementsByTagNameNS(NAMESPACE_URI, "fName") .item(0).getTextContent();
      String lName=placeOrderRequest.getElementsByTagNameNS(NAMESPACE_URI, "lName") .item(0).getTextContent();

The preceding code extracts the elements refNumber, fName, and lName from the incoming XML message (placeOrderRequest) via the method getElementsByTagNameNS. Then, it finds and returns the text content of the first item in the refNumber, fName, and lName elements (by item(0).getTextContent()).

The following part of the code creates an outgoing XML message by creating the placeOrderResponse element (using document.createElementNS). Then, it creates the child element refNumber (using document.createElementNS) and creates the text of this element (using createTextNode and appendChild). Then, it appends the refNumber element to the response element placeOrderResponse (using the appendChild method):

        Document document = documentBuilder.newDocument();
      Element responseElement = document.createElementNS(NAMESPACE_URI,
      "placeOrderResponse");
      
         Element canElem=document.createElementNS(NAMESPACE_URI,"refNumber");
      Text responseText = document.createTextNode(orderService.placeOrder(fName, lName, refNumber));

      canElem.appendChild(responseText);
      responseElement.appendChild(canElem);
      return responseElement;

The recipe Setting up an endpoint by annotating the payload-root, discussed in this chapter and the recipe Creating a Web-Service client on HTTP transport, discussed in Chapter 2, Building Clients for SOAP Web-Services.

In this recipe, the project's name is LiveRestaurant_R-1.14, with the following Maven dependencies:

The steps of this recipe are the same as that of the Setting up an endpoint by annotating the payload-root recipe, except for the implementation of the endpoint-handling methods. So, follow the steps of the aforementioned recipe, use JDOM to extract the data from incoming message, and create the response.

It works in the same way as explained in the previous recipe, except that it uses JDOM in its method implementation.

The following part of the code extracts the values refNumber, fName, and lName from the incoming XML message (placeOrderRequest) by using namespace and XPath object:

    Namespace namespace = Namespace.getNamespace("tns", NAMESPACE_URI);
    XPath refNumberExpression = XPath.newInstance("//tns:refNumber");
    refNumberExpression.addNamespace(namespace);

    XPath fNameExpression = XPath.newInstance("//tns:fName");
    fNameExpression.addNamespace(namespace);

    XPath lNameExpression = XPath.newInstance("//tns:lName");
    lNameExpression.addNamespace(namespace);

    String refNumber = refNumberExpression.valueOf(placeOrderRequest);
    String fName = fNameExpression.valueOf(placeOrderRequest);
    String lName = lNameExpression.valueOf(placeOrderRequest);

The following part of the code creates an outgoing message by creating the placeOrderResponse element (using new Element(...)). Then, it creates the child element refNumber (using new Element(...)) and creates the text f this element (using setText(...)). Then, it appends the message element to the response element placeOrderResponse (using the addContent method):

        Namespace resNamespace = Namespace.getNamespace("tns", NAMESPACE_URI);
    Element root = new Element("placeOrderResponse", resNamespace);
    Element message = new Element("refNumber", resNamespace);
    message.setText(orderService.placeOrder(fName, lName, refNumber));
    root.addContent(message);
    Document doc = new Document(root);
    return doc.getRootElement();

The recipes Setting up an endpoint by annotating the payload-root and Handling incoming XML Messages using DOM, discussed in this chapter.

The recipe Creating a Web-Service client on HTTP transport, discussed in Chapter 2, Building Clients for SOAP Web-Services.

In this recipe, the project's name is LiveRestaurant_R-1.15 and has the following Maven dependencies:

The steps of this recipe are the same as that of the recipe Setting up an endpoint by annotating the payload-root, except for the implementation of the endpoint handling methods. So, follow the steps of the aforementioned recipe and use JAXB Marshaller/Un-Mashaller to convert payload into/from POJO.

In the preceding code, the XML is bound with Java classes at runtime using JAXB. The incoming XML is converted into Java objects (unmarshalling) and after processing the objects, the resultant objects are marshalled back to XML before returning to the caller:

  @PayloadRoot(localPart = "placeOrderRequest", namespace = SERVICE_NS)
  public @ResponsePayload
  Source handlePlaceOrderRequest(@RequestPayload Source source) throws Exception {
    
     PlaceOrderRequest request = (PlaceOrderRequest) unmarshal(source, PlaceOrderRequest.class);
    PlaceOrderResponse response = new PlaceOrderResponse();
    String refNumber=request.getOrder().getRefNumber();
    String fName=request.getOrder().getCustomer().getName().getFName();
    String lName=request.getOrder().getCustomer().getName().getLName();
    response.setRefNumber(orderService.placeOrder(fName,lName,refNumber));
    
    return marshal(response);
  }
  private Object unmarshal(Source source, Class clazz) throws JAXBException {
    JAXBContext context;
    try {
      context = JAXBContext.newInstance(clazz);
      Unmarshaller um = context.createUnmarshaller();
      return um.unmarshal(source);
    } catch (JAXBException e) {
      e.printStackTrace();
      throw e;
    }
  }
  
  private Source marshal(Object obj) throws JAXBException {
    JAXBContext context = JAXBContext.newInstance(obj.getClass());
    return new JAXBSource(context, obj);
  }

The JAXB context binds the Java classes passed via the constructor with the incoming XML, with the help of annotations in the classes at runtime, which instructs the unmarshaller to instantiate and load data from the XML tags into the objects. The objects are now passed to the service classes (OrderServiceImpl) for processing:

public class OrderServiceImpl implements OrderService {
    @Service
public class OrderServiceImpl implements OrderService {

  public String placeOrder( String fName,String lName,String refNumber){
      return "order-"+fName+"_"+lName+"_"+refNumber;
    }
    
    public boolean cancelOrder( String refNumber ){
      return true;
    }

This approach allows the developer to work with Java objects instead of XML code with simple marshalling technology.

The recipe Setting up an endpoint by annotating the payload-root, discussed in this chapter.

The recipe Marshalling with JAXB2, discussed in Chapter 6, Marshalling and Object-XML Mapping (OXM)—Converting POJO to/from XML messages using Marshallers and Un-Marshallers.

In this recipe, the project's name is LiveRestaurant_R-1.16 with the following Maven dependencies:

The steps of this recipe are the same as that of Handling the incoming XML messages using DOM, except for the validation of request/response message.

spring-ws-servlet.xml is almost the same, as described in the recipe Handling the incoming XML messages using DOM, except that it includes the interceptor that uses schema for validation, validateRequest, and validateResponse.

     <sws:interceptors>
        <bean class="org.springframework.ws.soap.server.endpoint.interceptor.PayloadValidatingInterceptor">
            <property name="schema" value="/WEB-INF/OrderService.xsd"/>
            <property name="validateRequest" value="true"/>
            <property name="validateResponse" value="true"/>
        </bean>
        <bean class="org.springframework.ws.server.endpoint.interceptor.PayloadLoggingInterceptor">
        </bean>
    </sws:interceptors> 

When running the client, two requests will be sent to the server. The first one will be processed and the response will be sent back to the client, while the second one contains the wrong element (address instead of addressPrimary) that will send the faulty response back:

Sent response....
<faultcode>SOAP-ENV:Client</faultcode><faultstring xml:lang="en">Validation error</faultstring><detail><spring-ws:ValidationErr
or xmlns:spring-ws="http://springframework.org/spring-ws">cvc-complex-type.2.4.a: Invalid content was found starting with element 'tns:address'. One of '{"http:
//www.packtpub.com/liverestaurant/OrderService/schema":addressPrimary}' is expected.</spring-ws:ValidationError></detail></SOAP-ENV:Fault></SOAP-ENV:Body></SOAP
-ENV:Envelope>]
….

The recipe Setting up an endpoint by annotating the payload-root, discussed in this chapter.

The recipe Creating a Web-Service client on HTTP transport, discussed in Chapter 2, Building Clients for SOAP Web-Services.