Monday, 28 January 2013

Axis2 Web Service Client Tutorial

Introduction
Axis2 is a Java framework that provides comprehensive support for exposing and consuming web services. This short post will look at its SOAP client support and how it can be used to get a simple web service client up and running.
For convenience I'm going to be calling a web service that I recently built as part of another blog post.  If you don't already have a web service to call you can grab the full source code for my sample service from github. Simply run a Maven build and deploy the WAR to your Servlet container.

What is a Web Service Client
This post doesn't attempt to explain the detailed inner workings of a web service client, but its still pretty useful to have an idea of what's going on under the hood. Most web service clients provide the following
  • A client side proxy for the remote service we want to call, that allows our application to invoke a SOAP service using a simple method call. The proxy insulates our application from the intricacies of sending and receiving SOAP messages.
  • Marshalling of Java objects to XML so that application data can be converted to SOAP payloads for posting to the service endpoint.
  • Un-marshalling of XML back into Java objects so that SOAP payloads returned from the remote service can be interpreted by our application.
  • Establishing and pooling HTTP connections between client and and web service.
WSDL2Java
Axis2 provides WSDL2Java tooling that parses a WSDL to generate the client side proxies required to invoke a remote service. WSDL2Java can be run on the command line but I prefer to use a Maven plugin so that I have a fresh set of proxies generated as part of every build.

Maven Configuration
The Maven POM configuration below shows how the axis2-wsdl2code-maven-plugin can be configured to generate the required client side stubs.
1:  <?xml version="1.0"?>  
2:  <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0  
3:                                      http://maven.apache.org/maven-v4_0_0.xsd">  
4:       <artifactId>axis2-webservice-client-sample</artifactId>  
5:       <modelVersion>4.0.0</modelVersion>  
6:       <inceptionYear>2011</inceptionYear>  
7:       <packaging>jar</packaging>  
8:       <groupId>com.blog.webservices.client</groupId>  
9:       <version>1.0</version>  
10:       <properties>  
11:            <axis2.version>1.6.2</axis2.version>  
12:            <log4j.version>1.2.16</log4j.version>  
13:       </properties>  
14:       <build>  
15:            <resources>  
16:                 <resource>  
17:                      <directory>src/main/resources</directory>  
18:                      <filtering>true</filtering>  
19:                 </resource>  
20:            </resources>  
21:            <plugins>  
22:                 <plugin>  
23:                      <groupId>org.apache.axis2</groupId>  
24:                      <artifactId>axis2-wsdl2code-maven-plugin</artifactId>  
25:                      <version>1.6.2</version>  
26:                      <executions>  
27:                           <execution>  
28:                                <goals>  
29:                                     <goal>wsdl2code</goal>  
30:                                </goals>  
31:                                <configuration>  
32:                                     <wsdlFile>src/main/resources/wsdl/AccountDetailsService.wsdl</wsdlFile>  
33:                                     <databindingName>adb</databindingName>  
34:                                     <packageName>com.blog.webservices.client</packageName>  
35:                                     <outputDirectory>src/main/java</outputDirectory>  
36:                                     <flattenFiles>true</flattenFiles>  
37:                                </configuration>  
38:                           </execution>  
39:                      </executions>  
40:                 </plugin>  
41:                 <plugin>  
42:                      <groupId>org.apache.maven.plugins</groupId>  
43:                      <artifactId>maven-compiler-plugin</artifactId>  
44:                 </plugin>  
45:            </plugins>  
46:       </build>  
47:       <dependencies>  
48:            <dependency>  
49:                 <groupId>org.apache.axis2</groupId>  
50:                 <artifactId>axis2-kernel</artifactId>  
51:                 <version>${axis2.version}</version>  
52:            </dependency>  
53:            <dependency>  
54:                 <groupId>org.apache.axis2</groupId>  
55:                 <artifactId>axis2-adb</artifactId>  
56:                 <version>${axis2.version}</version>  
57:            </dependency>  
58:            <dependency>  
59:                 <groupId>org.apache.axis2</groupId>  
60:                 <artifactId>axis2-transport-http</artifactId>  
61:                 <version>${axis2.version}</version>  
62:            </dependency>  
63:            <dependency>  
64:                 <groupId>org.apache.axis2</groupId>  
65:                 <artifactId>axis2-transport-local</artifactId>  
66:                 <version>${axis2.version}</version>  
67:            </dependency>  
68:            <dependency>  
69:                 <groupId>org.apache.axis2</groupId>  
70:                 <artifactId>axis2-xmlbeans</artifactId>  
71:                 <version>${axis2.version}</version>  
72:            </dependency>  
73:            <dependency>  
74:                 <groupId>log4j</groupId>  
75:                 <artifactId>log4j</artifactId>  
76:                 <version>${log4j.version}</version>  
77:            </dependency>  
78:       </dependencies>  
79:  </project>  
The POM configuration shown here is pretty simple. The interesting bit is the WSDL2Code configuration plugin between lines 22 and 40. The plugin is configured with the following information

