WSAS and Eclipse simplify creating Web services

Need to create a Web service quickly? Consider the Web Services Application Server plug-in for Eclipse

We find Web services everywhere today. There's a good chance you will need to create Web services for whatever new applications or features you are developing. And it was not too long ago that this could be a painful proposition. WSO2 realized this and created an Eclipse plug-in to help make working with Web services easier. This article explores the WSO2 Web Services Application Server (WSAS) Eclipse plug-in and how it can help you develop Web services.

Michael Galpin, Developer, eBay

Michael Galpin's photoMichael Galpin has been developing Java software professionally since 1998. He currently works for eBay. He holds a degree in mathematics from the California Institute of Technology.



04 March 2008

Also available in Japanese

What is WSO2 WSAS?

Before we get too involved with the Web Services Application Server (WSAS) plug-in for Eclipse, we need to discuss WSAS itself. WSAS is a Java™ application server designed for Web services. It's an open source project distributed under the Apache Software License. WSAS contains the tools for every task you need to accomplish with Web services, including creating, deploying, managing, etc. It offers particularly effective tools that enable many features we expect in modern Web services, including the various WS-* you have heard about. WSAS is a relatively new product, but it is built on proven open source technologies, including Axis2 and Apache Tomcat.

You can use WSAS with another application server, such as Tomcat or IBM® WebSphere®, but it is fully functional by itself, as well. We use it in stand-alone mode in this article. We will focus on the Eclipse plug-in that is part of the WSAS and see how it makes Web services easier and how it ties in to WSAS.

Some of the developers behind WSAS — and the Web service standards themselves — work at WSO2, a company that develops open source software based on Apache projects, and offers support, consulting, and training services. Download WSAS from the WSO2 Oxygen Tank, WSO2's developer portal (see Resources).


System requirements

You need Eclipse V3.3, the WSO2 WSAS, and the WSAS Eclipse plug-in to develop a Web service. The WSAS plug-in leverages the Eclipse Web Tools Platform. The easiest way to satisfy this is to use the Eclipse Java EE. You will also need WSO2's WSAS V2.1 and a Java Development Kit (JDK) V5.0 or higher (see Resources). This article was written using Mac OS X, but all of the software required operates with Windows® and Linux®. File locations may need adjustment according to the customs of your operating system.


The Eclipse plug-in

WSAS has a powerful administrative application that we will see more of later. It supports deploying various JAR-based archives as Web services and even supports legacy Web service deployment descriptors used with Axis. You still need to write your code and create these various artifacts, however. Developing Java applications and using Eclipse go hand in hand. And the WSAS plug-in makes it easy to turn your Java application into a Web service running on WSAS. But before we start using it, we need to install and set it up.

Installation

To install the WSAS plug-in, we need to have Eclipse and WSAS already installed. You will also need to set up a JAVA_HOME environment variable, if you do not have this already. This should point to the directory that your JDK is installed in. Once this is set up, go to the bin directory of your WSAS installation and run the install script. This is install.bat on Windows, and install.sh on Linux and OS X. You should receive output as shown in Listing 1.

Listing 1. Running the installer script
>./install.sh 
Running WSO2 Web Services Application Server, v2.1 installer...

###########################################################
#                                                         #
#               WSO2 WSAS v2.1 Installation               #
#                                                         #
###########################################################


Please select your installation mode: 
1) Eclipse WTP Plugin Installation
2) Servlet Container Installation
3) Windows NT Service Installation
4) Windows NT Service Uninstallation
:

You will select option No. 1, and this should bring up the output shown in Listing 2.

Listing 2. Selecting Eclipse home
Selection: Eclipse WTP Plugin Installation

Starting WSAS Eclipse WTP Plugin installation...
Please shutdown the Eclipse instance, If Already Running ...
Please enter Eclipse WTP Home :

