Level: Intermediate

Michael Galpin (mike.sr@gmail.com), Developer, eBay

04 Mar 2008

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.

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).

Back to top

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.

Back to top

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.

                
>./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.

                
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.

                
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.

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.

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.

Back to top

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.

                
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.

Now pick Web > Dynamic Web Project.

This will bring up the New Dynamic Web Project interface.

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.

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.

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

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.

Clicking Next will bring up the new Web service interface.

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.

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.

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.

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.

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.

Back to top

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.

                
<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.

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.

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.

                
<?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?

                
<?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.

Back to top

Summary

Share this... Digg this story Post to del.icio.us Slashdot it!

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

• Apache Axis2 powers WSAS. Read "SOA development with Axis2, Part 1: Understanding Axis2 basics."
  
  
• Find out more about the Axis2 architecture in "Web services and Axis2 architecture written by WSO2."
  
  
• Find out more about how XML schema types are converted to Java types in "Java Web Services: Axis2 Data Binding."
  
  
• Learn more about how WSAS makes it possible to use SOAP and Ajax together in "AJAX and Web Services with WSO2" from the The Server Side.
  
  
• WSAS makes it easier than ever to use binary data. See how in "Sending Attachments with SOAP."
  
  
• Eclipse also makes it easy to debug your Web services. Read "How to Debug a Web Service."
  
  
• Creating Web services is only half of the story, you often have to create clients for them. The place to turn to for that is the Reference Guide to Apache Axis2 Client API Parameters.
  
  
• Check out the "Recommended Eclipse reading list."
  
  
• Browse all the Eclipse content on developerWorks.
  
  
• New to Eclipse? Read the developerWorks article "Get started with Eclipse Platform" to learn its origin and architecture, and how to extend Eclipse with plug-ins.
  
  
• Expand your Eclipse skills by checking out IBM developerWorks' Eclipse project resources.
  
  
• To listen to interesting interviews and discussions for software developers, check out check out developerWorks podcasts.
  
  
• Stay current with developerWorks' Technical events and webcasts.
  
  
• Watch and learn about IBM and open source technologies and product functions with the no-cost developerWorks On demand demos.
  
  
• Check out upcoming conferences, trade shows, webcasts, and other Events around the world that are of interest to IBM open source developers.
  
  
• Visit the developerWorks Open source zone for extensive how-to information, tools, and project updates to help you develop with open source technologies and use them with IBM's products.
  
  

• Download Eclipse Foundation technology from the Eclipse downloads.
  
  
• Download WSO2's WSAS V2.1.
  
  
• Get Sun's Java Development Kit (JDK) V5.0 or later.
  
  
• Check out the latest Eclipse technology downloads at IBM alphaWorks.
  
  
• Download Eclipse Platform and other projects from the Eclipse Foundation.
  
  
• Download IBM product evaluation versions, and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
  
  
• Innovate your next open source development project with IBM trial software, available for download or on DVD.

• 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.
  
  

About the author

		Michael 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.

Original link: http://www.ibm.com/developerwork...