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.

Back to top

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.

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.

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.

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.

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

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

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

jar cf amazon.war 

Now you're ready to deploy this code on Geronimo.

Back to top

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:

java -jar bin/server.jar

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.

You have now successfully deployed your first Web services consumer in Geronimo.

Back to top

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.

Back to top

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

Rate this article

Comments

Back to top

Table of contents

• Geronimo supports Web services standards
• Consuming Amazon Web Services
• Deploy the consumer code on Geronimo
• Standard J2EE Web services
• Summary
• Resources
• About the author
• Comments

Next steps from IBM

Rational Application Developer features provide the comprehensive Integrated Development Environment (IDE) used to develop J2EE applications requiring Servlets and JavaServer Pages (JSPs).

---

• Try: Try the free Rational Application Developer, which helps developers quickly design, develop, test, analyze, and deploy high-quality Java, Javaserver pages, and J2EE applications.
• Article: Learn how you can deliver accurate, higher-quality J2EE apps with Rational Application Developer, open source JUnit and JUnitEE test frameworks.
• Tutorial: Build a Facebook application using PHP, the Spring framework, and J2EE.
• Demo: This demo shows how to use the new Java EE 5 Java Persistence API (JPA) framework.
• Buy: Rational Application Developer

Dig deeper into Java on developerWorks

Discover knowledge paths

Skill-building guides for Java, Linux, open source, cloud, business analytics, and more.

Special offers