As mentioned, the WSAS plug-in leverages the Eclipse WTP. For this, you will usually just enter the directory where Eclipse is installed. The only exception is if you have Eclipse set up to keep your plug-ins outside the Eclipse installation directory. In that case, you enter the external plug-in directory. Either way, you should see the following output.

Listing 3. WSAS plug-in installed
Copying WSAS Eclipse WTP Plugins /Applications/eclipse/plugins
OK

WSO2 WSAS Eclipse WTP Plugin installation was successful.
Please restart Eclipse WTP Instance..

That's all there is to installing the WSAS plug-in. Now if you launch Eclipse, you should see WSAS tools and menus, as shown below.

Figure 1. The WSAS IDE
The WSAS IDE

Now that the WSAS plug-in is installed, we need to configure it so we can start using it.

Configuration

To configure the WSAS plug-in, we need to open the Eclipse Preferences and open Web Services > WSAS Preferences, as shown below.

Figure 2. WSAS Preferences panel
WSAS Preferences panel

There's only one thing we need to do: select the WSAS Runtime. Once this is selected, the WSAS plug-in will verify the location and show you a message indicating that it loaded the WSAS runtime. Once that is done, you can click OK. Now you're ready to start using the WSAS plug-in to develop a Web service.


Developing Web services

So far, all you have done is install the WSAS plug-in and configure it by simply letting the plug-in know where WSAS is installed. This enables you to start developing a Web service using the WSAS plug-in. You will take a simple Java class and turn it into a Web service using the WSAS plug-in. You will then use WSAS to test the Web service.

Working with POJOs

Web services have been around for many years. For as long as there have been Web services, there have been toolkits and frameworks for creating them. Those frameworks often involved declaring interfaces, implementing interfaces defined by the framework, or creating an XML file to generate code from (or all of the above). Modern Web services are nothing like that. The term Plain Old Java Objects (POJOs) is often used to refer to using everyday Java classes with persistence frameworks like Hibernate, but they are equally applicable to Web services. Any POJO can become a Web service using the WSAS plug-in. So for us to develop a Web service, we just need to write a Java class. We will write a class that determines the factors of an integer. The code for the class is shown in Listing 4.

Listing 4. The FactorService class
package org.developerworks.services;

import java.util.LinkedList;
import java.util.List;

public class FactorService {
     public Integer[] factor(int num){
          List<Integer> factors = new LinkedList<Integer>();
          int sqrt = (int) Math.floor(Math.sqrt(num));
          for (int i=1;i<=sqrt;i++){
               if (num % i == 0){
                    int mid = factors.size()/2;
                    factors.add(mid, i);
                    int quotient = num/i;
                    if (i != quotient){
                         factors.add(mid+1, quotient);
                    }
               }
          }
          return factors.toArray(new Integer[factors.size()]);
     }
}

Here is a quick explanation of how this class works. It accepts an integer to factor. It loops through all of the integers that are less than or equal to the square root of the input integer. If that integer divides the input integer, it adds not only that integer but the input integer divided by the counter-integer, and adds them to a list. It adds the integers in order, so the list is already sorted at the end. It then turns the list into an array that is returned. This is definitely a POJO: There are no interfaces implemented — nothing but the application logic going on here. This is as easy to develop as it could be, as we did not do anything other than implement our business logic (calculating the factors of an integer). So how easy will this be to turn into a Web service? Let's use the WSAS plug-in and find out.

Creating and deploying a Web service

To create a new Web service, we start by creating a Web application. To do this, choose File > New > Other, as shown in Figure 3.

Figure 3. Starting the new Web application wizard
Starting the new Web application wizard

Now pick Web > Dynamic Web Project.

Figure 4. New Dynamic Web Project
New Dynamic Web Project

This will bring up the New Dynamic Web Project interface.

Figure 5. New Dynamic Web Project
New Dynamic Web Project

One of the things you should notice is that there is no Target Runtime. We need to specify WSAS as the target runtime, so click New. This will bring up the New Server Runtime interface.

