Axis2: Axis2 Web Services with Spring 3 on Tomcat

Overview:
This article looks at how you could easily integrate Spring with Apache Axis2 via a very simple example. You can find the sample source code here.

Also, you can refer to this comprehensive tutorial on integrating Apache Axis2 with Spring 3 and Hibernate 3.

Project Structure: Following diagram shows the maven project structure I have used for this post.

Step 2: Creating POJO Classes and Service Implementation
Employee.java

 package org.fazlan.employee.axis2spring.service.beans;
public class Employee {
 private Long id;
 private String firstName;
 private String lastName;
 public Long getId() {
   return id;
 }
 public void setId(Long id) {
   this.id = id;
 }
 public String getFirstName() {
   return firstName;
 }
 public void setFirstName(String firstName) {
   this.firstName = firstName;
 }
 public String getLastName() {
   return lastName;
 }
 public void setLastName(String lastName) {
   this.lastName = lastName;
 }
}

IService.java - The Service Interface.

 package org.fazlan.employee.axis2spring.service.services;
import java.util.List;
/**
* Created by IntelliJ IDEA.
* User: fazlan
* Date: 3/9/12
* Time: 4:36 PM
* To change this template use File | Settings | File Templates.
*/
public interface IService<T> {
 Long add(T t);
 boolean update(T t);
 boolean delete(Long id);
 T get(Long id);
 List<T> getAll();
}  

EmployeeService.java - Implementation of the Service

 package org.fazlan.employee.axis2spring.service.services;
import org.fazlan.employee.axis2spring.service.beans.Employee;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
public class EmployeeService implements IService<Employee> {
 private static Long ID = 0L;
 private Map<Long, Employee> employeeDao;
 public Long add(Employee employee) {
   employee.setId(++ID);
   update(employee);
   return ID;
 }
 public boolean update(Employee employee) {
   employeeDao.put(employee.getId(), employee);
   return true;
 }
 public boolean delete(Long id) {
   return employeeDao.remove(id) instanceof Employee;
 }
 public Employee get(Long id) {
   return employeeDao.get(id);
 }
 public List<Employee> getAll() {
   return new ArrayList<Employee>(employeeDao.values());
 }
 public void setEmployeeDao(Map<Long, Employee> employeeDao) {
   this.employeeDao = employeeDao;
 }
}

Step 4: Creating the Spring Lifecycle Management to Allow Axis2 to Aanage the Lifecycle of the Spring Services.
EmployeeSpringInit.java

 package org.fazlan.employee.axis2spring.service.services;
import org.apache.axiom.om.OMElement;
import org.apache.axis2.context.OperationContext;
import org.apache.axis2.context.ServiceContext;
import org.apache.axis2.engine.ServiceLifeCycle;
import org.apache.axis2.context.ConfigurationContext;
import org.apache.axis2.description.AxisService;
import org.springframework.context.support.ClassPathXmlApplicationContext;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
public class EmployeeSpringInit implements ServiceLifeCycle {
 private static Log logger = LogFactory
   .getLog(EmployeeSpringInit.class);
  /**
  * this will be called during the deployement time of the service. irrespective
  * of the service scope this method will be called
  */
 public void startUp(ConfigurationContext ignore, AxisService service) {
   ClassLoader classLoader = service.getClassLoader();
   ClassPathXmlApplicationContext appCtx = new
     ClassPathXmlApplicationContext(new String[] {"classpath:spring/spring-app-context.xml"}, false);
   appCtx.setClassLoader(classLoader);
   appCtx.refresh();
   if (logger.isDebugEnabled()) {
     logger.debug("\n\nstartUp() set spring classloader via axisService.getClassLoader() ... ");
   }
 }
 /**
  * this will be called during the deployement time of the service. irrespective
  * of the service scope this method will be called
  */
 public void shutDown(ConfigurationContext ignore, AxisService service) {
 }
}

This loads the Spring bean configuration from classpath:spring/spring-app-context.xml.

Step 5: Configuring the Spring Beans and Wiring the Service Implementation (spring/spring-app-context.xml)
This is the Spring bean definition file in our application containing all the beans required to run the application.

The following is very important, this class and the spring bean needed to wire it could be used as an alternative to getting the ApplicationContext from the ServletContext.

 <bean id="applicationContext"
 class="org.apache.axis2.extensions.spring.receivers.ApplicationContextHolder" />

