Spring Web Services Using JAXB

Spring Web Services Example Easy Steps.....

Just a glimpse........

Spring Web Services is a product from Spring community to develop the web services in easier manner. Spring Web Services is following the strategy of contract-first web services. It focuses more on XML and lesser on Java implementation. In this article, we will learn how to write a simple web service application using Spring Web Services. It is expected that the reader has a fair amount of knowledge on Web services concepts before continuing with the article along with the basics of Spring Framework like Dependency Injection and Inversion of Control.

Spring Web Services Example :

In this article, we will design a simple application that'll ask for an employee id(consisting of two characters and five digits, e.g ab12345) and will return the employee details(here name & email id, e.g. Sidhartha Ray & ab@yahoo.co.in) using Spring Web Service in Eclipse IDE. This article will provide the content in a tutorial fashion in a step-by-step manner and parallely giving relevant details to that section. Generally speaking, developing web services involves writing artifacts in the server and the client tier. We will look into the details about those artifacts in the subsequent sections. Given below are the pre-requisite softwares to develop and run the application
1.Java Development Kit (1.6 or later)
2.Spring Web Service Framework (1.5.9)
3.Eclipse3.4 or later (add plugin jaxb 2.0 or later)
4.Web Server(Apache Tomcat 6)

And the following jar files
1.commons-logging-1.1.1.jar
2.spring.jar
3.spring-beans.jar

4.spring-web.jar

5.spring-webmvc.jar

6.spring-ws-core-1.5.9.jar

7.spring-ws-core-tiger-1.5.9.jar

8.spring-ws-support-1.5.9.jar

9.spring-xml-1.5.9.jar

10.spring-oxm-1.5.9.jar
11.spring-oxm-tiger-1.5.9.jar
12.spring-ws-security-1.5.9.jar(optional)

(N.B. Get all the above jars by downloading spring framework 2.5.6 & spring web services 1.5.9)

Server-side artifacts :

The following steps are provided in building up the various server-side artifacts.
1.Contract Design
2.Defining the service interface
3.Implementing the service interface
4.Defining Spring Web-Service endpoints
5.Configuring deployment descriptor.
6.Configuring Spring’s Application Context.

Remember to build the server tier as a web application(Dynamic Web Project in Eclipse IDE), so that it can be made runnable in any web server.

Application folder structure in eclipse'll look like :

1.Contract design :

We will design the contract for the service through xml, i.e. a .wsdl(Web Service Description Language) file. The contract defines the input and the output messages that a service expects. Since we wanted to enforce restriction on the input and output, we will provide an XSD, i.e. a.xsd(XML Schema Definition) file. In our case, the request and the response messages will be simple string objects. The following definitions define the .xsd file & .wsdl file:

Employee.xsd

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:tns="http://employee.com/schema" elementFormDefault="qualified"
   targetNamespace="http://employee.com/schema">
   <xsd:element name="EmployeeDetailsRequest">
       <xsd:complexType>
           <xsd:sequence>
               <xsd:element ref="tns:empId" />
           </xsd:sequence>
       </xsd:complexType>
   </xsd:element>
   <xsd:element name="EmployeeDetailsResponse">
       <xsd:complexType>
           <xsd:sequence>
               <xsd:element name="name" type="xsd:string" />
               <xsd:element name="email" type="xsd:string" />
           </xsd:sequence>
       </xsd:complexType>
   </xsd:element>
   <xsd:element name="empId">
       <xsd:simpleType>
           <xsd:restriction base="xsd:string">
               <xsd:pattern value="[a-z]{2}[0-9]{5}" />
           </xsd:restriction>
       </xsd:simpleType>
   </xsd:element>
</xsd:schema>

Now you can generate the service artifacts or jaxb classes by following steps :

i.) Right click on .xsd file >> select JAXB 2.0 >> select Run XJC >>(a pop up will appear) Give Package Name as "com.employee.schema" Output Directory as project's src directory >> Select Finish

ii.) Refresh your project directory and you'll find following four classes :