Line 32- Location of WSDL we're going to use for code generation.
Line 33 - Data binding framework we're going to use for code generation. In this example I've used the standard ADB (Axis Data Binding) framework but we could easily plugin an equivalent framework like JAXB or XMLBeans.
Line 34 - Package name for the generated classes.
Line 35 - Output directory for generated classes.

Code Generation
Now that we have the POM configured the next step is to run a build and generate our classes. When we run 'mvn clean install' the WSDL2Code plugin will read the WSDL and invoke the Axis code generator to build a client side proxy for our service. When the build is complete our project structure should look similar to figure 1.0. You'll notice that 2 classes were generated, both of which are explained below.
Figure 1.0 Project Structure

AccountDetailsServiceCallBackHandler
This is an abstract class that can be extend to implement a non blocking web service client. A non blocking client invokes the remote service on a separate thread and returns immediately, so as not to 'block' the client application while Axis waits on a response. The AccountDetailsServiceCallbackHandler abstract class should be extended to provide implementations for 2 callback methods, that are invoked by Axis once it has received a response from the service.
This non blocking approach is very useful in certain circumstances, for example, when a client application needs to call a number of different services at the same time. Rather than call each service sequentially, the client application can call multiple services simultaneously (on different threads) and handle the response from each service as it arrives, using appropriate callback implementations.

AccountDetailsServiceStub
This class acts as a client side proxy for the remote service and provides a means of building requests, invoking the service and processing responses.

