How to Use Spring Web Services

Spring Webservices encourages a contract first, message oriented approach to creating Webservices. The underlying details are completely under developer control starting from the contract to the marshalling/unmarshalling details to the endpoint handling the request.

Let us start by an example of a simple service to expose as a webservice - call it the MemberService. MemberService exposes one operation “Get Member Details” which returns the details of a member/person, given an identifier.

Creating the contract:

The Contract/WSDL for this service is fairly simple. Let us start by defining the messages and type :

		<xsd:schema targetNamespace="http://bk.org/memberservice/" elementFormDefault="qualified">
			<xsd:complexType name="MemberDetailType">
				<xsd:sequence>
					<xsd:element name="name" type="xsd:string" />
					<xsd:element name="phone" type="xsd:string" />
					<xsd:element name="city" type="xsd:string" />
					<xsd:element name="state" type="xsd:string" />
				</xsd:sequence>
			</xsd:complexType>
			<xsd:element name="MemberDetailsRequest">
				<xsd:complexType>
					<xsd:sequence>
						<xsd:element name="id" type="xsd:string" />
					</xsd:sequence>
				</xsd:complexType>
			</xsd:element>
			<xsd:element name="MemberDetailsResponse">
				<xsd:complexType>
					<xsd:sequence>
						<xsd:element name="memberdetail" type="ms:MemberDetailType" />
					</xsd:sequence>
				</xsd:complexType>
			</xsd:element>
		</xsd:schema>

MemberRequest message comprises of an id to represent the requested members identifier

MemberResponse message comprises of MemberDetail type to represent the details of a member.

A sample payload over the wire would look like this:

<?xml version="1.0"?>
<ms:MemberDetailsRequest xmlns:ms="http://bk.org/memberservice/">
	<ms:id>SAMPLE</ms:id>
</ms:MemberDetailsRequest>

and a sample response:

<ms:MemberDetailsResponse xmlns:ms="http://bk.org/memberservice/">
	<ms:memberdetail>
		<ms:name>testname</ms:name>
		<ms:city>testcity</ms:city>
		<ms:phone>testphone</ms:phone>
		<ms:state>teststate</ms:state>
	</ms:memberdetail>
</ms:MemberDetailsResponse>

The sample request and response can be easily generated by using a tool like SOAP UI –

Creating an Endpoint:

A Spring-WS endpoint processes the XML message and produces the XML response. Spring provides different Endpoints based on how the XML is to be handled. If you wish to handle raw xml you have the option of implementing AbstractDom4jPayloadEndpoint, AbstractDomPayloadEndpoint, AbstractJDomPayloadEndpoint etc, based on how the raw xml needs to be handled. If you wish to handle the XML message as an object representation then you can implement the AbstractMarshallingPayloadEndpoint, which is what I will be using for this example along with JIBX as the XML binding framework for its ease of use and performance.

package org.bk.memberservice.endpoint;

import org.bk.memberservice.message.MemberDetailsRequest;
import org.bk.memberservice.message.MemberDetailsResponse;
import org.bk.memberservice.service.MemberManager;
import org.bk.memberservice.types.MemberDetail;
import org.springframework.ws.server.endpoint.AbstractMarshallingPayloadEndpoint;

public class GetMemberDetailsEndpoint extends
		AbstractMarshallingPayloadEndpoint {

	private MemberManager memberManager;

	protected Object invokeInternal(Object requestObject) throws Exception {
		MemberDetailsRequest request = (MemberDetailsRequest) requestObject;
		MemberDetail memberDetail = memberManager.getMemberDetails(request
				.getId());
		MemberDetailsResponse response = new MemberDetailsResponse(memberDetail);
		return response;

	}

	public void setMemberManager(MemberManager memberManager) {
		this.memberManager = memberManager;
	}
}

Writing the Object/XML binding:

So we now have the endpoint to process the take in the request Message, process it and respond. The only missing piece is how to transform the raw request xml over the wire to the MemberDetailsRequest object, and on the way back to transform the MemberDetailsResponse object back to XML. This is where Springs Object/XML mapping support comes in. Spring Object/XML mapper provides a simple abstraction over the popular Java XML binding stacks like JAXB, Castor, JiBX, Xstream. In the current example, we will start by defining the binding file for JiBX:

