WSO2 WSAS and Spring Integration

Submitted on January 16, 2008 - 07:08. Story :

Articles

Realm :

Architecture

Project :

The purpose of this article, by Saminda Abeyruwan, is to provide in depth understanding of Spring integration in WSO2 WSAS and to discuss how to expose an existing POJO driven application as a Web service.

Introduction

There is a burgeon acceptance in the enterprise world today for Web services, especially, existing applications with business functions to be exposed as Web services. Thus, there should be a design pattern or principle that exposes these functions, securely, reliably, and easily as Web services.

Spring is a one-stop shop technology, enabling you to build applications using Plain Old Java Objects (POJO). Hence, it enables you to develop business logic as POJOs, where the framework itself takes care of many of the value addition features related to the business application. Since, there is no dependency between the business logic and infrastructure concern, your code base is shielded from the underlying infrastructure changes. Thus, Spring enables you to implement simplest possible solution to your application, which is the main reason why it is popular among many developers.

Applies To

WSO2 Web Services Application Server	v2.1 and upward
J2SE	v1.4 or v1.5
Operating Systems	MS Windows, Linux and McOS
Spring Framework	v1.2.8 or higher

Web Service Creation

The notion of a Web service consists of skeletons and stubs. The skeleton represents the server side business logic, where as the stub represents the client side Web service logic. The starting point of the Web service is the skeleton. Hence, the Web service can be created by using either the contract first (top-down approach) or code first (bottom-up approach).

In the contract first approach, you have to write a WSDL first and generate skeletons and stubs from it. Once the skeleton is generated, the Web service developer has to insert the business logic into it. The other approach is the bottom-up approach or the code first approach, which is the most common Web service development model. The Web service developer will give a pre-written Java class and expect the underlying framework to expose it as a Web service while generating the WSDL for the current implementation.

WSO2 WSAS and Axis2

WSO2 WSAS is the enterprise ready Web services engine powered by Apache Axis2. It is a lightweight application server for Web services that incorporates leading open source components into a simple, easy-to-use and highly performant package [5]. Hence, the developer will be equipped with all the Axis2 features.

Before going any further, you need to set up WSAS in your development arena. If you have not already download WSAS, you can download it from the WSAS Downloads page [6]. Once WSAS has been downloaded, follow these steps to start WSAS.

Linux :

unzip wso2wsas-2.1.zip
cd wso2wsas-2.1/bin
./wso2wsas.sh

MS Windows :

<unzip> wso2wsas-2.1.zip
cd wso2wsas-2.1/bin
wso2wsas.bat

Code Listing 1: Starting WSAS in a Linux/MS Windows Environment

Programming Flow

AAR (Axis Archive) is the typical mode of Web services deployment in WSAS. Each AAR includes its services.xml. Let's look at a simple services.xml.

<serviceGroup>
  <service name="MyService">
        <parameter name="ServiceClass">MyService</parameter>
   </service>
</serviceGroup>

Listing 2 : Simple services.xml

Listing 2 represents the minimum items that should be present in a services.xml in order to expose the "MyService" class as a Web service. As you can see, @name="ServiceClass" will provide the hook in the POJO that needs to be exposed as a Web service.

In our situation, Spring framework will provide the business class that should be exposed as a Web service. Thus, we need a way to instruct WSAS to locate the business class. This is achieved by a parameter named @name="ServiceObjectSupplier", in services.xml.

Parameter @name="ServiceObjectSupplier"

The parameter @name="ServiceObjectSupplier", is the starting point to inject a POJO from a underline infrastructure, such as Spring etc. This parameter will be located inside the <service/> tag. Analogous to any design pattern, prior parameter has several unique semantics. Let's look at them,