Calling the Service Synchronously
The code sample below shows how we can use the generated classes to call our service synchronously. Note that the main thread will block while it waits on a response from the service.
1:  package com.blog.samples.webservices.client;  
2:  import java.rmi.RemoteException;  
3:  import com.blog.webservices.client.AccountDetailsServicesStub;  
4:  import com.blog.webservices.client.AccountDetailsServicesStub.AccountDetailsRequest;  
5:  import com.blog.webservices.client.AccountDetailsServicesStub.AccountDetailsResponse;  
6:  public class SynchronousWebServiceClientTest  
7:  {  
8:       public static void main (String [] args) throws RemoteException  
9:       {  
10:            AccountDetailsServicesStub servicesStub = new AccountDetailsServicesStub(WebServiceCientUtils.SERVICE_ENDPOINT);  
11:            AccountDetailsRequest accountDetailsRequest = new AccountDetailsRequest();  
12:            accountDetailsRequest.setAccountNumber("12345");  
13:            AccountDetailsResponse accountDetailsResponse = servicesStub.accountDetails(accountDetailsRequest);  
14:            WebServiceCientUtils.logAccountDetails(accountDetailsResponse.getAccountDetails());  
15:       }  
16:  }  
Calling the Service Asynchronously
The code sample below shows how we can call our service asynchronously. Invoking 'startService' on the service stub kicks off a web service request on a new thread and returns immediately so that execution of the client application is not blocked. We pass in a new instance of our callback handler to handle the web service response.
1:  package com.blog.samples.webservices.client;  
2:  import java.rmi.RemoteException;  
3:  import com.blog.webservices.client.AccountDetailsServicesStub;  
4:  import com.blog.webservices.client.AccountDetailsServicesStub.AccountDetailsRequest;  
5:  public class AsynchronousWebServiceClientTest  
6:  {  
7:       public static void main (String [] args) throws RemoteException, InterruptedException  
8:       {  
9:             AccountDetailsServicesStub servicesStub = new AccountDetailsServicesStub(WebServiceCientUtils.SERVICE_ENDPOINT);  
10:            AccountDetailsRequest accountDetailsRequest = new AccountDetailsRequest();  
11:            accountDetailsRequest.setAccountNumber("12345");  
12:            WebServiceCientCallBackHandler callBackHandler = new WebServiceCientCallBackHandler();  
13:            servicesStub.startaccountDetails(accountDetailsRequest, callBackHandler);  
14:            Thread.sleep(5000);  
15:       }  
16:  }  
A sample callback handler implementation is shown below. Note that we implement the receiveResultAccountDetails method to handle successful responses and receiveErrorAccountDetails to handle errors. Axis2 will invoke the appropriate method depending on whether or not the web service call was successful.
1:  package com.blog.samples.webservices.client;  
2:  import org.apache.log4j.Logger;  
3:  import com.blog.webservices.client.AccountDetailsServicesCallbackHandler;  
4:  import com.blog.webservices.client.AccountDetailsServicesStub.AccountDetailsResponse;  
5:  public class WebServiceCientCallBackHandler extends AccountDetailsServicesCallbackHandler  
6:  {  
7:            private static final Logger logger_c = Logger.getLogger(WebServiceCientCallBackHandler.class);  
8:            @Override  
9:            public Object getClientData()  
10:            {  
11:                 return super.getClientData();  
12:            }  
13:            @Override  
14:            public void receiveResultaccountDetails(AccountDetailsResponse result_p)  
15:            {  
16:                 super.receiveResultaccountDetails(result_p);  
17:                 WebServiceCientUtils.logAccountDetails(result_p.getAccountDetails());  
18:            }  
19:            @Override  
20:            public void receiveErroraccountDetails(Exception ex_p)  
21:            {  
22:                 super.receiveErroraccountDetails(ex_p);  
23:                 logger_c.error("An error occurred calling AccountDetails Service", ex_p);  
24:            }  
25:  }  
Source Code
You can download the full source code for this tutorial here. I'm having an issue with my GitHub account at the minute but as soon as I get that sorted I'll push the code up and add a link.
If you liked the post or have questions about any of the material covered, feel free to leave a comment below.

Monday, 14 January 2013

Spring Web Services Tutorial

Introduction
Modern enterprise applications are rarely stand alone and often rely on data and services provided by external systems. In order for different types of systems to communicate there must be a  communication protocol of some sort, a standard way of sending and receiving messages in a format that is recognised and supported by all major platforms. SOAP (Simple Object Application Protocol) is such a protocol, and allows applications to communicate by exchanging messages in a standard XML format.
SOAP Web Services provide a platform agnostic integration mechanism that allows disparate systems to exchange data regardless of the platform they are running on. For example, SOAP web services are commonly used to integrate .NET applications with applications running on the Java platform. Almost all modern platforms and frameworks (Java, .Net, Ruby, PHP, etc) provide comprehensive libraries and tooling that allow developers to quickly and easily expose and consume SOAP services.
This post will look at Spring Web Services and take you through a step by step tutorial for building, deploying and testing a simple contract first SOAP service for retrieving simple bank account details.

Technology Stack
The technology stack used in this tutorial will include Spring 3.1 for Web Services Support, Maven for  dependency resolution & build, Tomcat for our test server and SoapUI to build sample SOAP messages for testing our service.

Creating the Project
The project structure is similar to that used in a some of my other tutorials and is typical of most modern Spring web applications. We'll start off by creating a simple Spring web project like the one shown in figure 1.0 below.
Figure 1.0 Project Structure
Contract Last vs Contract First
There are two fundamental approaches to building web services, Contract Last and Contract First.
The Contract Last approach involves taking existing code and generating a service contract directly from that code in order to expose it as a SOAP interface. There are a variety of Java frameworks out there (Axis2, XFire etc) that provide this Java2WSDL tooling, to quickly generate the server side proxies, marshallers and Servlet classes required to expose a SOAP service.
The Contract First approach involves defining the Service contract before implementing the service. This means describing the service parameters and return types using XSD's (XML Schema Definitions), then using those XSD's to construct a WSDL (web service definition language) to provides a public facing contract or description of the service. Only after the service contract has been clearly defined, is the service implementation actually written.
This post will describe a Contract First service, as this is the preferred approach for various reasons, some of which are explained in this article.