Figure 6. New Server Runtime
New Server Runtime

In the New Server Runtime interface, make sure you specify WSO2 > WSO2 WSAS as the runtime type. Also, make sure you select the check box next to "Also create new local server" and click Finish. This should take you back to the Dynamic Web Project screen.

Figure 7. Dynamic Web Project with server runtime specified
Dynamic Web Project with server runtime specified

Make sure you click Next, not Finish. This should bring up the Project Facets interface.

Figure 8. Project Facets
Project Facets

Make sure you select the WSAS Web Services facets. From here, go ahead and click Finish. This will create a skeleton Web project for you. Now you can add our FactorService class to this project (File > New > Class). You can also create a Web service from the FactorService class. Once again, select File > New > Other, but this time, select Web Services > Web Service.

Figure 9. New Web service
New Web service

Clicking Next will bring up the new Web service interface.

Figure 10. Defining the new Web service
Defining the new Web service

Notice that under Configuration, the Web service runtime is selected as Apache Axis. We need to change this, so click on it and it will bring up the Service Deployment Configuration interface.

Figure 11. Service Deployment Configuration
Service Deployment Configuration

Now we need to change the Web service runtime to WSO2 Web Services Application Server and click OK. This should bring back the Web Service interface.

Figure 12. Web Service interface with WSAS runtime selected
Web Service interface with WSAS runtime selected

On this screen, make sure that Publish the Web service is checked, then click Next. This will bring up the WSAS Web Service Java Bean Configuration interface.

Figure 13. WSAS Web service Java Bean Configuration
WSAS Web service Java Bean Configuration

On this screen, make sure that Generate Default Services.xml file is selected, then click Finish. This will cause the WSAS plug-in to create all the artifacts necessary for your Web service and publish it to your WSAS installation. To verify that the service has been published, bring up the WSAS Management console. This is usually available at https://localhost:9443. Log in to the console and go to Services.

Figure 14. WSAS Management console: List of services
WSAS Management console: List of services

You should see the FactorService listed in the table of Web services deployed to WSAS. The other services you see in the list are the default ones that ship with WSAS.

Congratulations! You have just created and deployed a Web service. Of course, just because we have something out there, we do not know if it works or not. We need to test it. Once again, WSAS will make this easy.


Testing the Web service

Let's take a look at the Web service we created. In the Service table, we see a link for the WSDL V2.0 View. Click on this and you should see the WSDL shown below.

