Level: Intermediate Tyler Anderson (tyleranderson5@yahoo.com), Freelance Writer, Stexar Corp.
07 Mar 2006 With the rise of Apache Axis and its latest successor, Axis2, developing Web services on Apache Geronimo has become easier and less cumbersome. Axis2 is an improvement over Axis, because a better architecture was implemented for Axis2, deployment was simplified, and Axis2 provides more data binding support. This article describes using a sample Web service and migrating a previously developed Web service in Axis to Axis2. The various changes and improvements in Axis2 over Axis are discussed as well as how this relates to deploying the newly migrated Axis2 Web service on the Geronimo application server.
Introduction
Apache Axis and Axis2 were designed to streamline the process of creating Web services. From Web Services Description Language (WSDL), both Axis and Axis2 automatically generate the Java™ classes -- using the WSDL2Java tool -- that you need to construct and deploy your Web service on Apache Geronimo.
The Apache Axis project started as a follow-on project to the Apache Simple Object Access Protocol (SOAP) project as a way to implement Web services and is a proven technology. In fact, several companies use Axis as a means to develop and implement Web services in their products.
Axis2 was envisaged to have higher performance than Axis through a new modular architecture. According to the Axis2 Apache Web site, "Apache Axis2 is an effort to...[build] upon the 'handler chain' model developed in Axis1... Axis2 introduces a more flexible pipeline architecture which leads itself to greater modularity and extensibility. This extensibility will allow Axis2 to act as a foundation for a growing constellation of associated Web services protocols..." The goal with Web services is to support the various emerging standards that are being created (see the Resources section later in this tutorial for some links). However, Axis made this difficult, because it doesn't have a clean enough extension layer. Such problems are being overcome with the new Axis2, so the current plan with Axis2 is to implement new Web services protocols, starting with WS-Security, WS-Addressing, and WS-ReliableMessaging, and then expand from there.
In fact, Axis2 hasn't even hit a full release yet; but it's very functional and definitely ready for prime time. The amazing thing is that it took the Apache team only five months to go from a milestone 1 release to version 0.9, which is definitely usable.
Thus, with all the improvements in Axis2, several developers will want to know the differences, and most importantly, know what changes are needed to port their Axis Web service over to Axis2. This article does just that, all the way to deployment and testing on Geronimo, assuming no prior knowledge of both Axis and Axis2. Also, this article assumes that the original Axis Web service was built using the Axis WSDL2Java tool on an existing WSDL (you'll use databinding via xmlbeans in Axis2).
To begin the migration described in this article, you start by downloading and installing the necessary technologies.
Getting started
For this article, you need the following products and technologies:
Unarchive each .jar, .war, .zip, or tar.gz file to separate directories, and you're ready to start Apache Geronimo. Go to the <geronimo-install-dir>/bin, and type the following to start Geronimo:
java -jar server.jar
Geronimo loads and waits for you to deploy your Web services later in the article. Now let's move on to the Axis2 improvements over Axis.
Improvements
Axis2 has several improvements over Axis that help with its speed and response time as well as its scalability and modularity. Unfortunately, backward compatibility is an issue. As a product progresses, backward compatibility is desired so as to not leave the previous generation behind; however, because Axis and Axis2 have been developed on different architectures, the API can be difficult to support. Axis2 supports Axis Data Binding (ADB), which is quite similar to Axis, but is still limited and less powerful than Axis2's default data binding support.
In regard to a modular architecture, you can easily compare modularity between the two as you use the WSDL2Java tool throughout this article. In fact, the Axis2 WSDL2Java tool generates a few hundred files and even more files if you're implementing other Web services standards, because each element and complex type in the XSD schema gets its own class and an implementation class. This greatly improves the xmlbeans data binding support for Axis2 -- every message and SOAP document object gets its own object.
Another huge improvement is deployment. Deploying an Axis Web service is cumbersome and takes a bit of digging around to sort everything out, with Web Services Deployment Descriptor (.wsdd) files being the best supported method. However, with Axis it's a matter of building an Axis Archive file (.aar), which you can easily deploy and redeploy using the Axis2 Web interface.
You'll see each of these improvements throughout the rest of this article. Let's move on to a brief description about the Web service.
The Web service
This article uses a simple Web service defined in WSDL that you can find in the Download section. It has a single operation, Ask, that takes in a single String parameter, question, and returns a single String as a response, answer. The XSD for the Ask and AskResponse elements of the Web service are shown in Listing 1.
Listing 1. Ask and AskResponse
<xsd:element name="Ask">
<xsd:complexType>
<xsd:sequence>
<xsd:element minOccurs="1" maxOccurs="1"
name="question" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="AskResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element minOccurs="1" maxOccurs="1"
name="answer" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
|
Full particulars of the WSDL file are left as an exercise. You can learn more about WSDL by following the links in the Resources section.
The Axis Web service
For completeness, you now build the Axis Web service and define its internals. The next section deals with the changes and differences needed for migration to Axis2.
To create the Java files for your Web service via Axis, you need to make sure that every .jar file in the <axis-install-dir>/lib directory is in your CLASSPATH. Then type the following to create your Web service:
java org.apache.axis.wsdl.WSDL2Java -S true ask.wsdl
The files are created in the ./com/example/www/ask directory. To implement your Axis Web service, you only need to modify one file, which is covered next.
Port binding implementation
Axis implements Web services much more simply than its successor, Axis2. Axis handles only basic primitive objects, such as String, int, float, and so on.
In Axis, the AskPortBindingImpl.java file is where you implement your Web service. Find it at ./com/example/www/ask/AskPortBindingImpl.java, and define it, as shown in Listing 2.
Listing 2. Handling the Ask operation in Axis
package com.example.www.ask;
public class AskPortBindingImpl implements
com.example.www.ask.AskPortType{
public java.lang.String ask(java.lang.String question)
throws java.rmi.RemoteException {
System.out.println("QUESTION ASKED: " + question);
return "Why ask me, Georgy, I don't know anything!!!";
}
}
|
The class contains the single Ask operation defined in the ask.wsdl file, which takes in a question, a String, and returns an answer, a String. Next you define the client stub that communicates with the Axis Web service.
The Java client
Here you define a command-line client in the Java language that communicates with your Axis Web service. Define a file, AskServiceTestCase.java, in the same directory as the AskPortBindingImpl.java file, as shown in Listing 3.
Listing 3. The Axis client stub
package com.example.www.ask;
public class AskServiceTestCase {
public static void main(String args[]) throws Exception {
com.example.www.ask.AskPortBindingStub binding = null;
try {
binding = (com.example.www.ask.AskPortBindingStub)
new com.example.www.ask.
AskServiceLocator().getAskPort();
}
catch (Exception e) {
e.printStackTrace();
}
// Test operation
java.lang.String answer = null;
answer = binding.ask(new java.lang.String("I have a hole in"+
" my bucket, dear Liza, with what should I fix it?"));
System.out.println("ANSWER RECEIVED: " + answer);
}
}
|
The client stub object is created in the try statement using the AskServiceLocator object that defines the service address and port for the service as defined in the WSDL. The last two lines call the Ask operation passing in a question. The answer is received and displayed back to the user.
Deploying on Geronimo and running the client
Now you can set up your Axis installation for deployment on Geronimo, packaged with your Axis Web service. Create the server-config.wsdd file that contains the deployment descriptor for your Web service by going to the directory where your Axis Web service exists and typing the following:
(Note: for this entire section, make sure the .jar files in the <axis-install-dir>/lib are in your CLASSPATH.)
cd com/example/www/ask
java org.apache.axis.utils.Admin server com\example\www\ask\deploy.wsdd
This creates the server-config.wsdd file. Copy this file to the WEB-INF directory:
cp server-config.wsdd <axis-install-dir>/webapps/axis/WEB-INF
Now go up four directories to the root of your Axis Web service, and compile the Java files. Then copy them to the Axis WEB-INF/classes directory:
javac com/example/www/ask/*.java
cp -r com <axis-install-dir>/webapps/axis/WEB-INF/classes
Now WAR-up and deploy Axis along with your Web service:
cd <axis-install-dir>/webapps/axis
jar -cvf axis.war *
mv axis.war <geronimo-install-dir>/deploy
The Geronimo Hot Deployer should now kick in and deploy Axis. Once deployed, run the client code in the AskServiceTestCase class:
java com.example.www.ask.AskServiceTestCase
You should see this as output from the server:
QUESTION ASKED: I have a hole in my bucket, dear Liza, with what should I fix it?
And you should see the following from the client:
ANSWER RECEIVED: Why ask me, Georgy, I don't know anything!!!
Those were a lot of steps to deploy! See how much easier it is to deploy your Axis2 Web service next.
Comparing and contrasting Axis2
Notice that Axis2 is very different just by looking at the skeleton and client in this section, which will be compared and contrasted with Axis.
Even usage of the WSDL2Java tool is different. Create the Axis2 Java classes by typing the following, after making sure that all .jar files in the <axis2-install-dir>/WEB-INF/lib directory are in your CLASSPATH:
java org.apache.axis2.wsdl.WSDL2Java -uri ask.wsdl -ss -sd
-p com.ibm.axis2.ask -d xmlbeans
Now type the following to create the client stub:
java org.apache.axis2.wsdl.WSDL2Java -uri ask.wsdl -sd
-p com.ibm.axis2.ask -d xmlbeans
The skeleton and client stub files get created at the ./src/com/ibm/axis2/ask directory, and the AskDocument and AskResonseDocument classes get created at the ./src/com/example/www/ask/xsd directory. Several xmlsoap classes get created at ./src/org/xmlsoap/schemas/soap/encoding. Thus, you can already see that, although Axis2 can seem more complex at first, with so many classes being created, Axis2 has a much more modular architecture and is more efficient with this architecture.
Server skeleton
In Axis2, you define the server skeleton class itself rather than an implementation object. Also, you can see in the code below just how modular the architecture is. Find and define the file found at ./src/com/ibm/axis2/ask/AskPortTypeSkeleton.java, as shown in Listing 4.
Listing 4. Defining the server skeleton
package com.ibm.axis2.ask;
public class AskPortTypeSkeleton {
public com.example.www.ask.xsd.AskResponseDocument Ask
(com.example.www.ask.xsd.AskDocument param0 ){
System.out.println("QUESTION ASKED: " +
param0.getAsk().getQuestion());
com.example.www.ask.xsd.AskResponseDocument res =
com.example.www.ask.xsd.AskResponseDocument.
Factory.newInstance();
com.example.www.ask.xsd.AskResponseDocument.AskResponse res2 =
res.addNewAskResponse();
res2.setAnswer("Why ask me, Georgy, I don't know anything!!!");
return res;
}
}
|
Notice that the return type and incoming object of the Ask operation is an AskResponseDocument and AskDocument, respectively, rather than just simply String objects. The question, like Axis is also a String object, can be retrieved by first retrieving the Ask object inside the incoming AskDocument object and by calling the Ask objects getQuestion() method.
The last seven lines in boldface create the response. First an AskResponseDocument object is instantiated with an AskResponse object created within the AskResponseDocument. Finally, the answer is set by calling the AskResponse object's setAnswer() method. Notice that the AskResponseDocument is returned back to the calling SOAP client as the response. The answer and AskResponse object are encapsulated inside the AskResponseDocument object.
With the more modular architecture of Axis2, as exemplified above, adding more features and abilities to Axis2 proves easier to code up and implement.
The Java client
Calling the Web service is also quite different, reflecting Axis2's improvements. Create a file at ./src/com/ibm/axis2/ask/Client.java, and define it, as shown in Listing 5.
Listing 5. Axis2 client code
package com.ibm.axis2.ask;
import com.example.www.ask.xsd.*;
public class Client{
public static void main(java.lang.String args[]){
try{
AskPortTypeStub stub = new AskPortTypeStub(null,
"http://localhost:8080/axis2/services/AskService");
ask(stub);
} catch(Exception e){
e.printStackTrace();
}
}
/* Ask */
public static boolean ask(AskPortTypeStub stub){
try{
AskDocument reqDoc = AskDocument.Factory.newInstance();
AskDocument.Ask reqDoc2 = reqDoc.addNewAsk();
reqDoc2.setQuestion("I have a hole in"+
" my bucket, dear Liza, with what should I fix it?");
AskResponseDocument resDoc = stub.Ask(reqDoc);
System.out.println("ANSWER RECEIVED: " +
resDoc.getAskResponse().getAnswer());
return true;
} catch(Exception e){
e.printStackTrace();
}
return false;
}
}
|
The notable code is in boldface. The first line creates the client stub by taking in the service endpoint or URL of the service. Then the ask() method gets called, which creates the Ask request, similar to how the AskResponseDocument was created in Listing 4. The request is sent off with the call to stub.Ask(), and the response is placed in resDoc. The answer received can then be retrieved by calling resDoc.getAskResponse().getAnswer(), similar to how you retrieved the question at the beginning of the skeleton code in Listing 4.
The Web services you've looked at in both Axis and Axis2 so far have been synchronous, also known as blocking Web service calls. Axis2 has much greater asynchronous support through nonblocking calls, which you can play around with in the AskPortTypeCallbackHandler class and by calling stub.startAsk() in the above client code rather than stub.Ask().
Deploying on Geronimo and running the client
Deploying your Axis2 Web service is much easier and requires fewer steps than Axis. Again, in this section, make sure that all .jar files in the <axis2-install-dir>/WEB-INF/lib directory are in your CLASSPATH. Now deploy the axis2.war you downloaded earlier onto Geronimo:
cp axis2.war <geronimo-install-dir>/deploy
Compile all the Java files that comprise your Axis2 Web service by typing:
ant jar.server
An AskService.aar file just got created at ./build/lib/AskService.aar, and this file is ready for deployment on Axis2 via its Web interface. Open a browser, and go to http://localhost:8080/axis2/Login.jsp.
Now log in using admin and axis2 as your username and password, respectively (see Figure 1).
Figure 1. Logging in to Axis2
Next, point your browser to http://localhost:8080/axis2/upload.jsp.
Click the Browse button, find the Ask.aar file you just created, and then click Open. Now click Upload (see Figure 2). After a few seconds your Web service will be fully deployed.
Figure 2. Uploading your Axis2 Web service
Now that you've deployed the Web service, you can test it by running the client. To do this, you need to add the AskService.aar file and the XBeans-packaged.jar file (both found at the ./build/lib directory) to your CLASSPATH. After you've completed this, type the following to run the client:
java com.ibm.axis2.ask.Client
You should see the same output messages about Liza and Georgy from the server and console output, respectively, as you saw when you ran the Axis Web service's client.
Note that deployment in Axis2 is much simpler than Axis, thanks to the handy build.xml file, Axis Archive files, and the functional Web interface!
Summary
You've successfully migrated an Axis Web service over to Axis2 using Apache Geronimo. You've also seen first hand the improvements Axis2 has made over Axis. Take a look at the Resources section to see how you can learn more about this grand new tool, Axis2.
Download | Description | Name | Size | Download method |
|---|
| Sample code | axis2source.zip | 10KB | HTTP |
|---|
Resources Learn
Get products and technologies
Discuss
About the author  | | | Tyler Anderson graduated with a degree in computer science from Brigham Young University in 2004 and graduated with a master's degree in computer engineering in December 2005, also from Brigham Young University. He is currently an engineer for Stexar Corp., based in Beaverton, Ore. |
Rate this page
| 