Service Contract Definition
Given that we're building a service to retrieve simple bank account details we'll start off by defining our core business entity, an Account. We'll define our account entity in src/main/webapp/schemas/AccountDetails.xsd.
 <?xml version="1.0" encoding="UTF-8"?>  
 <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="http://webservices.samples.blog.com" targetNamespace="http://webservices.samples.blog.com" elementFormDefault="qualified" attributeFormDefault="unqualified">  
      <xs:element name="Account" type="Account"/>  
      <xs:complexType name="Account">  
           <xs:sequence>  
                <xs:element name="AccountNumber" type="xs:string"/>  
                <xs:element name="AccountName" type="xs:string"/>  
                <xs:element name="AccountBalance" type="xs:double"/>  
                <xs:element name="AccountStatus" type="EnumAccountStatus"/>  
           </xs:sequence>  
      </xs:complexType>  
      <xs:simpleType name="EnumAccountStatus">  
           <xs:restriction base="xs:string">  
                <xs:enumeration value="Active"/>  
                <xs:enumeration value="Inactive"/>  
           </xs:restriction>  
      </xs:simpleType>  
 </xs:schema>  
I use XMLSpy for working with XML as it provides a useful graphical representation of the XML types being defined. This can be useful when working on large applications with complex data models. A visual representation of the above XSD is shown below.
Figure 2.0 Account Entity
Next we'll define the service request and response types in src/main/webapp/schemas/AccountDetailsServiceOperations.xsd.
 <?xml version="1.0" encoding="UTF-8"?>  
 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://com/blog/samples/webservices/accountservice" xmlns:account="http://webservices.samples.blog.com" targetNamespace="http://com/blog/samples/webservices/accountservice" elementFormDefault="qualified">  
      <xsd:import namespace="http://webservices.samples.blog.com" schemaLocation="AccountDetails.xsd"/>  
      <xsd:element name="AccountDetailsRequest">  
           <xsd:complexType>  
                <xsd:sequence>  
                     <xsd:element name="accountNumber" type="xsd:string"/>  
                </xsd:sequence>  
           </xsd:complexType>  
      </xsd:element>  
      <xsd:element name="AccountDetailsResponse">  
           <xsd:complexType>  
                <xsd:sequence>  
                     <xsd:element name="AccountDetails" type="account:Account"/>  
                </xsd:sequence>  
           </xsd:complexType>  
      </xsd:element>  
 </xsd:schema>  
