With WSO2's Web Services Application Server, hassles related to the development, deployment, management and consumption of enterprise level Web services have become a thing of the past. An ever increasing number of users are riding the Web services bandwagon and exposing their services using SOA. But how can a user who may already have some code written in a non-Web services-specific way, perhaps as plain old java objects, make use of the power of Web services? Can it be done without having to rewrite all of the existing code? Thanks to WSO2 WSAS, this is now possible with minimal or zero code change. In this article by Suran Jayathilaka,he describes how this is done.

 

Applies To

WSO2 WSAS	v2.2
Sun JDK	v1.5

 

For Whom Is This Tutorial?

This tutorial assumes no prior experience with Web services or WSO2 WSAS. In order to complete this tutorial successfully, all you need is a little experience in Java development. And I will presume that you have the Sun JDK 1.5 or higher already installed on your computer.

 

Contents

• Introduction [0]
• Installing WSO2 WSAS [0]
• Deploying a single POJO class [0]
• Deploying an Annotated jar [0]
• Invoking the service [0]
• Using WSAS IDE plugin for Eclipse WTP [0]

 

Introduction

Q: How do I deploy my simple Java classes (POJOs) as Web Services?

A: In this tutorial you will see how to expose a simple POJO (Plain Old Java Object) as a Web Service using the WSO2 Web Services Application Server (WSAS). My goal is to help you realize, how easy it is to take any old java class and make it accessible over a network as a Web service, without prior knowledge of Web services development. The creation of Web services has never before been this easy, but thanks to WSO2 WSAS, now it is!

All code used in this tutorial are available for download from here [0].

 

Installing WSO2 WSAS

    (For detailed instructions on how to install WSO2 WSAS on your computer please refer to the Installation Guide [1].)

• First of all, download the binary distribution of the latest stable release of WSO2 WSAS (currently version 2.2) from the WSAS Download [2] page. Once downloaded, extract wso2wsas-2.2.zip file to a folder on your local hard drive. We will refer to this folder as WSAS_HOME from here onwards.

• Start the WSO2 WSAS standalone server by running the wso2wsas.sh (Linux) or wso2wsas.bat (windows) script in the WSAS_HOME/bin folder. You could choose to run WSO2 WSAS as a web application inside your servlet container (Apache Tomcat, JBoss etc), just as easily. Refer to the WSO2 WSAS Installation Guide to find out how. For this tutorial, I will assume that you are working with the standalone server.

• Point your browser to https://<host>:9443 and you will be presented with the WSO2 WSAS management console. From here, you will be able to access the User Guide link to view the myriad documentation and guides bundled with the WSO2 WSAS distribution.



• Sign in using your username and password (the default values are 'admin' and 'admin').

Deploying a single POJO class

First, we shall see how to expose a single Java class as a Web service using WSO2 WSAS. For this example, I will be considering a simple calculator program. The calculator will provide several mathematical opeartions such as addition, multiplication, division and subtraction. But you should be able to apply the instructions in this tutorial to any POJO that you have or want to write.

One thing you must keep in mind when deploying a single unarchived Java class in WSAS, is that the class cannot be declared in a package other than the default package. You can easily overcome this limitation by packaging your class in a jar and I will elaborate on this later in this tutorial.

• Let us begin by writing the Calculator class:

  
  public class Calculator {
  	
  	public double add(double a, double b) {
  		return a + b; 
  	}
  	
  	public double subtract(double a, double b) {
  		return a - b;
  	}
  	
  	public double multiply(double a, double b) {
  		return a * b;
  	}
  	
  	public double divide(double a, double b) {
  		return a / b;		
  	}
  
  }

As you can see, this is a very basic java class and has nothing to do with any Web service specific technologies. Employing the power of Web services or SOA (Service Oriented Architecture) in general, you will see how easy it is to expose your calculator to the whole wide world, if you wish to do so.

• Compile the Calculator class.

• On the left panel in the WSAS management console, click on Services which will take you to the Service & Service Group Management screen. On this screen, you will see the plethora of options that are available for deploying new services on WSO2 WSAS. Click on Upload POJO Artifact - JSR-181 Annotated/JAX-WS (.jar, .class).



• You will be be taken to the following view. Enter the path to the Calculator.class file by browsing your local file system. The form field underneath allows you to upload additional jars that your class may be dependent on, if any. You can add as many jars as you need using the + button.



• When all file paths have been specified, click the Upload button and presto! The Calculator POJO will be uploaded and deployed as a fully fledged Web service. That's all there is to it!

• If you go back to the Service Service Group Management view, you will see the new Calculator service listed among the available services. You can click on the provided links to view WSDL (Web Services Description Language) documents, schema or policy information pertaining to your service.



• In the Services column of the table, click on Calculator to go to the Service Management page for the Calculator service. From here itself, you can check if your new service works as it's supposed to, using the Try It tool.

• Click on 'Try It' at the bottom of the management options. Now you will see all the operations that are provided by your service, namely, Add, Subtract, Divide and multiply. Click on any operation name in the tabbed display and enter values for the two required parameters. Now, click on the operation button below the parameters and you will see the result immediately.

 

Deploying an Annotated jar

If you want your POJO to be deployed in a jar (which is often the case when your POJO consists of several classes), or if you want your service class to be in a package other than the default package, then you need to make use of annotations. Here, by annotations I mean the JSR-181 i.e. Web Services MetaData for Java annotations. Strictly speaking, annotations are only required when there are several classes in the jar, out of which, you need to pick one to be the service - or when you want to selectively expose some of the class' methods as Web service operations. Note that you need to be using Java version 1.5 or higher in order to use annotations.