Listing 5. FactorService WSDL
<wsdl2:description xmlns:wsdl2="http://www.w3.org/ns/wsdl"
     xmlns:tns="http://services.developerworks.org"
     xmlns:wsoap="http://www.w3.org/ns/wsdl/soap"
     xmlns:ns0="http://services.developerworks.org"
     xmlns:ns1="http://org.apache.axis2/xsd"
     xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl"
     xmlns:wsdlx="http://www.w3.org/ns/wsdl-extensions"
     xmlns:xs="http://www.w3.org/2001/XMLSchema"
     xmlns:whttp="http://www.w3.org/ns/wsdl/http"
     xmlns="http://www.w3.org/ns/wsdl"
     targetNamespace="http://services.developerworks.org">
     <wsdl2:documentation>FactorService</wsdl2:documentation>
     <wsdl2:types>
          <xs:schema xmlns:ns="http://services.developerworks.org"
               attributeFormDefault="qualified" elementFormDefault="qualified"
               targetNamespace="http://services.developerworks.org">
               <xs:element name="factor">
                    <xs:complexType>
                         <xs:sequence>
                              <xs:element minOccurs="0" name="num"
                                   type="xs:int" />
                         </xs:sequence>
                    </xs:complexType>
               </xs:element>
               <xs:element name="factorResponse">
                    <xs:complexType>
                         <xs:sequence>
                              <xs:element maxOccurs="unbounded" minOccurs="0"
                                   name="return" type="xs:int" />
                         </xs:sequence>
                    </xs:complexType>
               </xs:element>
          </xs:schema>
     </wsdl2:types>
     <wsdl2:interface name="ServiceInterface">
          <wsdl2:operation name="factor"
               pattern="http://www.w3.org/ns/wsdl/in-out">
               <wsdl2:input element="ns0:factor" wsaw:Action="urn:factor" />
               <wsdl2:output element="ns0:factorResponse"
                    wsaw:Action="urn:factorResponse" />
          </wsdl2:operation>
     </wsdl2:interface>
     <wsdl2:binding name="FactorServiceSOAP11Binding"
          interface="tns:ServiceInterface" type="http://www.w3.org/ns/wsdl/soap"
          wsoap:version="1.1">
          <wsdl2:operation ref="tns:factor" wsoap:action="urn:factor" />
     </wsdl2:binding>
     <wsdl2:binding name="FactorServiceSOAP12Binding"
          interface="tns:ServiceInterface" type="http://www.w3.org/ns/wsdl/soap"
          wsoap:version="1.2">
          <wsdl2:operation ref="tns:factor" wsoap:action="urn:factor" />
     </wsdl2:binding>
     <wsdl2:binding name="FactorServiceHttpBinding"
          interface="tns:ServiceInterface"
          type="http://www.w3.org/ns/wsdl/http">
          <wsdl2:operation ref="tns:factor"
               whttp:location="FactorService/factor" />
     </wsdl2:binding>
     <wsdl2:service name="FactorService"
          interface="tns:ServiceInterface">
          <wsdl2:endpoint name="SecureSOAP11Endpoint"
               binding="tns:FactorServiceSOAP11Binding"
               address="https://192.168.0.104:9443/services/FactorService">
               <wsdl2:documentation>
                    This endpoint exposes a SOAP 11 binding over a HTTPS
               </wsdl2:documentation>
          </wsdl2:endpoint>
          <wsdl2:endpoint name="SecureSOAP12Endpoint"
               binding="tns:FactorServiceSOAP12Binding"
               address="https://192.168.0.104:9443/services/FactorService">
               <wsdl2:documentation>
                    This endpoint exposes a SOAP 12 binding over a HTTPS
               </wsdl2:documentation>
          </wsdl2:endpoint>
          <wsdl2:endpoint name="SecureHTTPEndpoint"
               binding="tns:FactorServiceHttpBinding"
               address="https://192.168.0.104:9443/services/FactorService">
               <wsdl2:documentation>
                    This endpoint exposes a HTTP binding over a HTTPS
               </wsdl2:documentation>
          </wsdl2:endpoint>
          <wsdl2:endpoint name="SOAP11Endpoint"
               binding="tns:FactorServiceSOAP11Binding"
               address="http://192.168.0.104:9762/services/FactorService">
               <wsdl2:documentation>
                    This endpoint exposes a SOAP 11 binding over a HTTP
               </wsdl2:documentation>
          </wsdl2:endpoint>
          <wsdl2:endpoint name="SOAP12Endpoint"
               binding="tns:FactorServiceSOAP12Binding"
               address="http://192.168.0.104:9762/services/FactorService">
               <wsdl2:documentation>
                    This endpoint exposes a SOAP 12 binding over a HTTP
               </wsdl2:documentation>
          </wsdl2:endpoint>
          <wsdl2:endpoint name="HTTPEndpoint"
               binding="tns:FactorServiceHttpBinding"
               address="http://192.168.0.104:9762/services/FactorService">
               <wsdl2:documentation>
                    This endpoint exposes a HTTP binding over a HTTP
               </wsdl2:documentation>
          </wsdl2:endpoint>
     </wsdl2:service>
</wsdl2:description>

A couple of things you should notice here. Under wsdl12:types/xs:schema, there are two types defined: factor and factorResponse. These are the in-and-out parameters of our service. The first is a single integer, and the other is an unbounded sequence of integers. This is what you would probably write if you had to write the WSDL yourself. But you did not have to! WSAS and the WSAS plug-in did it for you.