A visual representation of these types is shown below.
Figure 3.0 AccountDetailsRequiest Entity
Figure 4.0 AccountDetailsResponse Entity
Object to XML Mapping
A fundamental part of web services is the conversion of SOAP messages from XML to Java objects and vice versa. This is a non trivial task if you were to set out to do it yourself so we'll make use of the JAXB framework to take car of this for us. I've been working with JAXB for a few years now and find it to be a powerful and flexible framework, and a huge improvement on older OXM frameworks like Castor.
In order to use our XSD defined types in the application we need to generate Java classes from those types. We do this as part of the Maven build process by using the jaxb-maven-plugin in our POM. The plugin is configured to parse a set of XSD's and run JAXB's class generator to create Java classes for each of the defined types. For brevity only part of the Maven POM definition is shown below. The entire  POM definition can be found with the source code that accompanies this tutorial.
 <?xml version="1.0"?>  
 <project xmlns="http://maven.apache.org/POM/4.0.0"  
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
            xsi:schemaLocation="http://maven.apache.org/POM/4.0.0  
                                     http://maven.apache.org/maven-v4_0_0.xsd">  
      <artifactId>spring-webservices-sample</artifactId>  
      <modelVersion>4.0.0</modelVersion>  
      <inceptionYear>2013</inceptionYear>  
      <packaging>war</packaging>  
      <groupId>com.blog.webservices</groupId>  
      <version>1.0</version>  
      <properties>  
           <spring.version>3.1.1.RELEASE</spring.version>  
           <spring.ws.version>2.0.0.RELEASE</spring.ws.version>  
           <log4j.version>1.2.16</log4j.version>  
           <context.path>spring-webservices-sample</context.path>  
      </properties>  
      <build>  
           <plugins>  
                <plugin>  
                     <groupId>org.codehaus.mojo</groupId>  
                     <artifactId>jaxb2-maven-plugin</artifactId>  
                     <version>1.4</version>  
                     <executions>  
                          <execution>  
                               <goals>  
                                    <goal>xjc</goal>  
                               </goals>  
                               <phase>generate-sources</phase>  
                          </execution>  
                     </executions>  
                     <configuration>  
                          <clearOutputDir>false</clearOutputDir>  
                          <outputDirectory>src/main/java</outputDirectory>  
                          <schemaDirectory>src/main/webapp/schemas</schemaDirectory>  
                          <includeSchema>**/*.xsd</includeSchema>                        
                          <enableIntrospection>false</enableIntrospection>  
                     </configuration>  
                </plugin>  
                <plugin>  
                     <groupId>org.apache.maven.plugins</groupId>  
                     <artifactId>maven-war-plugin</artifactId>  
                     <configuration>  
                          <warName>${context.path}</warName>  
                     </configuration>  
                </plugin>  
           </plugins>  
      </build>  
      <dependencies>  
     ...  
     ...  
Running a Maven build will create Java classes for each of the defined schema types. The screenshot below shows what the generated classes should look like in your project after you run a Maven build. Note that JAXB has used the the namespaces in the XSD's to derive package names for the generated classes.
Figure 5.0 JAXB Generated Classes
Defining the Service
The next step is to define the Service interface using the types we generated above. The Service interface is defined below and is very simple indeed.
 package com.blog.samples.services;  
 import com.blog.samples.webservices.Account;  
 /**  
  * The Interface AccountService.  
  */  
 public interface AccountService  
 {  
      /**  
       * Gets the account details.  
       *  
       * @param accountNumber the account number  
       * @return the account details  
       */  
      public Account getAccountDetails(String accountNumber);  
 }  
Now we'll provide a really simple implementation of this interface. As you can see our service implementation returns some hard coded values. Obviously a real service implementation would do something more meaningful.
 package com.blog.samples.services;  
 import org.springframework.stereotype.Service;  
 import com.blog.samples.webservices.Account;  
 import com.blog.samples.webservices.EnumAccountStatus;  
 /**  
  * The Class AccountService.  
  */  
 @Service  
 public class AccountServiceImpl implements AccountService  
 {  
      /**  
       * Gets the account details.  
       *  
       * @param accountNumber the account number  
       * @return the account details  
       */  
      public Account getAccountDetails(String accountNumber)  
      {  
           /* hard coded account data - in reality this data would be retrieved  
            * from a database or back end system of some sort */  
           Account account = new Account();  
           account.setAccountNumber("12345");  
           account.setAccountStatus(EnumAccountStatus.ACTIVE);  
           account.setAccountName("Joe Bloggs");  
           account.setAccountBalance(3400);  
           return account;  
      }  
 }  