• The code for the Calculator class, now named AnnotatedCalculator, will change as given below. To compile this class you will need to add the axis2-jws-api-1.35.jar (or the version available with the WSO2 WSAS distribution you happen to be using) which contains these annotations, available in the WSAS_HOME/lib folder, to your Java classpath.

package org.wso2.sample;



import javax.jws.WebMethod;

import javax.jws.WebService;



@WebService(name = "CalculatorService")

public class AnnotatedCalculator {



	@WebMethod(operationName = "add")

	public double add(double a, double b) {

		return a + b;

	}



	@WebMethod(operationName = "subtract")

	public double subtract(double a, double b) {

		return a - b;

	}



	@WebMethod(operationName = "multiply")

	public double multiply(double a, double b) {

		return a * b;

	}



	@WebMethod(operationName = "divide")

	public double divide(double a, double b) {

		return a / b;

	}



}

• As shown in the code above, the class you want to expose as a Web service should be annotated with the @WebService annotation, along with the name parameter that specifies the name of the service. Any methods of the class you want to expose as operation of the Web service need to be annotated with @WebMethod, specifying the operationName parameter.

• Now, compile the AnnotatedCalculator class and create the jar file using either the Java jar tool or your IDE's export function. Assuming you have followed the a similar package structure for the class, go to the folder containing the top level org folder of the compiled class and create the jar with the following command.

  jar cvf annotated-calc.jar org

  I've created the jar file, with the name annotated-calc.jar.

• Now, like you did before, in the Service & Service Group Management screen, click on Upload POJO Artifact - JSR-181 Annotated/JAX-WS (.jar, .class). Now specify the paths to the annoatated-calc.jar file and any required resource jars, which is none in this case. Then, click Upload and the jar/s will be uploaded to and deployed on WSO2 WSAS.



• Now go back to the services list and you will see a listing for the new annotated calculator service, named CalculatorService. Similar to the previous non-annotated Calculator service, you can access your new service with the Try It tool and get immediate results.

Invoking the Service

Now that you have exposed your plain old java class as a Web service, let us see how it can be accessed or consumed. In fact, there are several ways in which this can be done, one of which is the Try It tool provided by WSO2 WSAS itself that I talked about briefly earlier. You can also consume your Web service with a simple SOAP (Simple Object Access Protocol) client or in a RESTful (Representational State Transfer) manner.

• Writing a SOAP client

  WSO2 WSAS makes writing a client program to access your Web service quite easy by taking care of much of the boilerplate code involved.

  • To begin, in the WSAS management console services list panel, click on the service you want to write a client for, in our case the CalculatorService service, to go to the management screen for the service.

  • Click on the option named Generate Client. You will be taken to a screen which allows you to customize the generated stub to fit your needs. For this example, just accept the default values and click the Generate button. WSO2 WSAS will generate the stub classes that are necessary for accessing your service and present them to you as a downloadable archive.

  
  • Save this jar to your local disk.
  • Now you can write a simple client that makes use of these generated stubs. It would be something like the code below.

  package org.wso2.sample.client;
  
  import java.rmi.RemoteException;
  import org.apache.axis2.AxisFault;
  import org.wso2.sample.Add;
  import org.wso2.sample.AddResponse;
  import org.wso2.wsas.client.CalculatorServiceStub;
  
  
  public class CalculatorClient {
  
  	public static void main(String[] args) 
  		throws AxisFault, RemoteException{		
  
  		//create an instance of the stub
  		CalculatorServiceStub stub = new CalculatorServiceStub();
  
  		//create an object of the operation you want to invoke
  		Add addObj = new Add();		
  
  		//set the arguments
  		addObj.setA(42);
  		addObj.setB(666);		
  
  		//invoke the operation and receive the response
  		AddResponse addResp = stub.add(addObj);		
  
  		//display the return value in the response
  		System.out.println(addResp.get_return());		
  
  	}
  
  }

  • Now you can compile this program, making sure that the above generated stub jar is in your classpath. You may also need to add the jars in WSAS_HOME/lib to the classpath in order to resolve all compilation dependencies.

  • When you run the compiled client, you should see the correct result. Feel free to change the code to invoke any of the other operations as well.

• RESTful Invocation

  This method of invocation is quite straightforward as it will not require writing any code.

  • Simply, get the endpoint reference address for your service (in the Service Management screen, the endpoint references for both HTTP and HTTPS are listed in the last row of the table) and enter it in your browser's address bar followed by the name of the operation you want to invoke. Include any arguments you need to pass in the form of key value pairs.

    E.g. For my CalculatorService service, the HTTP endpoint reference is http://localhost:9762/services/CalculatorService. Now, say you want to invoke the multiply operation with the arguments 1.21 and 245! You can point your browser to
    http://localhost:9762/services/CalculatorService/multiply?a=1.21&b=245
    and you will receive the following result.

  .

  You may have noticed that this is the same as a simple HTTP GET request.

 

Using WSAS IDE Plugin For Eclipse WTP

By now you should have realized how easy it is to convert plain old Java classes to fully functional Web services using WSO2 WSAS. If you use the Eclipse IDE for Java development, WSAS makes this process even easier thanks to the WSAS IDE plugin for the Eclipse WTP. To learn how the WSAS IDE plugin can be used to develop, debug and deploy Web services right off the IDE in a speedy and convenient manner, refer to this excellent guide by Lahiru Sandakith on Developing Web Services with WSAS IDE [3].

Conclusion

In this tutorial, you learned how to expose a plain old Java object as a Web Service using WSO2 WSAS. You saw how a single .class file can be deployed as well as an annotated class in a jar. You also learned how to consume such services either by writing a client with the help of stubs generated by WSAS or in a RESTful manner.

 

Author

Suran Jayathilaka, Software Engineer at WSO2. suran at wso2 dot com.