Level: Intermediate Kunal Mittal (kunal@kunalmittal.com), Portal/J2EE architect, consultant, freelance writer
28 Jun 2005 Deciding on an application server to support your Web services development efforts? Meet the Apache Geronimo application server, one of the latest projects from the Apache Software Foundation. Java™ specialist Kunal Mittal introduces you to Geronimo's Web services capabilities by showing you how to write and develop standard J2EE Web services code in Geronimo. You'll learn how to consume Amazon Web services using Apache Axis as the underlying Simple Object Access Protocol (SOAP) implementation, and you'll see how to use a simple JavaServer Pages (JSP)-based client to access the Web service.
Geronimo supports Web services standards
The new Apache Geronimo project is a powerful open source J2EE application server built on top of J2EE 1.4 standards. It uses all open source
implementations and will soon be J2EE compliant. Interestingly, Geronimo is built upon a collection of code gathered from many other open source projects. Geronimo uses Apache Axis and Apache Scout (see Resources) to support the following Web services standards:
- Java Specification request (JSR) 109 (implementing Enterprise Web Services 1.1)
- Java API for XML-based Remote Procedure Call (JAX-RPC)
- SOAP with Attachments API for Java (SAAJ) 1.2
- Java API for XML Registries (JAXR) 1.0
Support for these standards makes Geronimo a viable option when deciding
on an application server to support your Web services development efforts. If you've already used the open source projects that make up Geronimo, the transition to Geronimo as your deployment
container should come naturally.
To make development and deployment of J2EE applications on Geronimo even easier,
several Eclipse plug-ins are also available. These plug-ins are part of the Eclipse Web
Tools Platform (WTP) (scheduled to have its 1.0 launch in July 2005). See Resources for links to the WTP and related information.
Using Amazon Web Services (AWS) as an example, you'll learn how to consume Web services with Geronimo.
You'll be guided through
taking the Web Services Description Language (WSDL) for AWS and using Apache Axis to build the consumer
code. You'll see a simple Java class that consumes the Web service and learn how this class is invoked from a JSP file to display the results of the Web service. Finally, you'll bundle the code as a J2EE WAR file and deploy it on Geronimo.
Consuming Amazon Web Services
To consume AWS, you need to build the service consumer using Apache Axis as the
SOAP implementation. (Axis is the underlying SOAP implementation that
Geronimo supports.) If you have done this in the past and have the code, feel free to
jump ahead.
 | | At the time of this writing, Geronimo is not a production-ready application server, but it is going through the J2EE certification process. When released, it will be
