Simple Spring Web Services using JAXB for Marshalling

　　David Winterfeldt

　　2008

　　A very simple example of using Spring Web Services 1.5.x with JAXB for marshalling and unmarshalling requests. A JAXB plugin for Maven is used to generate the JAXB beans from and XSD and the XSD is reused to generate a WSDL. The response from the server sends a person list, but could easily be modified to retrieve person based on an ID.

　　1. Server Configuration

　　Web Configuration

　　The MessageDispatcherServlet needs to be defined and the URL patterns it will handle. The contextConfigLocation is specified instead of allowing the default (/WEB-INF/spring-ws-servlet.xml) because this location makes the configuration easier to share with the unit test.

　　/WEB-INF/web.xml

　　xmlns="http://java.sun.com/xml/ns/javaee"

　　xmlns:web="http://java.sun.com/xml/ns/javaee/web-a pp_2_5.xsd"

　　xsi:schemaLocation="http://java.sun.com/xml/ns/jav aee

　　http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"

　　id="WebApp_ID" version="2.5">

　　spring-ws

　　org.springframework.ws.transport.http .MessageDispatcherServlet

　　contextConfigLocation

　　classpath:/spring-ws-context.xml

　　spring-ws

　　/*

　　Spring Configuration

　　The PersonEndpoint is defined as a bean and will automatically be registered with Spring Web Services since the class is identified as an endpoint by the @Endpoint annotation. This configuration uses the person.xsd that was used to generated the JAXB beans to generate the WSDL. The locationUri matches the URL pattern specified in the web.xml.

　　The JAXB marshaller/unmarshaller is configured using Spring OXM and also set on the MarshallingMethodEndpointAdapter bean.

　　/src/main/resources/spring-ws-context.xml

　　xmlns:xsi="http://www.w3.org/2001/XMLSchema-instan ce"

　　xmlns:p="http://www.springframework.org/schema/p"

　　xmlns:context="http://www.springframework.org/sche ma/context"

　　xsi:schemaLocation="http://www.springframework.org /schema/beans

　　http://www.springframework.org/schema/beans/spring -beans.xsd

　　http://www.springframework.org/schema/context

　　http://www.springframework.org/schema/context/spri ng-context.xsd">

　　p:portTypeName="Person"

　　p:locationUri="/personService/"

　　p:requestSuffix="-request"

　　p:responseSuffix="-response">

　　p:xsd="classpath:/person.xsd" />

　　An endpoint mapping strategy that looks for @Endpoint and @PayloadRoot annotations.

　　Enables the MessageDispatchServlet to invoke methods requiring OXM marshalling.

　　p:contextPath="org.springbyexample.person.schema.b eans" />

　　XML Schema Descriptor

　　A very simple XSD defining an element to indicate an incoming request to get all persons (name element isn't used) and a person response element that contains a list of person elements.

　　person.xsd

　　targetNamespace="http://www.springbyexample.org/pe rson/schema/beans"

　　xmlns:xsd="http://www.w3.org/2001/XMLSchema">

　　minOccurs="0" maxOccurs="unbounded"/>

　　Code Example

　　Example 1. MarshallingPersonService

　　Interface for getting persons using the JAXB generated beans ('get-persons-request' element --> GetPersonsRequst? , 'person-response' element --> PersonResponse? ). It also has constants for the namespace (matches XSD) and a request constant.

　　public interface MarshallingPersonService {

　　public final static String NAMESPACE = "http://www.springbyexample.org/person/schema/bean s";

　　public final static String GET_PERSONS_REQUEST = "get-persons-request";

　　/**

　　* Gets person list.

　　*/

　　public PersonResponse getPersons(GetPersonsRequest request);

　　}

　　Example 2. PersonEndpoint

　　It is indicated as an endpoint by the @Endpoint annotation and implements MarshallingPersonService. The getPersons method is indicated to handle a specific namespace and incoming request element.

　　The endpoint just prepares a static response, but this could very easily have a DAO injected into it and information retrieved from a database that is then mapped into the JAXB beans. The PersonResponse is created using the JAXB Fluent API which is less verbose than the standard JAXB API.

　　@Endpoint

