This tutorial by Lahiru Sandakith consists of two parts with examples to walk you through the step by step process of developing, deploying, testing and debugging a sample Gaming Web service using WSO2 WSAS IDE.

As a pre-requisite to this tutorial, it is recommended that you read through the online documentation of WSO2 WSAS in order to get familiar with WSAS.

Applies To

WSO2 WSAS	v2.1
Eclipse WTP	v2.0
Sun JDK	v1.5

Introduction
Tutorial Scenario
Getting Started
Part 1
- Install and configure Eclipse WTP with WSO2 WSAS
- Develop and Deploy the WSO2GameService using WSAS IDE.
Part 2
- Locally Test the WSO2GameService with JUnit.
- Debug a Web service using WSAS IDE
Conclusion
References

Introduction

WSAS IDE WSO2 WSAS is a lightweight, high performing Web services Platform for Service Oriented Architecture, powered by Apache Axis2, enabling business logic and applications. It brings together the value of a number of Apache Web services projects in to one integrated and complete solution. WSO2 WSAS provides a secure, transactional and reliable runtime for deploying and managing Web services. It is carefully designed to support the easy addition of plugin "modules" that extend its functionality for features such as security and reliability.

On the other hand, Eclipse is an open source project aiming to provide a universal tool set for development in any programming language. It is the most widely used IDE for most computer languages, especially for JAVA. The plugin architecture of its design makes the IDE usable with any programming language.

The new feature of WSAS IDE brings together the power of the Eclipse Integrated Environment as a Tool and WSO2 Web Services Application Server capabilities to develop Web services. This combination creates a complete tool set for developing, deploying, testing and debugging that will increase the productivity of the Web service developers and consumers.

Tutorial Scenario

Lets think of a Java developer who develop, deploy, test and debug Web services. As part of his day to day work he needs to expose an available application as a Web service and test them against the clients for verification of the functionality. For this it's almost necessary to debug the Web service to nail down issues and find out why the service is not working as expected. This tutorial covers developing, deploying, testing and mainly introduce the way to debug a custom-made Web service.

As the example Web service in this tutorial, we will use custom made game application mainly because this scenario will suit the debugging approaches that will help the user to understand the power of debugging by cheating the game. In Web services deployment and testing it's a necessity to be able to debug, and by having the advantage of doing all the necessary scenarios in one integrated development environment, it becomes an added advantage for the Web services developers.

Only WSAS IDE is used on this tutorial and to make up the WSAS IDE we use the Eclipse WTP 2.0 and WSAS 2.1. The tutorial uses the WSO2 WSAS as the Web service deployment engine. Also, it is assumed that you know the basics of how to use Eclipse IDE as your Java development environment, and therefore it does not cover areas such as creating a JAVA project in an Eclipse workspace and compiling and building a JAVA project in Eclipse etc.

Getting Started

These are the tools used in the tutorial.

1) Java Development Kit 1.5 (Download)

2) Eclipse WTP SDK 2.0 (Download)

3) WSO2 WSAS 2.1.x (Download)

Now let us focus on getting the WSAS IDE configured.

Part 1

Install and Configure Eclipse WTP with WSO2 WSAS

Extract the WSO2 WSAS, v2.1 in to a directory on your file system (We will refer that directory as <WSAS_HOME>). We will be using the installation script to install the embedded WSAS IDE eclipse plugins inside the WSAS distribution. Go to the <WSAS_HOME>/bin locate the install script to suit your operating system. If you are on MS Windows you will have to use install.bat and if you are on a *nix platform you will have to use install.sh.
Run the install script
At the first step the user will be asked to enter the installation mode. As we want to go for the Eclipse WTP Plugin installation we need to enter the option 1. In order to go ahead the user needs a valid eclipse home directory.
If you have Eclipse WTP 2.x already in your local machine, we'll refer the root directory of that Eclipse WTP 2.x installation as <Eclipse_Home>. If you do not have Eclipse WTP 2.x, download and extract it in to a user define <Eclipse_Home>.
Returning to the installation again, the next step is to specify the Eclipse WTP Home directory to complete the installation. When you are prompted to enter the Eclipse WTP Home location you need to specify the above worked out <Eclipse_Home>.

