http://www.developer.com/java/ent/top-features-in-spring-ws-2.0-release.html

Back to article

Spring Web Services 2.0: Best Java Stack for SOAP-based Web Services


March 1, 2011

A major version of the Spring Web service project Spring WS 2.0 recently was released after a year in development. This version requires that your project use Java 5 or above and Spring 3.0 or above, but the upgrade (if necessary) is well worth it because Spring WS 2.0 delivers a lot of goodies for Java developers. New features include:

  • An improved, more flexible @Endpoint programming model
  • A new integration testing framework for both server-side and client-side testing
  • Java 5 APIs (generics, varargs), and more

For developers who are not familiar with Spring WS, it is a Spring portfolio project that lets you build Spring-based, document-oriented SOAP Web services. Spring WS is very different from other Java SOAP stacks as it is supports only the contract first Web service development style, it focuses on XML messages, and it does no code generation (except for dynamic generation of WSDL from XSD).

I have been experimenting with Spring WS 2.0 during the past several days . In this article, I will share some my experiences with the parts of the project that I have used--so this is not an exhaustive overview by any means. In future posts, I will cover the left over pieces. For now, I show you how you can create a simple SOAP Web service using Spring WS 2.0.

Creating a New Spring WS 2.0 Project

Using a Maven archetype, it is very easy to create a new Spring WS project. Please make sure that you have Maven 2 installed on your system and type the following command:

mvn archetype:create -DarchetypeGroupId=org.springframework.ws -DarchetypeArtifactId=spring-ws-archetype -DarchetypeVersion=2.0.0.RELEASE -DgroupId=com.shekhar.usermanagement -DartifactId=profileService

This command will create a Maven2-based Spring WS project with all the required configurations. The two files apart from pom.xml that this archetype will create are spring-ws-servlet.xml and web.xml. The web.xml is a standard Web application deployment descriptor, which maps all (/*) incoming requests to MessageDispatcherServlet. The spring-ws-servlet.xml contains all the Spring-WS-related beans, such as endpoints, WebServiceMessageReceivers, interceptors, and so on. The name of this file is the concatenation of the name of servlet defined in web.xml and "-servlet.xml". The name of the servlet is "spring-ws", so the Spring WS XML file name is "spring-ws-servlet.xml".

Best New Features in Spring WS 2.0

This section highlights the most notable new features of Spring WS 2.0.

Annotation-driven Enpoint Model

The first feature I'll talk about is the single-line configuration in the spring-ws-servlet.xml file. This single line (shown below) configures the annotation-driven Spring WS endpoint model. So in Spring WS 2.0, you don't have to define any bean in spring-ws-context.xml to configure the @Endpoint programming model.

As an example, let's write a simple SOAP-based Web service that creates a user profile. As Spring WS follows a contract first development style, we should first write the XML contract. The XML schema definition for our Web service is:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified" targetNamespace="http://shekhar.com/usermanagement/schemas"
xmlns:schemas="http://shekhar.com/usermanagement/schemas">
<xs:element name="UserProfileCreateRequest">
<xs:complexType>
<xs:sequence>
<xs:element name="UserProfile" type="schemas:UserProfile" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:complexType name="UserProfile">
<xs:sequence>
<xs:element name="firstName" type="xs:string" />
<xs:element name="lastName" type="xs:string" />
<xs:element name="age" type="xs:integer" />
</xs:sequence>
</xs:complexType>
<xs:element name="UserProfileCreateResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="message" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>

Automatic WSDL Exposure Using sws:dynamic-wsdl and sws:static-wsdl

Spring WS gives us the option to generate the WSDL from XSD dynamically (i.e., without writing it ourselves). Before version 2.0, we had to define a bean in a context file to generate WSDL dynamically. With Spring WS 2.0, you can generate the WSDL dynamically by using the <sws:dynamic-wsdl> tag.

 <sws:dynamic-wsdl id="profile" portTypeName="UserManagement" locationUri="/profileService" targetNamespace="http://shekhar.com/usermanagement/schemas">
<sws:xsd location="/WEB-INF/userManagement.xsd"/>
</sws:dynamic-wsdl>

We can also publish an existing WSDL using the tag. If you deploy the application now on any server like Jetty or Tomcat, you will be able to see the WSDL at http://localhost:8080/profileService/profile.wsdl.

Improved, More Flexible @EndpointModel

So far we have exposed our contract (i.e. WSDL), but we have not written the code that will be invoked on the server side. In Spring WS, you write endpoints that handle incoming XML messages. An endpoint is a class annotated with the @Endpoint annotation. In this endpoint class, you will create one or more methods that handle incoming request XML messages. The handle methods can take a wide range of parameter and return types, such as JAXB2, dom4j, XPATH, SAX, STAX, and so on. You can also mix and match the parameters (i.e. you can have a request parameter as a DOM object and return a JAXB2 response object).

This is the most important feature introduced in this release. The handle methods are annotated with @PayloadRoot or @SoapAction to map which kind of messages a method can handle. You can get the complete list of supported parameter and return types from the SpringSource documentation.

As an example, let's write an endpoint for profile service.

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.ws.server.endpoint.annotation.Endpoint;
import org.springframework.ws.server.endpoint.annotation.PayloadRoot;
import org.springframework.ws.server.endpoint.annotation.RequestPayload;
import org.springframework.ws.server.endpoint.annotation.ResponsePayload;
import com.shekhar.usermanagement.profile.UserProfileCreateRequest;
import com.shekhar.usermanagement.profile.UserProfileCreateResponse;
@Endpoint
public class UserProfileEndpoint {
private UserService service;
@Autowired
public UserProfileEndpoint(UserService service) {
this.service = service;
}
@PayloadRoot(localPart = "UserProfileCreateRequest", namespace = "http://shekhar.com/usermanagement/schemas")
@ResponsePayload
public UserProfileCreateResponse create(@RequestPayload UserProfileCreateRequest request) {
String message = service.createUser(request.getUserProfile());
UserProfileCreateResponse response = new UserProfileCreateResponse();
response.setMessage(message);
return response;
}
}

In the endpoint shown above, the @PayloadRoot annotation maps all the incoming requests with the namespace "http://shekhar.com/usermanagement/schemas" and localpart "UserProfileCreateRequest" to the create method. I have used JAXB2 as the parameter and return type. You can generate JAXB2 objects from XSD using the Maven 2 plugin. For more information please download the code from my github repository.

Snap Judgment: Spring WS 2.0 Is the Best

With its new @Endpoint programming model, it is very easy to create a SOAP-based Web service with Spring WS 2.0.The improved @Endpoint programming model is very flexible and requires very little configuration. You don't have to write all the boilerplate code to do the configuration, like when you define beans in a context file. Just write a few XML tags in the application context XML file and you are done.

To me, Spring WS 2.0 is the best Java stack to write SOAP-based Web services.

About the Author

Shekhar Gulati is a Java consultant with over 5 years experience. He currently works with Xebia India, an Agile Software Development company. The opinions in this article and on his blog are his own and do not necessarily represent the opinions of his employer. His own blog is at and you can follow him on twitter here.

Sitemap | Contact Us