　　public class PersonEndpoint implements MarshallingPersonService {

　　/**

　　* Gets person list.

　　*/

　　@PayloadRoot(localPart=GET_PERSONS_REQUEST, namespace=NAMESPACE)

　　public PersonResponse getPersons(GetPersonsRequest request) {

　　return new PersonResponse().withPerson(

　　new Person().withId(1).withFirstName("Joe").withLastNa me("Smith"),

　　new Person().withId(2).withFirstName("John").withLastN ame("Jackson"));

　　}

　　} 2. Client Configuration

　　Spring Configuration

　　The org.springbyexample.ws.service package is scanned for beans and will find the PersonServiceClient and inject the WebServiceTemplate into it. The JAXB marshaller/umarshaller is defined and set on the template.

　　The import of the jetty-context.xml isn't relevant to creating a client, but it creates an embedded jetty instance that loads the spring-ws-context.xml and it's services. Then client in the unit test is able to run in isolation.

　　PersonServiceClientTest.xml

　　xmlns:xsi="http://www.w3.org/2001/XMLSchema-instan ce"

　　xmlns:p="http://www.springframework.org/schema/p"

　　xmlns:context="http://www.springframework.org/sche ma/context"

　　xsi:schemaLocation="http://www.springframework.org /schema/beans

　　http://www.springframework.org/schema/beans/spring -beans.xsd

　　http://www.springframework.org/schema/context

　　http://www.springframework.org/schema/context/spri ng-context.xsd">

　　p:defaultUri="http://${ws.host}:${ws.port}/${ws.co ntext.path}/personService/"

　　p:marshaller-ref="marshaller"

　　p:unmarshaller-ref="marshaller" />

　　p:contextPath="org.springbyexample.person.schema.b eans" />

　　Code Example

　　Example 3. PersonServiceClient

　　At this point Spring Web Services handle almost everything. The template just needs to be called and it will return the PersonResponse from the service endpoint. The client can be used like this: PersonResponse response = client.getPersons(new GetPersonsRequest());

　　public class PersonServiceClient implements MarshallingPersonService {

　　@Autowired

　　private WebServiceTemplate wsTemplate;

　　/**

　　* Gets person list.

　　*/

　　public PersonResponse getPersons(GetPersonsRequest request) {

　　PersonResponse response =

　　(PersonResponse) wsTemplate.marshalSendAndReceive(request);

　　return response;

　　}

　　} 3. Unit Test

　　Spring Configuration

　　The unit test's main XML configuration was shown in the Client Spring Configuration section, but this is the configuration that it imported. It creates an embedded Jetty instance and registers the Spring Web Service MessageDispatcherServlet. The spring-ws-context.xml configuration is passed into the servlet.

　　jetty-context.xml

　　xmlns:xsi="http://www.w3.org/2001/XMLSchema-instan ce"

　　xmlns:p="http://www.springframework.org/schema/p"

　　xmlns:context="http://www.springframework.org/sche ma/context"

　　xsi:schemaLocation="http://www.springframework.org /schema/beans

　　http://www.springframework.org/schema/beans/spring -beans.xsd

　　http://www.springframework.org/schema/context

　　http://www.springframework.org/schema/context/spri ng-context.xsd">

　　class="org.mortbay.jetty.Server"

　　init-method="start" destroy-method="stop">

　　class="org.mortbay.thread.concurrent.ThreadPool">

　　class="org.mortbay.jetty.nio.SelectChannelConnecto r"

　　p:port="${ws.port}"

　　p:maxIdleTime="30000"

　　p:acceptors="2"

　　p:confidentialPort="8443" />

　　p:contextPath="/${ws.context.path}">

　　p:name="spring-ws">

　　p:servletName="spring-ws"

　　p:pathSpec="/*" />

　　4. Reference

　　Related Links

　　Spring Web Services Site

　　JAXB Reference Implementation Project

　　Project Setup

　　The project is available to checkout from an anonymous Subversion checkout.

　　Command Line Example

　　svn co http://svn.springbyexample.org/enterprise/simple-s pring-web-services/tags/1.1.2/ simple-spring-web-services

　　General Setup Instructions

　　General instructions for checking out the project with Eclipse and building with Maven.

　　Example Project Setup

　　Project Information

　　Spring Framework 3.0.x

　　Spring Web Services 1.5.x