Creating the Service Endpoint
A service endpoint is the component that deals with processing web service requests and responses. In the background a Spring Servlet intercepts incoming SOAP requests for a defined URL and routes them to an endpoint for processing. Below we're going to define that endpoint.
1:  package com.blog.samples.services.endpoints;  
2:  import org.springframework.beans.factory.annotation.Autowired;  
3:  import org.springframework.ws.server.endpoint.annotation.Endpoint;  
4:  import org.springframework.ws.server.endpoint.annotation.PayloadRoot;  
5:  import org.springframework.ws.server.endpoint.annotation.RequestPayload;  
6:  import org.springframework.ws.server.endpoint.annotation.ResponsePayload;  
7:  import com.blog.samples.services.AccountService;  
8:  import com.blog.samples.webservices.Account;  
9:  import com.blog.samples.webservices.accountservice.AccountDetailsRequest;  
10:  import com.blog.samples.webservices.accountservice.AccountDetailsResponse;  
11:  /**  
12:   * The Class AccountService.  
13:   */  
14:  @Endpoint  
15:  public class AccountServiceEndpoint  
16:  {  
17:       private static final String TARGET_NAMESPACE = "http://com/blog/samples/webservices/accountservice";  
18:       @Autowired  
19:       private AccountService accountService_i;  
20:       /**  
21:        * Gets the account details.  
22:        *  
23:        * @param accountNumber the account number  
24:        * @return the account details  
25:        */  
26:       @PayloadRoot(localPart = "AccountDetailsRequest", namespace = TARGET_NAMESPACE)  
27:       public @ResponsePayload AccountDetailsResponse getAccountDetails(@RequestPayload AccountDetailsRequest request)  
28:       {  
29:            AccountDetailsResponse response = new AccountDetailsResponse();  
30:            /* call Spring injected service implementation to retrieve account data */  
31:            Account account = accountService_i.getAccountDetails(request.getAccountNumber());  
32:            response.setAccountDetails(account);  
33:            return response;  
34:       }  
35:       public void setAccountService(AccountService accountService_p)  
36:       {  
37:            this.accountService_i = accountService_p;  
38:       }  
39:  }  
Our sample application makes sue of  Springs Web Services annotation support. The above class uses a number of these annotations, each of which is explained below.

Line 14 - @Enpoint is a specialised version of the standard Spring @Component annotation and allows this class to get picked up and registered by Springs component scanning.
Lines 18 & 19 - Our simple service implementation is Spring injected so that it can be used by our web service endpoint.
Line 17 - this is the namespace we defined in our XSD type definitions earlier. We use this in the endpoint class for mapping request to specific methods for processing.
Line 26 - @PayloadRoot indicates that this method will process service requests with the XML root element matching that defined by the localPart attribute. In the example above our method will process incoming requests of type AccountDetailsRequest with namespace http://com/blog/samples/webservices/accountservice. Remember that we defined this XSD type and namespace earlier.
Line 27 - @ResponsePayload indicates the type to be returned in the SOAP response. In this example the AccountDetailsResponse object will be converted to XML and returned to the client application as a SOAP response. @RequestPayload AccountDetails tells Spring to convert incoming requests of type AccountDetails, from XML to Java and the pass that object as a parameter to this endpoint method.

Spring Configuration
Next we'll write our Spring configuration to bring everything together. The Spring configuration is defined as follows.
1:  <?xml version="1.0" encoding="UTF-8"?>  
2:  <beans xmlns="http://www.springframework.org/schema/beans"  
3:            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
4:            xmlns:context="http://www.springframework.org/schema/context"  
5:            xmlns:sws="http://www.springframework.org/schema/web-services"  
6:            xsi:schemaLocation="http://www.springframework.org/schema/beans  
7:                                     http://www.springframework.org/schema/beans/spring-beans-3.0.xsd  
8:                                     http://www.springframework.org/schema/web-services  
9:                                     http://www.springframework.org/schema/web-services/web-services-2.0.xsd  
10:                                     http://www.springframework.org/schema/context  
11:                                     http://www.springframework.org/schema/context/spring-context-3.0.xsd">  
12:       <context:component-scan base-package="com.blog.samples.services" />  
13:       <sws:annotation-driven />  
14:       <!--  
15:            Our test service bean  
16:       -->  
17:       <bean id="AccountDetailsService" class="org.springframework.ws.wsdl.wsdl11.DefaultWsdl11Definition" lazy-init="true">  
18:      <property name="schemaCollection">  
19:        <bean class="org.springframework.xml.xsd.commons.CommonsXsdSchemaCollection">  
20:          <property name="inline" value="true" />  
21:          <property name="xsds">  
22:            <list>  
23:              <value>schemas/AccountDetailsServiceOperations.xsd</value>  
24:            </list>  
25:          </property>  
26:        </bean>  
27:      </property>  
28:      <property name="portTypeName" value="AccountDetailsService"/>  
29:      <property name="serviceName" value="AccountDetailsServices" />  
30:      <property name="locationUri" value="/endpoints"/>  
31:    </bean>  
32:  </beans>  
Line 12 - Component scanning scans the defined package (com.blog.sample.services) for Spring managed components to load into the bean factory.
Line 13 - Enables Spring Web Services annotation support so that annotations like @PayloadRoot can be used to configure the service endpoint.
Line 17 to 31 - Use of DefaultWsdl11Definition enables automated WSDL generation. Spring uses the schema definitions listed in the schemaCollection property, as well as the portType, serviceName and locationUri to generate a WSDL file the first time it is requested. Although this is a powerful feature it should be used with caution in production as the WSDL generation process can be quite slow. An approach I've used in the past is to copy the generated WSDL from your browser to your project and expose it using Springs static WSDL support with <static-wsdl>.