Employee.wsdl

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<wsdl:definitions xmlns:emp="http://employee.com/schema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="http://employee.com/employee" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" name="Employee" targetNamespace="http://employee.com/employee">
   <wsdl:types>
       <xsd:schema targetNamespace="http://employee.com/employee">
           <xsd:import namespace="http://employee.com/schema" schemaLocation="Employee.xsd"/>
       </xsd:schema>
   </wsdl:types>
   <wsdl:message name="EmployeeDetailsRequest">
       <wsdl:part element="emp:EmployeeDetailsRequest" name="EmployeeDetailsRequest"/>
   </wsdl:message>
   <wsdl:message name="EmployeeDetailsResponse">
       <wsdl:part element="emp:EmployeeDetailsResponse" name="EmployeeDetailsResponse"/>
   </wsdl:message>
   <wsdl:portType name="EmployeePortType">
       <wsdl:operation name="EmployeeDetails">
           <wsdl:input message="tns:EmployeeDetailsRequest"/>
           <wsdl:output message="tns:EmployeeDetailsResponse"/>
       </wsdl:operation>
   </wsdl:portType>
   <wsdl:binding name="EmployeeSOAPBinding" type="tns:EmployeePortType">
       <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
       <wsdl:operation name="EmployeeDetails">
           <soap:operation soapAction="http://employee.com/employee/EmployeeDetails"/>
           <wsdl:input>
               <soap:body use="literal"/>
           </wsdl:input>
           <wsdl:output>
               <soap:body use="literal"/>
           </wsdl:output>
       </wsdl:operation>
   </wsdl:binding>
   <wsdl:service name="EmployeeService">
       <wsdl:port binding="tns:EmployeeSOAPBinding" name="Employee">
           <soap:address location="http://localhost:8888/EmployeeWS/services/Employee"/>
       </wsdl:port>
   </wsdl:service>
</wsdl:definitions>

2.Defining the service interface :

Defining the service interface - The service interface represents the client-facing interface for invoking the service by passing in the required inputs. Note that the interface will be a simple POJO, the interface doesn’t need to extend or implement any of the spring web-service related APIs. In this example, the input will be a simple java string object.

EmployeeService.java

package com.employee.service;

import com.employee.schema.EmployeeDetailsRequest;
import com.employee.schema.EmployeeDetailsResponse;

public interface EmployeeService {
EmployeeDetailsResponse getEmployeeDetails(EmployeeDetailsRequest request);
}

3.Implementing the service interface :

Implementing the service interface - Writing the implementation for the above service interface will be fairly straight-forward. It returns an EmployeeDetailsResponse object with name : Sidhartha Ray & Email : ab@yahoo.co.in if employee id is ab12345, else returns with name : Nitesh Yetta & Email : xy@yahoo.co.in.

EmployeeServiceImpl.java

package com.employee.service;

import com.employee.schema.EmployeeDetailsRequest;
import com.employee.schema.EmployeeDetailsResponse;

public class EmployeeServiceImpl implements EmployeeService{

    @Override
    public EmployeeDetailsResponse getEmployeeDetails(
           EmployeeDetailsRequest request) {
       EmployeeDetailsResponse response = new EmployeeDetailsResponse();
       if(request.getEmpId().equalsIgnoreCase("ab12345")){   //two char & five digits
           response.setEmail("ab@yahoo.co.in");
           response.setName("Sidhartha Ray");
       }else{
           response.setEmail("xy@yahoo.co.in");
           response.setName("Nitesh Yetta");
       }
       return response;
    }
}

4.Defining Spring Web-Service endpoint :

Defining endpoints - Endpoints are components for processing the input request messages and are usually responsible for invoking the desired service by passing in the required details. Spring Web Services implementation comes with two flavors of endpoints – message endpoints and payload endpoints. Message endpoints provide access to the raw input XML message including the XML header along with the XML body. On the other hand, Payload endpoints are useful in dealing with the XML body alone. In our simple application, we will define a Payload endpoint for parsing the input XML message for invoking the service.

EmployeeDetailsEndpoint.java

package com.employee.endpoint;

import org.springframework.oxm.Marshaller;
import org.springframework.ws.server.endpoint.AbstractMarshallingPayloadEndpoint;
import com.employee.schema.EmployeeDetailsRequest;
import com.employee.service.EmployeeService;