If the entered Eclipse WTP Home passed the small validation of the WSAS WTP Plugin installer, it will install the WSO2 WSAS IDE Plugins in to the specified Eclipse WTP instance.

Note : Please note that if you already have an earlier version of the WSO2 WSAS IDE plugins installer inside the specified Eclipse WTP instance, then the installer will ask a confirmation message to override the already existing installation.

Develop and Deploy the WSO2GameService using WSAS IDE

By this time you have successfully configured the WSO2 WSAS IDE. Now we will concentrate on covering the tutorial scenario of demonstrating debugging of Web service using WSAS IDE. For this we need an active service, that is worth debugging. In the next few steps we will create a "WSO2GamingService" which will be the service used to demonstrate the debugging aspects.

First create the "WSO2GamingService" and then go ahead and run a TestCase that will prove that it works. Now start your WSAS IDE.

Note: In addition to the normal Eclipse WTP features you will soon realize the additional features that WSAS IDE has added. There will be a custom WSAS Menu together with WSAS Toolbar.
Next step is to configure the WSAS Preferences of the IDE. The main aim of this is to integrate the WSAS runtime.

Open Window -> Preferences -> Web Services -> WSAS Preferences. Then Set the WSAS Runtime to point to the local WSAS Home location.

Note : When you set the correct WSAS Home, the preferences will validate it and will display the result message. Here also note that You can configure the debugging options. Also on the WSAS Preferences page, we can set the default setting for the Web services creation codegen options, Web services client codegen options and service archive options. Since we will use the defaults of these features, you do not need to do any adjustments. Of course for your custom needs you can fine tune preferences.
Now create a project with the support of WSAS features. Open File -> New -> Other... -> Web -> Dynamic Web Project. Dynamic Web Project is the Web Services project with WSAS Runtime Support that is readily made available.

Select the Dynamic Web project and click next.
Select the name of the project as the Dynamic Web project name (you can specify any name you prefer), but for convenience we use the name "WSASDebugCheck", related to the tutorial topic.
As the next step we need to assign the target runtime to the created Dynamic Web project. Click on the New Target Runtime button and select the WSO2 WSAS target runtime.

Then click Finish. This will add the target runtime.
Note that it will add the configurations of the default WSAS settings as well.

Click Next.
Next will be the DWP Facets Page. On this facet creation page, select the WSAS Web Services Facets , Core and Extensions.

Click Next.
Then accept the default configuration settings on the Configure Web Modules Page.

Click Finish.
It will create the Dynamic Web Project with the support of WSAS Web Services functionalities.
Now we will create the WSO2GameService. First we need to create a appropriate package. We will create org.wso2.wsas.example package under the src directory of the created WSASDebugCheck dynamic Web project.
Under that package we will now create the WSO2GameService class.
Make sure that you have created the WSO2GameService under the correct package with the correct name.
You can download the actual WSO2GameService Class from here. Download it and replace recently created WSO2GameService content with the downloaded file content.

Please go through the WSO2GameService java doc for the instructions to how to play the game. Now we are ready to go ahead and create our Game.
Now we have the JAVA Bean that has to be exposed as the Web service, which represent the WSO2GameService. To create the customized game service we need to have a custom services.xml file so that we can host it as required. As for the gaming service we need to change the scope of the service. For more details about customizing the services using WSAS look into here. Lets go ahead and create the customized services.xml file for our gaming service. Lets start with a creating a XML document through File -> New -> Other -> XML

Click Next.
Select the location of the same package where we placed our WSO2GameService.

Enter the Filename as services.xml and Click Next.
Then accepting the defaults and clicking Finish will generate the empty services.xml file.
Now we have to create the services.xml according to the WSAS semantics. You can use the custom services.xml here, and replace the content of the services.xml file with the content on the hosted services.xml file. Now the services.xml will look like this. For more information about writing custom services.xml, please visit Writing Your Own services.xml tutorial here.

Lets take some time to understand the main difference of this custom services.xml. After reading the tutorial given above I assume that you will have a good idea on the tags of the services.xml file, which is the main configuration file for the WSAS Service Archive.