J2EE 1.4 certified. |
|
Requirements for generating AWS code
Begin by setting up your environment. To generate the AWS consumer code, you
need four things:
- Java software development kit (JDK) 1.4.2 or later. (See Resources to link to the Java Web site.)
- Apache Axis 1.1 or later. (See Resources for the Apache Axis Web link.)
- The Web Services Description Language (WSDL) for the Web service. (See Resources for a link to download the WSDL.)
- An AWS subscription ID from Amazon so you can use their Web services. (See Resources for a link to register for the free ID.)
Set up your environment
The next series of steps guides you through setting up your environment by downloading the elements listed above as follows:
- Install the JDK into C:\jdk_142_05. Set the JAVA_HOME to this directory.
- Extract Apache Axis into C:\axis1-2, and define AXIS_HOME as this directory.
- Copy the WSDL file into the AXIS_HOME directory.
- Register for the AWS subscription ID.
Now that you have the basic environment ready to go, you can start
generating the code to consume the Web service.
Generate the Java code from the WSDL
First, generate the Java code that will consume the Web service
from the WSDL file. Apache Axis comes with a utility called WSDL2Java
that performs this task for you. To run this tool, make sure the following Java
Archive (JAR) files are in your classpath. The sample setenv.bat script shown
in Listing 1 does this for you.
Listing 1. Setenv.bat
set AXIS_HOME=c:\axis-1-2
set CLASSPATH=.
set CLASSPATH=%AXIS_HOME%\lib\axis.jar;%CLASSPATH%
set CLASSPATH=%AXIS_HOME%\lib\commons-discovery.jar;%CLASSPATH%
set CLASSPATH=%AXIS_HOME%\lib\commons-logging.jar;%CLASSPATH%
set CLASSPATH=%AXIS_HOME%\lib\jaxrpc.jar;%CLASSPATH%
set CLASSPATH=%AXIS_HOME%\lib\saaj.jar;%CLASSPATH%
set CLASSPATH=%AXIS_HOME%\lib\log4j-1.2.8.jar;%CLASSPATH%
set CLASSPATH=%AXIS_HOME%\lib\wsdl4j.jar;%CLASSPATH%
|
Now, from the AXIS_HOME directory, run the following command to
generate the Java code:
java org.apache.axis.wsdl.WSDL2Java AWSECommerceService.wsdl
|
This process takes a few seconds to create a directory called com
under AXIS_HOME. Now you can start creating a Web Archive (WAR) file
that you will eventually deploy on Geronimo.
Create a directory called C:\amazon-client. You'll use this directory to store
the code for the WAR file. Under this directory, create a directory called
WEB-INF and a directory called src. Copy the com directory from your
AXIS_HOME to C:\amazon-client\WEB-INF\src.
This code is the basic code for consuming a Web service. For now, you don't need to go into the details of this code.
Write code to consume the Web service
Next, write a client to the Web service. In this example,
you'll write a simple Java class that calls the appropriate classes that were
generated using WSDL2Java. (Tools such as Eclipse and IBM®
Rational® Application Developer generate a stubbed version of this code
for you automatically. Thus, I won't spend much time on the specifics of
how to write this code.)
For simplicity, I created a class called AmazonClient
in the same package structure that was generated using WSDL2Java
(com.amazon.xml.AWSECommerceServer). The code for this class is shown
in Listing 2. This class exposes a single method called lookupISBN.
As the name suggests, this method calls AWS and returns information about the
book represented by the ISBN number passed in.
Listing 2. AmazonClient.java
package com.amazon.xml.AWSECommerceServer;
import java.lang.*;
import java.util.*;
public class AmazonClient {
public AmazonClient() { }
public Items[] lookupISBN(String isbn) throws Exception {
try {
System.out.println("Given ISBN is " + isbn);
AWSECommerceServiceLocator locator =
new AWSECommerceServiceLocator();
AWSECommerceServicePortType type =
locator.getAWSECommerceServicePort();
String itemId[] = {isbn.trim()};
ItemLookup lookup = new ItemLookup();
lookup.setAssociateTag("MY ID"); // fill in your own
lookup.setSubscriptionId("MY ID"); // fill in your own
ItemLookupRequest lookupReq = new ItemLookupRequest();
lookupReq.setMerchantId("All");
lookupReq.setItemId(itemId);
lookupReq.setResponseGroup(new String[]
{"Medium", "OfferFull", "Variations", "Images"});
ItemLookupRequest[] requests = lookup.getRequest();
requests = new ItemLookupRequest[1];
requests[0] = lookupReq;
lookup.setRequest(requests);
ItemLookupResponse response =
type.itemLookup(lookup);
Items[] items = response.getItems();
if (items != null && items.length > 0) {
System.out.println("Number of results "+ items.length);
return items;
}
} catch (javax.xml.rpc.ServiceException se) {
throw new Exception(se.getMessage());
}
return new Items[0];
}
}
|
You must register with Amazon to get a subscription ID (see Consuming Amazon Web Services above). After you get your subscription ID, replace it in the code in Listing 2.
Now you're ready to compile this code. After you have run the setenv.bat file,
you should be able to compile the code easily by running javac *.java:. You get
several class files in this directory. For simplicity of packaging, I copy the
entire src directory into a new directory called WEB-INF/classes. Then, from
WEB-INF/classes, I delete all the Java source files; from WEB-INF/src, I delete
all the class files. If you use an integrated development environment (IDE), such
as Eclipse, a lot of this manual work is done for you automatically.
Now you can invoke your Web service and see the results. Use a JSP file to do this.
Write a JSP file to display results from the Web service
Under the amazonclient directory, create a JSP file called searchAmazon.jsp.
The code is shown in Listing 3.
In the JSP file shown in Listing 3, you're calling the AmazonClient
class that you defined and receiving an array of Item objects. You then iterate over
this array to display the values.
| |
The point here is not to demonstrate good J2EE coding practices, but rather to
demonstrate that all the code you're writing is standard J2EE code that can easily
be deployed on the IBM WebSphere®; platform, Apache Tomcat, Apache Geronimo, JBoss, or
BEA WebLogic.
|
|
You now have all the code you need.
Final steps before deploying the code
The last step is to set up the deployment descriptors so you can
deploy the WAR file on Geronimo. Under the WEB-INF directory, create
two simple XML deployment descriptors. The first is the standard J2EE WAR
deployment descriptor, called web.xml (see Listing 4).
Listing 4. web.xml
<?xml version="1.0" encoding="ISO-8859-1" ?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://java.sun.com/xml/ns/j2ee/web-app_2_3.xsd"
version="2.3">
<display-name>Amazon Sample</display-name>
<welcome-file-list>
<welcome-file>t;searchAmazon.jsp</welcome-file>
</welcome-file-list>
</web-app>
|
Geronimo requires a geronimo-jetty.xml descriptor. The code is shown in Listing 5.
Listing 5. geronimo-jetty.xml descriptor
<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app
xmlns="http://geronimo.apache.org/xml/ns/web/jetty"
xmlns:naming="http://geronimo.apache.org/xml/ns/naming"
configId="amazonclient"
parentId="amazonClient">
<context-root>/amazonclient</context-root>
<context-priority-classloader>true</context-priority-classloader>
</web-app>
|
Now you can save this file as a WAR file called amazon.war. To do so, run the
following command from the amazonclient directory:
Now you're ready to deploy this code on Geronimo.
Deploy the consumer code on Geronimo
Although you built a standard J2EE WAR file, you could easily deploy
this WAR file on any application server (or servlet engine) that you
choose. The next sections show you how to deploy this code on Geronimo.
Install Geronimo
Begin by downloading and installing Geronimo. (See Resources to link to the download site.)
Download the Geronimo 1.0 M3 Installer. To run the installer, use the following
command:
java -jar geronimo-1.0-M3-installer.jar
|
Follow the steps to install Geronimo into GERONIMO_HOME, defined as C:\geronimo.
Start Geronimo
To start the server, from the GERONIMO_HOME directory, run
the following command:
Deploy the Amazon.war file
You should have all the JAR files defined in the setenv batch file in your classpath.
Copy the files from AXIS_HOME\lib into GERONIMO_HOME\lib. Many of
these JAR files will already exist in GERONIMO_HOME\lib. Do not overwrite the
files that exist, even if the files you're copying are later versions of the same file.
Click No when prompted to replace existing files.
To deploy the amazon.war file on the application server, copy the WAR file into GERONIMO_HOME. From
this directory, run the following command:
java -jar bin/deployer.jar deploy amazon.war
|
Run searchAmazon.jsp
The last task left is to run the JSP file you wrote. Open a browser
and type http://localhost:8080/amazon/searchAmazon.jsp
in the address bar.
Figure 1 shows the result. You can modify the JSP file to include a form field
in which you can enter an ISBN number and get a result.
Figure 1: Execution of searchAmazon.jsp
You have now successfully deployed your first Web services
consumer in Geronimo.
Standard J2EE Web services
The example in this article is simple, but it has shown that Geronimo supports standard J2EE Web services. As an exercise in using Web services, you can try out other options available in AWS. For example, change the ISBN search to be a title or
author search. Then, from the Web service results, figure out how to display a URL that links to Amazon.com, and show an image
of the book.
Another interesting exercise is to use other J2EE technologies along with
Apache Axis to consume Web services, and then deploy them in Geronimo.
For example, replace the AmazonClient.java Plain Old Java Object (POJO) with
a stateless session Enterprise JavaBean (EJB) component, and then deploy it in
Geronimo.
You can take any Web service from webMethods or the Google
Web services as an example. If you apply the same steps described in this article,
you can quickly deploy a consumer to these Web services in Geronimo.
Summary
Now that you've met Geronimo and seen its Web services capabilities, you should be ready to get started using the Geronimo application server in your Web services development efforts.
Resources
- Participate in the discussion forum.
- Get more information about the Web Tools Platform project from eclipse.org.
- Download the M4 milestone of WTP from eclipse.org.
- Read "Create, deploy, and debug Apache Geronimo applications" (developerWorks, May 2005) for more information on how to use Eclipse to build and deploy Geronimo applications (developerWorks, May 2005).
- Read the two-part series on Geronimo. Part 1, "The J2EE 1.4 engine that could" is an introduction and conceptual overview to Geronimo; Part 2, "Tame this J2EE 1.4 bronco" covers Geronimo configuration, deployment, management, and provides hands-on examples of deploying Web applications and EJBs (developerWorks, May 2005).
- Learn how to "Boost application development with Amazon Web Services" (developerWorks, June 2005) in Part 1 of this multipart tutorial.
- Download the Java software development kit (JDK) 1.4.2 or later.
- Download Apache Axis 1.1 or later.
- Download the Web Services Description Language (WSDL).
- Register for a free AWS subscription ID from Amazon.
- Download Gluecode Standard Edition, an open source application server based on Apache Geronimo.
- Visit the official Apache Geronimo Web site.
- For more information about or to download Apache Axis, visit the Apache Axis Web site.
- Check out the Apache Scout Web site.
- For more information about JSP technology, visit the Sun Microsystems JavaServer Pages Technology site.
- Visit the Specifications section of the J2EE v1.4 Documentation page to learn about the J2EE 1.4 standards.
- For more articles on Web services, see the developerWorks SOA and Web services zone.
- For more articles on Java programming, see the developerWorks Java Technology zone.
- Get involved in the developerWorks community by participating in developerWorks blogs.
- 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.
- Browse all the Apache articles and free Apache tutorials available in the developerWorks Open source area.
- Browse for books on these and other technical topics.
-
See the Geronimo project area for a complete listing of free open source resources from developerWorks.
- Innovate your next open source development project with IBM trial software, available for download or on DVD.
About the author | | | Kunal Mittal is a consultant specializing in Java technology, J2EE, and Web services technologies. He is the co-author of and has contributed to several books on these topics. Kunal is currently working on a portal project for Sony Pictures Entertainment. For more information, visit the author's Web site. |
Rate this page
| 