<?xml version="1.0" encoding="UTF-8"?>
<binding>
	<mapping name="MemberDetailsRequest"
		class="org.bk.memberservice.message.MemberDetailsRequest">
		<namespace prefix="ms" uri="http://bk.org/memberservice/" default="all"/>
		<value name="id" field="id" />
	</mapping>

	<mapping name="MemberDetailsResponse"
		class="org.bk.memberservice.message.MemberDetailsResponse">
		<namespace prefix="ms" uri="http://bk.org/memberservice/" default="all"/>
		<structure name="memberdetail" field="memberDetail"
			class="org.bk.memberservice.types.MemberDetail">
			<value name="name" field="name" />
			<value name="city" field="city" />
			<value name="phone" field="phone" />
			<value name="state" field="state" />
		</structure>
	</mapping>
</binding>

JiBX requires a compile step with the above binding file, this is very easily wired using Maven as the build tool.

Putting it together:

So now all the pieces are in place -

To direct the request to the appropriate endpoint, Spring-WS requires a custom servlet to be set up:

    <servlet>
        <servlet-name>memberservice</servlet-name>
        <servlet-class>org.springframework.ws.transport.http.MessageDispatcherServlet</servlet-class>
        <init-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>classpath:/applicationContext-memberservice.xml</param-value>
        </init-param>
    </servlet>

    <servlet-mapping>
        <servlet-name>memberservice</servlet-name>
        <url-pattern>/services/*</url-pattern>
    </servlet-mapping> 

This would direct all requests starting with serivces/* to be handled by Spring-WS.

The MessageDispatcherServlet would look for a Spring bean with id of “payloadMapping” to direct the incoming XML to an appropriate endpoint, for the example the bean entry is the following:

	<bean id="payloadMapping"
		class="org.springframework.ws.server.endpoint.mapping.PayloadRootQNameEndpointMapping">
		<property name="endpointMap">
			<map>
				<entry key="{http://bk.org/memberservice/}MemberDetailsRequest"
					value-ref="getMemberDetailsEndpoint" />
			</map>
		</property>
	</bean>

 Essentially a request with MemberDetailsRequest as the element will be directed to getMemberDetailsEndpoint which is :

	<bean id="getMemberDetailsEndpoint" class="org.bk.memberservice.endpoint.GetMemberDetailsEndpoint">
		<property name="marshaller" ref="marshaller" />
		<property name="unmarshaller" ref="unmarshaller" />
		<property name="memberManager" ref="memberManager" />
	</bean>

The Endpoint needs the marshaller and unmarshaller to be injected to transform the request XML to request object and the response object to response XML. These are created as follows:

	<bean id="marshaller" class="org.springframework.oxm.jibx.JibxMarshaller">
		<property name="targetClass"
			value="org.bk.memberservice.message.MemberDetailsResponse" />
	</bean>

	<bean id="unmarshaller" class="org.springframework.oxm.jibx.JibxMarshaller">
		<property name="targetClass"
			value="org.bk.memberservice.message.MemberDetailsRequest" />
	</bean>

Exposing the Webservice WSDL:

Since the WSDL was created from scratch, to expose this pre-canned wsdl requires a bit more configuration with Spring:

	<bean id="MemberDetailsRequest"
		class="org.springframework.ws.wsdl.wsdl11.SimpleWsdl11Definition">
		<property name="wsdl" value="classpath:/memberservice.wsdl" />
	</bean>

Now, when the request comes in for the URI /memberservice/MemberDetailsRequest.wsdl, Spring-WS would serve out the static memberservice.wsdl.

This completes the Webservice implementation. It can be further enhanced to handle the Exception scenarios, Security etc which is an exercise for another day.

The complete example can be run using the attached maven enabled code, which will download all dependencies, and can be run using the following command:

mvn jetty:run

Conclusion:

Spring-WS provides a compelling way to create a webservice with a contract first approach. The amount of code appears extensive, however there is clean separation of the contract defined by the WSDL and the implementation, thus being able to change underlying implementation without affecting the contract.