Web.xml
Now for the final bit of configuration before we test out our service. Web.xml is defined as follows.
1:  <?xml version="1.0" encoding="UTF-8"?>  
2:  <web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
3:             xmlns="http://java.sun.com/xml/ns/javaee"  
4:             xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"  
5:             xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"  
6:             id="WebApp_ID"  
7:             version="2.5">  
8:       <context-param>  
9:            <param-name>contextConfigLocation</param-name>  
10:            <param-value>  
11:                 /WEB-INF/config/spring-config.xml  
12:            </param-value>  
13:       </context-param>  
14:       <listener>  
15:            <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>  
16:       </listener>  
17:       <servlet>  
18:            <servlet-name>webservices</servlet-name>  
19:            <servlet-class>org.springframework.ws.transport.http.MessageDispatcherServlet</servlet-class>  
20:            <init-param>  
21:                 <param-name>transformWsdlLocations</param-name>  
22:                 <param-value>true</param-value>  
23:            </init-param>  
24:            <init-param>  
25:                 <param-name>contextConfigLocation</param-name>  
26:                 <param-value></param-value>  
27:            </init-param>  
28:            <load-on-startup>1</load-on-startup>  
29:       </servlet>  
30:       <servlet-mapping>  
31:            <servlet-name>webservices</servlet-name>  
32:            <url-pattern>*.wsdl</url-pattern>  
33:       </servlet-mapping>  
34:       <servlet-mapping>  
35:            <servlet-name>webservices</servlet-name>  
36:            <url-pattern>/endpoints/*</url-pattern>  
37:       </servlet-mapping>  
38:  </web-app>  
Line 8 to 13 - Path for Spring configuration to be loaded on application start-up.
Line 14 to 16 - Loads the Spring application context using the configuration file defined above
Line 18 to 19 - Spring Web Service Servlet that intercepts incoming HTTP requests.
Line 21 to 22 - Ensures WSDL is context aware. Transforms SOAP address so that it isn't hard coded to localhost:8080.Address updates depending on the application context and port that the application is deployed at.
Line 25 to 26 - ContextConfigLocation set with an empty parameter means that Spring won't try to load the default webservices-servlet.xml configuration.
Line 47 to 55 - Configures the URLs that our newly configured Web Services Servlet will handle.

Deploying the Service
We're now ready to deploy our application - I use Tomcat but feel free to use any Servlet container. Once the application is deployed, just browse to http://localhost:8080/spring-webservices-sample/endpoints/AccountDetailsService.wsdl and the application should generate and display the following WSDL.
1:  <wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:sch0="http://com/blog/samples/webservices/accountservice" xmlns:sch1="http://webservices.samples.blog.com" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="http://com/blog/samples/webservices/accountservice" targetNamespace="http://com/blog/samples/webservices/accountservice">  
2:       <wsdl:types>  
3:            <xsd:schema xmlns="http://com/blog/samples/webservices/accountservice" xmlns:account="http://webservices.samples.blog.com" xmlns:xsd="http://www.w3.org/2001/XMLSchema" attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="http://com/blog/samples/webservices/accountservice">  
4:                 <xsd:import namespace="http://webservices.samples.blog.com"/>  
5:                 <xsd:element name="AccountDetailsRequest">  
6:                      <xsd:complexType>  
7:                           <xsd:sequence>  
8:                                <xsd:element name="accountNumber" type="xsd:string"/>  
9:                           </xsd:sequence>  
10:                      </xsd:complexType>  
11:                 </xsd:element>  
12:                 <xsd:element name="AccountDetailsResponse">  
13:                      <xsd:complexType>  
14:                           <xsd:sequence>  
15:                                <xsd:element name="AccountDetails" type="account:Account"/>  
16:                           </xsd:sequence>  
17:                      </xsd:complexType>  
18:                 </xsd:element>  
19:            </xsd:schema>  
20:            <xs:schema xmlns="http://webservices.samples.blog.com" xmlns:xs="http://www.w3.org/2001/XMLSchema" attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="http://webservices.samples.blog.com">  
21:                 <xs:element name="Account" type="Account"/>  
22:                 <xs:complexType name="Account">  
23:                      <xs:sequence>  
24:                           <xs:element name="AccountNumber" type="xs:string"/>  
25:                           <xs:element name="AccountName" type="xs:string"/>  
26:                           <xs:element name="AccountBalance" type="xs:double"/>  
27:                           <xs:element name="AccountStatus" type="EnumAccountStatus"/>  
28:                      </xs:sequence>  
29:                 </xs:complexType>  
30:                 <xs:simpleType name="EnumAccountStatus">  
31:                      <xs:restriction base="xs:string">  
32:                           <xs:enumeration value="Active"/>  
33:                           <xs:enumeration value="Inactive"/>  
34:                      </xs:restriction>  
35:                 </xs:simpleType>  
36:            </xs:schema>  
37:       </wsdl:types>  
38:       <wsdl:message name="AccountDetailsResponse">  
39:            <wsdl:part element="tns:AccountDetailsResponse" name="AccountDetailsResponse"/>  
40:       </wsdl:message>  
41:       <wsdl:message name="AccountDetailsRequest">  
42:            <wsdl:part element="tns:AccountDetailsRequest" name="AccountDetailsRequest"/>  
43:       </wsdl:message>  
44:       <wsdl:portType name="AccountDetailsService">  
45:            <wsdl:operation name="AccountDetails">  
46:                 <wsdl:input message="tns:AccountDetailsRequest" name="AccountDetailsRequest"/>  
47:                 <wsdl:output message="tns:AccountDetailsResponse" name="AccountDetailsResponse"/>  
48:            </wsdl:operation>  
49:       </wsdl:portType>  
50:       <wsdl:binding name="AccountDetailsServiceSoap11" type="tns:AccountDetailsService">  
51:            <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>  
52:            <wsdl:operation name="AccountDetails">  
53:                 <soap:operation soapAction=""/>  
54:                 <wsdl:input name="AccountDetailsRequest">  
55:                      <soap:body use="literal"/>  
56:                 </wsdl:input>  
57:                 <wsdl:output name="AccountDetailsResponse">  
58:                      <soap:body use="literal"/>  
59:                 </wsdl:output>  
60:            </wsdl:operation>  
61:       </wsdl:binding>  
62:       <wsdl:service name="AccountDetailsServices">  
63:            <wsdl:port binding="tns:AccountDetailsServiceSoap11" name="AccountDetailsServiceSoap11">  
64:                 <soap:address location="http://localhost:8080/spring-webservices-sample/endpoints"/>  
65:            </wsdl:port>  
66:       </wsdl:service>  
67:  </wsdl:definitions>  
Testing the Service
The simplest way to test a SOAP service is using SoapUI. For anyone who hasn't used it before, SoapUI is an open source functional testing tool for testing SOAP web services. It saves us having to write a web service client and means that in just a few clicks we can have a test harness in place to test our service.

To test our serviced using SoapUI follow the steps below.
Figure 6.0 SoapUI Test Project
  • SoapUI will parse the exposed WSDL (make sure your application is deployed and the WSDL is exposed!) and use it to build a sample SOAP request.
  • When the new project opens click AccountServiceTest -> AccountDetails -> request and you'll see a SOAP request for the AccountDetails service in the left hand pane. Set the account number and press the green arrow in the top left hand corner to call the service.
  • If the request is successful you should see a SOAP response containing the requested account data in the right hand pane. See figure 7.0 below  
Figure 7.0 SoapUI AccountDetaills Service Test
Summary
The sample code in this post took you through the steps required to build, deploy and test a contract first web service using the Spring framework. Don't forget that you can download the full source code for this tutorial and play around with it. If you found this tutorial useful then feel free to share it with others or leave a comment below. The full source code can be found on GitHub at https://github.com/briansjavablog/spring-webservices-tutorial.