The default way of selecting a POJO for a Web service, is to list it inside <service/> tag with a parameter that has a attribute named "ServiceClass". The other method is to have a parameter with a attribute named "ServiceObjectSupplier". If there is a parameter with @name, and if the value of the @ is "ServiceObjectSupplier", there should not be a parameter in this <service/> section with the @name with the value "ServiceClass". If the latter is present, during deployment and runtime, the @name "ServiceClass" will be selected and the former will be discarded.
The text node associated with this parameter should contain a full qualified name of a class that implements the org.apache.axis2.description.AxisService.ServiceObjectSupplier.
There should be a mandatory parameter with @ "SpringBeanName", which will provide the name of the Spring bean to be exposed.
There should be a mandatory parameter with @ "SpringContextLocation", which will provide the location in which the Spring application context should be loaded. The location should be coming from the class path.

Let's see an example,


<serviceGroup>
    <service name="calculator"> 
  <parameter name="ServiceObjectSupplier">org.wso2.wsas.admin.service.spring.GenericApplicationContextSupplier</parameter>
  <parameter name="SpringBeanName">calculator</parameter> 
 <parameter name="SpringContextLocation">spring/context.xml</parameter>
    </service>
</serviceGroup>

Listing 3 : Sample services.xml with Spring Integration.

Spring Integration in WSO2 WSAS

Listing 3 represents a typical services.xml that has been configured to load Spring beans. The handy thing about WSAS is that the developer dose not need to know any prior configuration, it is all taken care of by WSAS, yet the developer should know what is going on under the hood.

Let's start with the @ named "ServiceObjectSupplier". As you can see the parameter that contains this @ has a text node of org.wso2.wsas.admin.service.spring.GenericApplicationContextSupplier. This is the default service object supplier given by WSAS. It has the ability to load Spring beans from the Spring configuration file and expose the specified bean in @ SpringBeanName as the Web service.

The other most import entity is the message receiver. We recommend the use of the org.apache.axis2.rpc.receivers.RPCMessageReceiver and org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver message receivers, because it has the power to generate the WSDL out of the given POJO. Hence, the WSAS specific service object supplier will provide the POJO that needs to be exposed as a Web service and the previously mentioned message receivers will take care of the WSDL generation. I will talk about the obstacles involved in using other message receivers and service object suppliers coming from Axis2 later in this article and how to overcome some of the problems associated with them.

WSO2 WSAS in Action

(1). As shown in listing 1, start WSAS in your favourite browser and and Sign in with the username/password "admin/admin".

Figure 1: WSAS home page.

2. Go to "Services" and click "Upload Spring service."

WSAS Upload Spring service

Figure 2: Upload Spring Service

(3). Upload the spring configuration file and its related beans. Sample code is available here [4].

WSAS Spring upload - Upload artifacts

Figure 3: Uploading the Spring Configuration File and its beans jar

(4). Select the bean you want to expose as a Web Service

Select beans Figure 4: Selecting Spring Beans to be Exposed as Web services

(5). Now you will be able to see the deployed service after approximately 10 seconds.

Final result

Figure 6: Loaded Spring Bean.

(6). Click "calculator", then "Try it" and then try the new Web service.

Analyzing the Sample

The above sample has used the following Spring configuration file.

<?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="calculator" class="org.wso2.samples.Calculator"></bean>
 <bean id="mybean" class="org.wso2.samples.MyBean"></bean>
</beans>

Listing 4: Sample Spring Configuration File

Listing 4 contains a very basic Spring configuration. If the developer has come up with a complex Spring configuration, he could apply the same semantics.

Axis2 Spring Support

WSAS Spring support is an extension from Axis2. Axis2 has two modes for configuring Spring.

1. With a servlet context
2. Without a servlet context.

In the first method, the developer will not get the advantage of hot deployment. The developer has to restart the server when he needs to expose the new Spring bean. In this mode, the developer will have the privilege of using one application context, and the addition should be amended to it. In the second method, the developer has to manually load the application context from the class path or should have put the hold bean in the application context. For more information refer to [3].

Conclusion

WSO2 WSAS will provide the facility to expose Spring beans as Web services with zero code, by merely extending Axis2's service object supplier. After the Spring bean has been exposed as a Web service, the developer will be able to apply all other WSAS functionalities such as security, reliability and so on.