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).
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
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
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
Now pick Web > Dynamic Web Project.
Figure 4. New Dynamic Web Project
This will bring up the New Dynamic Web Project interface.
Figure 5. 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
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
Make sure you click Next, not Finish. This should bring up the Project Facets interface.
Figure 8. 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
Clicking Next will bring up the new Web service interface.
Figure 10. 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
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
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
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
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
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
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.
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. |
Rate this page
| 
