Hello World with WSO2 WSF/Spring

The tutorial by Tharindu Mathew explains, how to expose beans defined in the Spring Framework as Web services, using WSO2 WSF/Spring. It is assumed that the reader has a basic knowledge on the Spring Framework. Prior knowledge in Apache Axis2 is NOT required.

The complete Web project with the source is available here.

Applies To

Content

1. Introduction
2. Getting Started
3. Step 1 - Setting up a Web Project
4. Step 2 - Configuring the web.xml
5. Step 3 - Writing the Hello World Class
6. Step 4 - Initializing the Spring Bean
7. Step 5 - Exposing it as a Web Service
8. Conclusion

Introduction

WSF/Spring was designed to develop Web services in a code first approach, a simple and efficient way for the Spring user to expose Web services. It uses the Axis2 Web service engine for the deployment of Web services.

This means that it inherits all the power and versatility of Axis2, which has implemented most of the WS-* specifications. And now as a Spring user, this power is at your disposal.

Getting Started

The following components are used in this tutorial :

1. JDK 1.5 or later

2. Spring 2.0.7 or later

3. Tomcat 5.5.x

4. WSF/Spring 1.0 beta or later

5. Any IDE supporting Java (Eclipse WTP 3.3 is used in this tutorial)

A Spring Web application is deployed inside a servlet container (i.e. Tomcat 5.5). This tutorial uses the same model and creates a Web application to expose a Web service.

Step 1 – Setting up a Web Project

1. Let's create a Web project. In Eclipse, this is done by File > New > Project... .

2. Then in the dialog box that appears choose Web > Dynamic Web Project. Click Next and enter “WSFSpringHelloWorld” as the project name.

3. Make sure the target runtime is compliant with JDK 1.5 (if Tomcat is the server you are using, then it should be Apache Tomcat 5.5) and click Finish.

4. Copy the axis2-web/ directory provided in the WSF/Spring distribution into the Web Content directory.

5. Copy the axis2Config.xml provided in the distribution into the project's WEB-INF/ directory.

6. Copy the jars included in the WEB-INF/lib directory into the project's WEB-INF directory.

 NOTE : The spring jars relevant to the servlet container you use, should be in lib/ directory (For Tomcat, these are spring-2.x.x.jar and spring-tomcat-weaver-2.x.x.jar)

Illustration 1 - Initial hierachy of the web project

Step 2 – Configuring the web.xml

The following entries should be inserted into the Web project's web.xml:

<listener>
	<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>

<context-param>
	<param-name>contextConfigLocation</param-name>
	<param-value>/WEB-INF/applicationContext.xml</param-value>
</context-param>

<servlet>
	<servlet-name>axis2</servlet-name>
	<servlet-class>
		org.wso2.spring.ws.servlet.SpringAxis2Servlet
	</servlet-class>
	<load-on-startup>1</load-on-startup>
</servlet>

<servlet-mapping>
	<servlet-name>axis2</servlet-name>
	<url-pattern>/axis2/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
	<servlet-name>axis2</servlet-name>
	<url-pattern>/services/*</url-pattern>
</servlet-mapping>

<welcome-file-list>
	<!--
	<welcome-file>index.jsp</welcome-file>
	-->
	<welcome-file>/axis2-web/index.jsp</welcome-file>
</welcome-file-list>

It is assumed that the Spring application context is applicationContext.xml and is located in the WEB-INF/ directory.

The location of this context is passed as a parameter through the ContextLoaderListner to initialize the SpringAxis2Servlet. Rest of the entries are standard Web xml entries to initialize the servlet. The welcome-file list entry is not essential. But you can make use of it to see whether the Web service is properly deployed, and also, to look at the wsdl. This will be further illustrated later.

Step 3 – Writing the Hello World class

Now after completing the initial configuration, let's say hello to the world! The class HelloWorld was created inside a package named “com.hello”.

package com.hello;

public class HelloWorld {

private String name;

public String getName() {
    return name;
}

public void setName(String name) {
    this.name = name;
}


public String sayHello(String name) {
    return name + "says Hello World!";
}

}

Step 4 – Initialize the Spring bean

Now, let's initialize these values in the application context:

<bean id="helloworld" class="com.hello.HelloWorld">
     
	<property name="name" value="Tharindu Mathew"></property>

</bean>

Step 5 – Exposing it as a web service

You must've noticed, that up to this step what we've done is basic Spring and Web xml configuration. Only from this step that we will be actually using, the WSF/Spring framework.

Next, we have to import the axis2Config.xml to the application context.

	<import resource="axis2Config.xml"/>

A knowledge of Axis2 is not needed in this tutorial but using Spring beans to boot up Axis2 is a feature that the WSF/Spring framework provides. The Axis2 startup configuration can be edited in Spring just like a user edits Spring beans. This means a user can customize the Axis2 Web services' engine through Spring itself. Please refer this article for more about Axis2 and its architecture.

Now let's get back to creating a Web service, inserting the following lines in your application context:

<bean id="services" class="org.wso2.spring.ws.WebServices">
    <property name="services">
    <list>
   	 <bean id="helloService" class="org.wso2.spring.ws.SpringWebService">       
            <property name="serviceBean" ref="helloworld"></property>
            <property name="serviceName" value="helloWorldService"></property>
         </bean>
    </list>
    </property>
</bean>

We define a Web services bean and in that we list the beans we want to expose as services. Since the “helloworld” bean is what we want to expose, we list it as a Spring Web service bean in this list. The service name field is mandatory as it decides how the URL of the web service, i.e. the access point of the service.

Note : You can't have more than once WebService bean. All beans you want to expose should be listed in the services list of the Web service bean as SpringWebService beans.

That's it! We're done making our hello world Web service. Now let's see how it looks.

Create a WAR out of your Web project (In Eclipse this is done by, right-clicking on the project, Select Export... > Web > WAR). Drop the WAR into the webapp directory of your servlet container (ex :- Tomcat 5.5). Point your browser to http://localhost:8080/WSFSpringHelloWorld (Assuming your server is hosted on port 8080 of localhost). Click on service and you should see the service listed under helloworldWebService. Click on that and you can see the wsdl for the Web service.

Illustration 2 - Axis2 home page

Illustration 3 - helloWorldService

Illustration 4 - WSDL of the hello world service

Conclusion

This brings us to the end of this tutorial. I have explained how easy it is to expose a Spring bean as a web service with this framework. I hope to follow up this tutorial with a one that covers more advanced topics.

Those of who wants to test this Web service through a client please refer, Hello World with Axis2. It shows, how to automatically generate client stubs and create a client with just a few lines of code, using Axis2.

Author

Tharindu Mathew, Trainee Web Service Developer, tharindu at wso2.com