public class EmployeeDetailsEndpoint extends AbstractMarshallingPayloadEndpoint{
    private EmployeeService service;
    public EmployeeDetailsEndpoint(EmployeeService service,
            Marshaller marshaller) {
        super(marshaller);
        this.service = service;
    }
    @Override
    protected Object invokeInternal(Object arg0) throws Exception {
        return service.getEmployeeDetails((EmployeeDetailsRequest)arg0);
    }
}

Here as we want to use JAXB for marshalling/unmarshalling, we have gone through AbstractMarshallingPayloadEndpoint.
The method invokeInternal will be called when an XML request is received by the framework and the whole xml content will be available in the requestElement. The rest of the code does the job of finding the request string from the input XML, invoke the employee service and then constructs the appropriate XML response.

5.Configuring deployment descriptor :

The web application’s deployment descriptor must be configured with a servlet that is capable of dispatching web service message to the appropriate handler. This happens to be the MessageDispatcherServlet servlet.

web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" id="WebApp_ID" version="2.5">
<display-name>EmployeeWS</display-name>
<servlet>
   <servlet-name>EmployeeWS</servlet-name>
   <servlet-class>org.springframework.ws.transport.http.MessageDispatcherServlet</servlet-class>
   <init-param>
       <param-name>contextConfigLocation</param-name>
       <param-value>/WEB-INF/spring/context/ApplicationContext.xml</param-value>
   </init-param>
</servlet>
<servlet-mapping>
   <servlet-name>EmployeeWS</servlet-name>
   <url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app>

In the above XML, we have routed all requests to the servlet spring-ws-service which in-turns maps to MessageDispatcherServlet. The above dispatcher servlet will search for a configuration file representing the spring application context for looking up the definition for various spring beans. By default, the name of the configuration file will be derived from the servlet name. If the name of the servlet is xyz, then the name of the configuration file will be xyz-servlet.xml. In our case, the configuration file will be spring-ws-servlet.xml. We can also give any name to the Spring Configuration File by just adding the following init-param to the MessageDispatcherServlet :

<init-param>

<param-name>contextConfigLocation</param-name>

<param-value>/WEB-INF/spring/context/ApplicationContext.xml</param-value>

</init-param>

6.Configuring Spring’s Application Context :

The minimal requirement of the spring application configuration file that resides in a web server is to contain the following entries:
i Endpoints definition
ii Endpoint mappings definition
iii WSDL Definition

spring-ws-servlet.xml

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:oxm="http://www.springframework.org/schema/oxm"
   xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
       http://www.springframework.org/schema/oxm http://www.springframework.org/schema/oxm/spring-oxm-1.5.xsd">
   
   <bean id="EmployeeService"
       class="org.springframework.ws.wsdl.wsdl11.SimpleWsdl11Definition">
       <constructor-arg value="/wsdl/Employee.wsdl" />
   </bean>
   <oxm:jaxb2-marshaller id="marshaller"
       contextPath="com.employee.schema" />
   <oxm:jaxb2-marshaller id="unmarshaller"
       contextPath="com.employee.schema" />
   
   <bean name="service" class="com.employee.service.EmployeeServiceImpl" />
   <bean id="employeeDetailsEndpoint" class="com.employee.endpoint.EmployeeDetailsEndpoint">
       <constructor-arg ref="service" />
       <constructor-arg ref="marshaller" />
   </bean>
   <bean name="endPointMapping"
       class="org.springframework.ws.server.endpoint.mapping.PayloadRootQNameEndpointMapping">
       <property name="mappings">
           <props>
               <prop key="{http://employee.com/schema}EmployeeDetailsRequest">employeeDetailsEndpoint</prop>
           </props>
       </property>
   </bean>
</beans>

Now Deploy the application into tomcat server & hit the url to see the .wsdl:

http://<server-address>:<port>/EmployeeWS/services/EmployeeService.wsdl

e.g., http://localhost:8888/EmployeeWS/services/EmployeeService.wsdl

http://<server-address>:<port>/EmployeeWS/<MessageDispatcherServlet_name_from_deployment_descriptor>/<wsdl_bean_name_from_spring_app_context>.wsdl

e.g., http://localhost:8888/EmployeeWS/EmployeeWS/EmployeeService.wsdl

B. Test service Using soapUI