The main difference other than the default services.xml here is having a scope attribute on the service element. This is called the "Service Session Scope". If we look more on to that topic we can see that there are four service session scopes available for deployment. If we do not specify the session scope, then the service will be deployed using the default session scope - the request session scope.
1. application : Lifetime is equal to the lifetime of the system.
2. soapsession : Session is managed using the custom reference property in the addressing headers
3. transportsession : This session is managed using transport cookies, and the lifetime is equal to the lifetime of the underlying transport.
4. request : Lifetime is very short and it is equal to the request processing time
So we need the application scope to make our WSO2GameService playable.

Now we have created all the needed artifacts to make our WSO2GameService to expose it as a Web service in WSO2 WSAS IDE.
Next step is to start WSO2 WSAS through the IDE. As we have already set the preferences, starting WSAS will be just a matter of a click. You can start the WSAS from the WSAS Main menu or from the WSAS Tool bar. Lets start through it with WSAS Main Menu. Go to WSAS -> WSAS Server -> Start WSAS and start the WSAS Server.
This will result an automatic pop up of the console that will track the logs of the WSAS. If WSAS Server successfully started then there will be a message box pop up with the results.

Click OK, to accept the message.
After starting WSAS, it will automatically display the console and the WTP internal browser with the WSAS HOME Page.

This will direct the user to the non authenticated home of WSO2 Web Services Application Server.
To Sign-In as the admin, click on the Sign-In and get authenticated as username "admin" and password "admin".
Sign-In like admin/admin will direct the user to the authenticated home of WSO2 Web Services Application Server. This will list all the features for the user. Click on the services on the left navigation tab to see the default deployed services list.
Now that we have the up and running WSO2 WSAS through WSAS IDE, lets go ahead and deploy our own WSO2GameService in to the WSAS. We will user WSAS IDE features to deploy the WSO2GameService. For that we will use the Web services wizards provided by the WSAS IDE, and in no time we will able to deploy it within an active WSAS. For this first select the WSO2GameService and then select, File -> New -> Other -> WebService.

And Click Next
This will lead us to the WebServices configuration page of the WSAS IDE.

Because we had selected the WSO2GamingService before we invoked the wizard, the wizard itself will fill most of the entries by default, so you have little to configure. Sine we are going through code first (Bottom up) make sure you have already selected that. Next item is the Service Implementation Class Name. For this make sure that you have selected the fully qualified class name of the WSO2GameService. Other item of importance is to make sure that you have selected up to the start service at the of the left navigation tab. And also make sure that correct items are selected to the Server, Webservice Runtime and the service project as illustrated in the above given image.

After verifying that you have filled the correct entries Click Next.
Next page is the services.xml selection page. If you have a custom services.xml, you can include that by clicking the Browse button. Or else just leave the default and it will add an default services.xml for you. As we need the service deployed to have some changes in the session scope we are going with the "Have a services.xml" option.

Browse and select the custom made services.xml that we made inside the WSASDebugCheck project and Click Next.
Next page is the Web services publication page. Accept the default values.

Click Finish to deploy the WSAS IDE made service.
By now the service will be available on WSAS and you will be able to carry out the WSAS provided functionalities, the "Try It" functionality, for example. For now we will not look in to it. Later in the part 2 of this tutorial we will cover this as one of the ways of invoking the service to debug it.
If we select on the WSO2GameService under the services column, you will be supplied with the details of the WSAS deployed service.

Note the General, Statistics and most importantly the Endpoint references. Now that we have completed the part one of this tutorial. Lets go ahead to the Part 2 to locally test our WSO2GameService and look in to the debugging aspects using the WSAS IDE.

Developing Web Services Easily with WSAS IDE - Part 2

Conclusion

Because of the WSAS IDE Web service creation, deployment, testing and debugging is no more a tedious or time consuming task. With the WSAS IDE you can create, deploy, test and also easily debug your own custom made Web service using a wizard step by step procedures. Hence, time taken to write, deploy, test debug and verify a custom user made Web service is now down to minimum.