The complete Spring bean definition file,

 <beans xmlns="http://www.springframework.org/schema/beans"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:util="http://www.springframework.org/schema/util"
   xsi:schemaLocation= "http://www.springframework.org/schema/beans
              http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
              http://www.springframework.org/schema/util
              http://www.springframework.org/schema/util/spring-util-3.0.xsd">
 <bean id="applicationContext"
 class="org.apache.axis2.extensions.spring.receivers.ApplicationContextHolder" />
 <bean id="employeeSpringService" class="org.fazlan.employee.axis2spring.service.services.EmployeeService">
   <property name="employeeDao" ref="employeeDao"/>
 </bean>
 <util:map id="employeeDao"
      key-type="java.lang.Long"
      value-type="org.fazlan.employee.axis2spring.service.beans.Employee">
   <entry key="1" value-ref="emp1" />
   <entry key="2" value-ref="emp2" />
   <entry key="3" value-ref="emp3" />
 </util:map>
 <bean id="emp1" class="org.fazlan.employee.axis2spring.service.beans.Employee">
   <property name="id" value="1" />
   <property name="firstName" value="Apache" />
   <property name="lastName" value="Axis2" />
 </bean>
 <bean id="emp2" class="org.fazlan.employee.axis2spring.service.beans.Employee">
   <property name="id" value="2" />
   <property name="firstName" value="Apache" />
   <property name="lastName" value="Spring" />
 </bean>
 <bean id="emp3" class="org.fazlan.employee.axis2spring.service.beans.Employee">
   <property name="id" value="3" />
   <property name="firstName" value="Apache" />
   <property name="lastName" value="Tomcat" />
 </bean>
</beans>

Here, I am using an instance of java.util.Map to mock the database.

Step 6: Defining your Axis2 Service Configuration (META-INF/services.xml)
EmployeeSpringInit Service: Loading the Spring context

  <service name="EmployeeSpringInit" class="org.fazlan.employee.axis2spring.service.services.EmployeeSpringInit">
 <description>
  This web service initializes Spring.
 </description>
 <parameter name="ServiceClass" >org.fazlan.employee.axis2spring.service.services.EmployeeSpringInit</parameter>
 <parameter name="ServiceTCCL" >composite</parameter>
 <parameter name="load-on-startup" >true</parameter>
</service>

Here, we use this service to load the Spring context at the startup of the application.

EmployeeService - The actual service definition.

 <service name="EmployeeService">
 <description>
  Weather Spring POJO Axis2 AAR deployment
 </description>
 <parameter name="ServiceClass" >org.fazlan.employee.axis2spring.service.services.EmployeeService</parameter>
 <parameter name="ServiceObjectSupplier" >org.apache.axis2.extensions.spring.receivers.SpringAppContextAwareObjectSupplier</parameter>
 <excludeOperations>
     <operation>setEmployeeDao</operation>
 </excludeOperations>
 <parameter name="SpringBeanName" >employeeSpringService</parameter>
 <parameter name="SpringContextLocation">spring/spring-app-context.xml</parameter>
 <messageReceivers>
  <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-only"
           class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver"/>
  <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out"
           class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>
 </messageReceivers>
</service>

NOTE: I have excluded setEmployeeDao() as a web method.

By default, the Axis2 Engine will look for /applicationContext.xml to load the Spring bean configurations.

You can change this by either defining the following property.

 <parameter name="SpringContextLocation">spring/spring-app-context.xml</parameter>

This tells the Axis2 Engine where to locate the Spring application context file for this service. This is very useful when you have multiple Spring application services in the same Axis3 Engine.
Or,
You can place the Spring configuration file alongside the service.xml as in the following format. Axis2 Engine will implicitly detect this.

META-INF/<service-name>-application-context.xml

Putting all together,

 <serviceGroup>
 <service name="EmployeeSpringInit" class="org.fazlan.employee.axis2spring.service.services.EmployeeSpringInit">
 <description>
  This web service initializes Spring.
 </description>
 <parameter name="ServiceClass" >org.fazlan.employee.axis2spring.service.services.EmployeeSpringInit</parameter>
 <parameter name="ServiceTCCL" >composite</parameter>
 <parameter name="load-on-startup" >true</parameter>
</service>
<service name="EmployeeService">
 <description>
  Weather Spring POJO Axis2 AAR deployment
 </description>
 <parameter name="ServiceClass" >org.fazlan.employee.axis2spring.service.services.EmployeeService</parameter>
 <parameter name="ServiceObjectSupplier" >org.apache.axis2.extensions.spring.receivers.SpringAppContextAwareObjectSupplier</parameter>
 <excludeOperations>
     <operation>setEmployeeDao</operation>
 </excludeOperations>
 <parameter name="SpringBeanName" >employeeSpringService</parameter>
 <parameter name="SpringContextLocation">spring/spring-app-context.xml</parameter>
 <messageReceivers>
  <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-only"
           class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver"/>
  <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out"
           class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>
 </messageReceivers>
