Search This Blog

Tuesday, 18 December 2012

SOAP Webservices using Spring -1

The Spring Web Services project is used for creating document-driven Web services. I decided to create a simple web service that takes a value and returns a value (i.e. no logic - just data transfer) .
The focus of Spring is to allow for contract-first SOAP service development. Accordingly I defined a simple WSDL document detailing my web services.
<?xml version="1.0"  encoding = "UTF-8" ?>
<wsdl:definitions xmlns:xs=""
            <xs:import namespace=""
                schemaLocation="xsd/RandomService.xsd" />

    <wsdl:message name="GetRandomRequest">
        <wsdl:part element="random:GetRandomRequest" name="GetRandomRequest" />
    <wsdl:message name="GetRandomResponse">
        <wsdl:part element="random:GetRandomResponse"
            name="GetRandomResponse" />
    <wsdl:message name="GetRandomFault">
        <wsdl:part element="random:GetRandomFault" name="GetRandomFault" />

    <wsdl:portType name="SampleServiceOperationsPortType">
        <wsdl:operation name="random">
            <wsdl:documentation>Returns a random value
            <wsdl:input message="tns:GetRandomRequest" name="GetRandomRequest" />
            <wsdl:output message="tns:GetRandomResponse" name="GetRandomResponse" />
            <wsdl:fault message="tns:GetRandomFault" name="GetRandomFault" />

    <wsdl:binding name="SampleServiceOperationsPortTypeSoap"
        <soap:binding style="document"
            transport="" />
        <wsdl:operation name="random">
            <soap:operation soapAction="/Service/random" />
            <wsdl:input name="GetRandomRequest">
                <soap:body use="literal" />
            <wsdl:output name="GetRandomResponse">
                <soap:body use="literal" />
            <wsdl:fault name="GetRandomFault">
                <soap:fault use="literal" name="GetRandomFault" />

    <wsdl:service name="SampleServiceOperationsPortTypeSoap">
        <wsdl:port binding="tns:SampleServiceOperationsPortTypeSoap"
            <soap:address location="/Service/ws-operations" />
As can be seen the wsdl defines a single operation which takes a GetRandomRequest object as input and returns a GetRandomResponse as output. In case of failure the operation returns a fault object of type GetRandomFault. The details of the these object is in an accompanying XSD file.
<xs:schema xmlns:xs=""

    <xs:element name="GetRandomRequest">
                <xs:element name="name" type="xs:string" maxOccurs="1"
                    minOccurs="1" />
    <xs:element name="GetRandomResponse">
                <xs:element name="value" type="xs:int" maxOccurs="1"
                    minOccurs="1" />
    <xs:element name="GetRandomFault">
                <xs:element name="faultMessage" type="xs:string"
                    maxOccurs="1" minOccurs="1" />
Now that the contract is defined the next step is to implement the webservice via Spring:
Step 1 is to create a Server project to host our web-service. I did this in Eclipse creating a dynamic web project.
Step 2 is to configure the Server side to handle our requests. Handler in Java Enterprise is at its simplest a servlet. Just like the DispatcherServlet which acts as a front controller receiving all requests and then delegating to controllers, spring ws uses the MessageDispatcherServlet. As per the code documentation:
Servlet for simplified dispatching of Web service messages.
This servlet is a convenient alternative to the standard Spring-MVC DispatcherServlet 
with separate WebServiceMessageReceiverHandlerAdapter, MessageDispatcher, and
WsdlDefinitionHandlerAdapter instances.
This servlet automatically detects EndpointAdapters, EndpointMappings, and 
EndpointExceptionResolvers by type.
The servlet acts like a front controller for our web service, receiving all requests and then delegating them to appropriate endpoints (Controllers in the web service world).
This is from the docs: When the transformWsdlLocations init-param is set to true in this servlet's configuration in web.xml, all location attributes in the WSDL definitions will reflect the URL of the incoming request.  
Step 3 is telling our controller the details of the requests it needs to handle. In our example we would like our controller to handle all requests starting with "Service". Hence the servlet-mapping:
<servlet-mapping> <!-- For the End Points -->
Step 4 involved adding the jars necessary for the code to execute:
As can be seen most of the jars are the same that we use in a normal web application. New jars of interest are:
  1. wsdl4j-1.6.1.jar - Is the reference implementation for JSR110 'JWSDL' ( allows the creation, representation, and manipulation of WSDL documents.) In this jar, the package javax.wsdl.* includes all the interfaces while the package* includes all the
  2. spring-ws-core - This is the Spring Web Services Core package.
  3. spring-xml - The jar is a utility jar that includes various XML support classes for Spring Web Services.
  4. spring-oxm -The jar provides for Object/XML Mapping, or O/X mapping. It is the act of converting an XML document to and from an object
This completes the basic project setup. We shall continue with the example in the next post.


  1. Thanks for writing such a good article, I stumbled onto your blog and read a few post. I like your style of writing... Auto Detailing Irvine

  2. BlueHost is ultimately the best hosting provider for any hosting plans you might need.