POJO Web Services using Apache Axis2

Quick Introduction

If you take a look at the source code of this document in Axis2_HOME/samples/pojoguidespring (to see how the Spring based POJO Web service is coded), you can see that the Weather class didn't change at all and the WeatherService class only got its name changed to WeatherSpringService.

You'll also notice an applicationContext.xml file, which we'll cover later. It is used to setup the beans used in our Web service.

Now you might wonder what the SpringInit.java class is for. This service is necessary to initialize the Spring Framework's application context.

The client is pretty much the same, except you won't use it to initialize the Weather data in the Web service, since Spring does that for you using Inversion of Control (IoC), which is covered next.

The Service Definition: services.xml

Since the core POJOs didn't change, you move straight to the services.xml file. It's a bit longer this time because it instantiates two services in one file (see Code Listing 7).

Code Listing 7: Defining the services: services.xml

<serviceGroup>
  <service name="SpringInit" 
class="sample.spring.service.SpringInit">
    <description>
      This web service initializes Spring.
    </description>
    <parameter name="ServiceClass">
        sample.spring.service.SpringInit
    </parameter>
    <parameter name="ServiceTCCL">composite</parameter>
    <parameter name="load-on-startup">true</parameter>
    <operation name="springInit">
      <messageReceiver 
      class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
    </operation>
  </service>
  <service name="WeatherSpringService">
    <description>
      Weather Spring POJO Axis2 AAR deployment
    </description>
    <parameter name="ServiceClass">
        sample.spring.service.WeatherSpringService
    </parameter>
    <parameter name="ServiceObjectSupplier">
org.apache.axis2.extensions.spring.receivers.SpringAppContextAwareObjectSupplier
    </parameter>
    <parameter name="SpringBeanName">
        weatherSpringService
    </parameter>
    <messageReceivers>
      <messageReceiver mep="http://www.w3.org/ns/wsdl/in-only"
      class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver"/>
      <messageReceiver mep="http://www.w3.org/ns/wsdl/in-out"
      class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>
    </messageReceivers>
  </service>
</serviceGroup>

You'll see a few familiar items in the above listing, and several changes. Once again, the items in bold are most important. The ServiceTCCL property under the SpringInit service makes sure that the Spring class loader is used for the Web service, allowing it to properly instantiate the Spring application context. The load-on-startup variable is a must-have so that the service loads up immediately on startup, creating the Spring application context. The WeatherSpringService stays similar to the WeatherService previously with a couple of additions: The ServiceObjectSupplier provides the service with the Spring application context, making it "Spring Aware."

Lastly, the SpringBeanName points to the name of the bean associated with this Web service, which is defined in the applicationContext.xml file (essentially the WeatherSpringService). We'll cover the applicationContext.xml file next. The application context, applicationContext.xml file tells the Spring Framework what beans are defined. For this example, you'll define three of them (see Code Listing 8).

Code Listing 8: Defining the application context: applicationContext.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" 
"http://www.springframework.org/dtd/spring-beans.dtd">

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

  <bean id="weatherSpringService" 
        class="sample.spring.service.WeatherSpringService">
    <property name="weather" ref="weatherBean"/>
  </bean>

  <bean id="weatherBean" class="sample.spring.bean.Weather">
    <property name="temperature" value="89.9"/>
    <property name="forecast" value="Sunny"/>
    <property name="rain" value="false"/>
    <property name="howMuchRain" value="0.2"/>
  </bean>
</beans>

The first one is Axis2's hook into Spring's application context (needed since AAR deployment is quite different from regular WAR deployment). Next, you define the bean to which the services.xml file points, which is the weatherSpringService bean that points to the WeatherSpringService class. It has one field property that gets initialized by the Spring Framework - weather. This will be set to the weatherBean. The weatherBean is an instantiation of the Weather class that holds information on the weather. Spring will initialize it to the values shown above, and set the Weather object in the WeatherSpringService class to the weatherBean instantiation. Thus, when you deploy the Web service, you won't have to instantiate the values because they'll already be set.

Next up is the SpringInit class.

Initializing the Spring Application Context: SpringInit

Without the Spring application context being initialized quickly, you'll run into problems. The SpringInit class initializes the Spring application context on startup because it is a ServiceLifeCycle class whose startUp method gets called upon loading the class (and because its load-on-startup property is set in the services.xml file). The only code worth mentioning in this class is shown in Code Listing 9.

Code Listing 9: SpringInit's startUp method

    public void startUp(ConfigurationContext ignore,
                        AxisService service) {
        ClassLoader classLoader = service.getClassLoader();
        ClassPathXmlApplicationContext appCtx = new
            ClassPathXmlApplicationContext(new String[]
                                           {"applicationContext.xml"}, 
                                           false);
        appCtx.setClassLoader(classLoader);
        appCtx.refresh();
        if (logger.isDebugEnabled()) {
            logger.debug("\n\nstartUp() set spring classloader " +
                         "via axisService.getClassLoader() ... ");
        }
    }

Note that this method retrieves the Spring class loader, and creates an application context with applicationContext.xml as the parameters. This new application context then gets the Spring class loader as its class loader. The Spring Framework is now up and ready for our WeatherSpringService.

Build and Deploy Using Apache Axis2 and Tomcat

Your POJO is now ready for primetime within the Spring Framework. Before you build, you'll first need to make sure the axis2-spring-1.8.2.jar and spring.jar files are in the project's Axis2_HOME/lib directory.

Note: The service will not deploy if you add the above .jar files to the service archive due to class loding issues.

Now build the source and create an AAR file by typing: ant

It'll be created at target/WeatherSpringService.aar. Copy it to <tomcat-home>/webapps/axis2/WEB-INF/services, and Axis2 should deploy it quickly.

Next, test the Web service to see whether Spring will really initialize the weather data for you.

Testing Using an RPCServiceClient

It's as simple as it was for the other Web service, except this time type: ant rpc.client

Feel free to browse the code for this client in src/client/WeatherSpringRPCClient.java. Essentially, this client does the same thing as the client testing the WeatherService. Except that this one skips the "Setting the weather" task since the weather data should have already been set by the Spring framework at startup.

Thus, you should get the following as output from the client:

run.client:
    [javac] Compiling 1 source file to C:\axis2-1.8.2\samples\pojoguidespring\build\cl
asses
     [java] Temperature               : 89.9
     [java] Forecast                  : Sunny
     [java] Rain                      : false
     [java] How much rain (in inches) : 0.2

Which are exactly the values you set in the applicationContext.xml file!

SR 181 Annotation support with POJO Web services

Got the JSR 181 annotated POJOs? Great. This section will show you how to package them in to a jar format for easy pojo deployment with the help of Axis2 POJO deployer. First create the JSR 181 Annotated class.

@WebService(name="JSR181TestService" targetNamespace="http://www.test.org/jsr181/Example")
@SOAPBinding(style=SOAPBinding.Style.RPC)
public class TestService {
    @WebMethod(operationName = "echoMethod")
    public String echoString(@WebParam(name="stringIn")String s){
        return s;
    }
}

        Ex: <deployer extension=".jar" directory="pojo" class="org.apache.axis2.deployment.POJODeployer"/>