Let's continue to explore our service running on WSAS. Go back to the Service table and click on the FactorService link in the Services column. This brings up the Service Management interface.

Figure 15. Service Management
Service Management

There are a lot of things you can do with your service from this screen. You can manage security and transport configuration, but for now, let's click on the Try It link. This will bring up the Try Web Service interface.

Figure 16. Try Web Service
Try Web Service

Go ahead and put in some numbers and play around. What is going on here? Is WSAS invoking your Java class directly and just displaying the results? Is it calling some proxy that is invoking your Web service instead? Watch the HTTP traffic and what you will see is shown in Listings 6 and 7.

Listing 6. HTTP request from invoking FactorService.factor(783)
<?xml version="1.0" encoding="UTF-8"?>
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope"
     xmlns:wsa="http://www.w3.org/2005/08/addressing">
     <s:Header>
          <wsa:To>https://localhost:9443/services/FactorService</wsa:To>
          <wsa:ReplyTo>
               <wsa:Address>
                    http://www.w3.org/2005/08/addressing/anonymous
               </wsa:Address>
          </wsa:ReplyTo>
          <wsa:MessageID>
               http://identifiers.wso2.com/messageid/1197868769405/8468659498
          </wsa:MessageID>
          <wsa:Action>urn:factor</wsa:Action>
     </s:Header>
     <s:Body>
          <p:factor xmlns:p="http://services.developerworks.org">
               <num xmlns="http://services.developerworks.org">
                    783
               </num>
          </p:factor>
     </s:Body>
</s:Envelope>

This is a SOAP request. It will validate against the WSDL we saw in Listing 5. What do you think we will see from a SOAP request?

Listing 7. HTTP response from invoking FactorService.factor(783)
<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope
     xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"
     xmlns:wsa="http://www.w3.org/2005/08/addressing">
     <soapenv:Header>
          <wsa:Action>
               urn:factorResponse
               </wsa:Action>
          <wsa:RelatesTo>
                    http://identifiers.wso2.com/messageid/1197868769405/8468659498
               </wsa:RelatesTo>
     </soapenv:Header>
     <soapenv:Body>
          <ns:factorResponse xmlns:ns="http://services.developerworks.org">
                    <ns:return>1</ns:return>
                    <ns:return>3</ns:return>
                    <ns:return>9</ns:return>
                    <ns:return>27</ns:return>
                    <ns:return>29</ns:return>
                    <ns:return>87</ns:return>
                    <ns:return>261</ns:return>
                    <ns:return>783</ns:return>
          </ns:factorResponse>
     </soapenv:Body>
</soapenv:Envelope>

This is a SOAP response. Again, this would validate against the WSDL. WSAS invoked the Web service directly using an Ajax library called WSRequest, which is also part of WSAS. No proxies were used. This is exactly the kind of request a client using your service would use and exactly the kind of response your Web service would send back to the client.


Summary

Web services have come a long way. There are no more interfaces to write or implement. There is no code to generate or XML files to create. The WSAS simplifies what you need to create. It requires that very little be done to create a Web service. What little is required can be provided by the WSAS plug-in for Eclipse. With WSAS and the WSAS plug-in, you get to concentrate on just writing your business logic and forget about the rest.

Resources

Learn

Get products and technologies

Discuss

  • The Eclipse Platform newsgroups should be your first stop to discuss questions regarding Eclipse. (Selecting this will launch your default Usenet news reader application and open eclipse.platform.)
  • The Eclipse newsgroups has many resources for people interested in using and extending Eclipse.
  • Participate in developerWorks blogs and get involved in the developerWorks community.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Open source on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Open source
ArticleID=291939
ArticleTitle=WSAS and Eclipse simplify creating Web services
publish-date=03042008