</service>
</serviceGroup>

Step 7: Building the Project
mvn clean install

Step 8: Deploying the Service
Now you can deploy this service on to any container. Here we'll deploy this on Tomcat server.

You need to copy the following *.jars to /axis2/WEB-INF/lib/ directory (e;i: /home/fazlan/apache-tomcat-6.0.32/webapps/axis2/WEB-INF/lib/)in your Axis2 WAR already deployed on Tomcat.

Spring 3.1.1.RELEASE jars
spring-aop-3.1.1.RELEASE.jar
spring-asm-3.1.1.RELEASE.jar
spring-beans-3.1.1.RELEASE.jar
spring-context-3.1.1.RELEASE.jar
spring-context-support-3.1.1.RELEASE.jar
spring-core-3.1.1.RELEASE.jar
spring-expression-3.1.1.RELEASE.jar
spring-jdbc-3.1.1.RELEASE.jar
spring-orm-3.1.1.RELEASE.jar
spring-tx-3.1.1.RELEASE.jar
spring-web-3.1.1.RELEASE.jar

Once, all the above *.jars are copied to /axis2/WEB-INF/lib/ on Tomcat. We are good to deploy the service and test.

Now you can deploy this service on to any container. Here we'll deploy this on Tomcat server.
If you have not already done, extract the axis2.war that comes with the Apache Axis2 distribution and deploy to Tomcat server.
You can verify the deployment http://localhost:8080/axis2/
Once verified the successful deployment of the Axis2 web archive on Tomcat, you can deploy the *.aar file.
- Either via http://localhost:8080/axis2/axis2-admin/ or,
- Manually copying the *.aar file to <$TOMCAT_HOME>/webapps/axis2/WEB-INF/services

You can also list down the existing Axis2 services via http://localhost:8080/axis2/services/listServices

After successfully deploying the service, you can access the service via http://localhost:8080/axis2/services/EmployeeService?wsdl

Step 9: Testing the Services via SOAP UI.

Option 1: Testing REFTful endpoint using CURL
Install CURL
sudo apt-get install curl

Now, after successfully installing CURL, we are ready to test the services.
Issue the following commands on the terminal.

POST a Resource: Adding a new employee resource.
- Adding the new employee record in the add.xml file.

 <ns:add xmlns:ns="http://services.service.axis2spring.employee.fazlan.org">
    <ns:employee xmlns:ax21="http://beans.service.axis2spring.employee.fazlan.org/xsd"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ax21:Employee">
         <ax21:firstName>My FirstName</ax21:firstName>
         <ax21:id>1</ax21:id>
         <ax21:lastName>My LastName</ax21:lastName>
    </ns:employee>
</ns:add>

 curl -v -H "Accept: application/xml" -H "Content-type: application/xml" -X POST -d @add.xml http://localhost:8080/axis2/services/EmployeeService/add

GET Resource:
- Retrieving all the employee resources.

 curl -v http://localhost:8080/axis2/services/EmployeeService/getAll

- Retrieving a employee resource for a given id(id = 1).

 curl -v http://localhost:8080/axis2/services/EmployeeService/get?id=1

PUT a Resource: Updating an existing employee resource.
- Updating an existing employee record in the update.xml file.

 <ns:update xmlns:ns="http://services.service.axis2spring.employee.fazlan.org">
    <ns:employee xmlns:ax21="http://beans.service.axis2spring.employee.fazlan.org/xsd"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ax21:Employee">
         <ax21:firstName>Update FirstName</ax21:firstName>
         <ax21:id>1</ax21:id>
         <ax21:lastName>Update LastName</ax21:lastName>
    </ns:employee>
</ns:update>

 curl -v -H "Accept: application/xml" -H "Content-type: application/xml" -X PUT -d @update.xml http://localhost:8080/axis2/services/EmployeeService/update

DELETE a Resource: Deleting an employee for a given id (id=1)

 curl -v http://localhost:8080/axis2/services/EmployeeService/delete?id=1

Option 2: Testing SOAP endpoints using SOAP UI.
Use the service URL(http://localhost:8080/axis2/services/EmployeeService?wsdl) and create a project on SOAP UI.


Summary:
Aixs2 is a fast Web Service Engine that enables us to deploy Web Services on any Web Container. Axis2 allows us to make use of these features by allowing us to integrate Spring.
You can find the sample source code here.