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 comment:

  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