ONJava.com    
 Published on ONJava.com (http://www.onjava.com/)
 See this if you're having trouble printing code examples


What Is Geronimo?

by Kunal Jaggi
07/19/2006
Geronimo
Geronimo is the newest Apache-initiated, open source application server. Licensed under the Apache license (version 2.0), Geronimo is a Java EE 1.4 certified app server.

In This Article:

  1. Why Geronimo?
  2. A Look Under the Hood
  3. Get Started with Geronimo
  4. Sample Application
  5. Deployment Plans
  6. Code Your First Geronimo App
  7. Build the App
  8. Deploy the App
  9. Test the App

Based in an integration of best-of-breed open source technologies, and with a vibrant and thriving community backing a certified open source server, Geronimo is set to take the enterprise market by storm. This article will introduce you to Geronimo and give you the basics you need for developing and deploying a simple Java EE web application on Geronimo.

Why Geronimo?

Geronimo is not the only open source app server available in the market. There are other open source Java EE app servers out there as well, such as JOnAS from ObjectWeb. However, Geronimo fills a need that other application servers do not. With Geronimo, components can be easily integrated. Its key aim is to support custom builds, geared to the needs of specific applications. Geronimo offers choices. For instance, if you don't want transaction management, you can go for a web-tier container such as Tomcat or Jetty. Geronimo supports the assembly of custom components pretty easily. In short, you can make it whatever you need it to be. This means Geronimo is much more than simply an app server; it offers a framework that can be used to glue together different components.

Geronimo doesn't try to reinvent the wheel, and it's not a rip-off of any of the existing open source frameworks or tools. Rather, Geronimo is an integration of several open source projects, some of which are shown below:

Tier Open source project Description
Web tier Tomcat Reference implementation for Java Servlet 2.4 and JavaServer Pages (JSP) 2.0.
Jetty A web-tier servlet container that supports Servlets and JSPs.
Business tier OpenEJB An open source Enterprise JavaBeans container that also supports Container Managed Persistence 2 (CMP2) and EJB Query Language (EJBQL).
EIS tier ActiveMQ Open source Java Message Service (JMS) applications provider and supporter of message driven beans (MDBs).
HOWL Distributed transactions and support for transaction logging.

One of the most elegant features of Geronimo is that it doesn't require a restart. Unlike other web- and business-tier containers, which require restarting the container for any configuration change, Geronimo is tailored from the ground up to support dynamic class loading, and keeps running as an uninterrupted service.

A Look Under the Hood

Geronimo is a loose integration of components called Geronimo Beans or simply GBeans. GBeans, which are the building blocks of Geronimo, are managed beans based around an IoC container concept, and they're used to add services to the Geronimo kernel. Almost everything in Geronimo is a GBean.

It's easy to extend Geronimo by deploying new GBeans. GBeans define the capabilities of the server and are registered with the kernel as they are deployed. The GBean components follow a particular life cycle as the kernel creates them, injects dependencies, notifies events, and calls their methods. Each GBean can maintain a state, depend on other GBeans, and contain logic that defines its functionality. The GBean architecture is a Dependency Injection (DI) configuration and management system. A GBean is plugged to the kernel through a plan, which is an XML-based configuration file. Further, components can be easily removed by editing the configuration files. For more information on Geronimo GBean architecture and IoC containers, refer to the Resources section.

Get Started with Geronimo

Geronimo requires Java SE 1.4 (or higher, but earlier than SE 5). The latest milestone release available as of this writing is M5. Unzip the Geronimo with Tomcat container zip at some location, and set the GERONIMO_HOME environment variable to this location.

Start Geronimo by booting its kernel. Once started, Geronimo will load all predefined modules along with any other application modules as shown below (for brevity, not all fields are shown here):

D:\>cd %GERONIMO_HOME%
D:\geronimo-1.0>java -jar bin/server.jar
Booting Geronimo Kernel (in Java 1.4.2_08)...
Starting Geronimo Application Server
[********************] 100%  44s Startup complete
  Listening on Ports:
    1527 0.0.0.0 Derby Connector
    8080 0.0.0.0 Tomcat Connector HTTP
    8443 0.0.0.0 Tomcat Connector HTTPS

  Started Application Modules:
    EAR: geronimo/daytrader-derby-tomcat/1.0/car
    EAR: geronimo/uddi-tomcat/1.0/car
    WAR: geronimo/welcome-tomcat/1.0/car

  Web Applications:
    http://WINKJ185011-NZR:8080/
    http://WINKJ185011-NZR:8080/console
Geronimo Application Server started

Next, verify the Geronimo installation by accessing the Geronimo console window at http://localhost:8080/console, as shown in Figure 1 below. Use the default username (system) and password (manager). Stopping Geronimo is easy; Ctrl-C stops the app server.

Apache Geronimo Console
Figure 1. Apache Geronimo Console

Sample Application

For an introductory article like this, we'll create a simple web application and deploy it on Geronimo. Please make sure that the following environment variables are set correctly.

Environment variable Purpose
JAVA_HOME Indicates the base directory of your standard Java SE installation.
GERONIMO_HOME Set to the root directory of your Geronimo installation.
ANT_HOME Set to the root directory of your Ant installation.
GERONIMO_DEV Indicates the base directory of application development space.
PATH Ensure that ANT_HOME/bin is in your PATH.

Within GERONIMO_DEV, create the following directories:

Deployment Plans

We'll need two deployment plans, namely web.xml and geronimo-web.xml. Before we dive into these, I'll clarify their differences. The following table will help differentiate between the two deployment plans and their roles.

Deployment Plan Type Location Purpose
web.xml Standard Java EE web deployment descriptor This must be stored as part of the WAR file under the WEB-INF subdirectory. Used for specifying declarative security, configuring error and welcome pages, servlet declaration and mapping, filter definition and mapping, configuring initialization parameters, registering listener classes, etc.
geronimo-web.xml Geronimo-specific deployment plan Under the private WEB-INF subdirectory. The geronimo-web.xml file defines Geronimo-specific parts such as resource references and security mapping configuration.

Code Your First Geronimo App

We'll begin by creating a simple JSP page to greet the user and display the current date and time. Create hello.jsp as shown below and place it in the GERONIMO_DEV/web directory:

<html>
<head>
<jsp:useBean id="currentdate"
    class="java.util.Date" />
<title>Geronimo JSP App</title>
</head>
<body>
<h3>Hello world from Geronimo!! on
${currentdate}</h3>
</body>
</html>

Next, create the following two deployment plans and place them inside the GERONIMO_DEV/etc directory. The first deployment plan, web.xml, is the standard Java EE deployment descriptor as shown here:

<?xml version="1.0" encoding="UTF-8"?>
<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_4.xsd"
version="2.4">

    <display-name> Hello JSP Web App
    </display-name>
    <description>First Geronimo App
    </description>
</web-app>

The following code snippet shows the Geronimo-specific deployment plan, geronimo-web.xml:

<?xml version="1.0" encoding="UTF-8"?>
<web-app
xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.0"
xmlns:sec="http://geronimo.apache.org/xml/ns/security-1.0"
configId="com/onjava/safari/myApp">


  <context-root>/myApp</context-root>
  <context-priority-classloader>false\
  </context-priority-classloader>
</web-app>

The configId attribute specifies the name of our application, com/onjava/safari/myApp. Next, we set up the context (/myApp), which is the directory where our application is placed once deployed to Geronimo.

Build the App

Next, we'll do an incremental build with Ant. We need an Ant build file (build.xml), placed in GERONIMO_DEV. The build.xml is a well-formatted XML file that describes the build process of our application as shown below:

<project name="GeronimoApp" default="war"
basedir=".">

  <property environment="env"/>

 <path id="cp">
      <pathelement path="${java.class.path}"/>
      <fileset dir="${env.GERONIMO_HOME}/
      repository/org.apache.geronimo.specs/jars">
        <include name="*.jar"/>
      </fileset>
    </path>

 <target name="prepare">
    <mkdir dir="dist"/>
    <mkdir dir="classes"/>
    <mkdir dir="build"/>

    <delete>
     <fileset dir="classes"
       includes="**/*.class"/>
    </delete>

    <mkdir dir="build/WEB-INF"/>
    <mkdir dir="build/WEB-INF/lib"/>

    <copy file="etc/web.xml" todir="build/WEB-INF"/>
    <copy file="etc/geronimo-web.xml"
    todir="build/WEB-INF" />

    <copy todir="build">
      <fileset dir="web"/>
    </copy>

 </target>

<target name="compile" depends="prepare">
    <javac srcdir="src" destdir="classes"
    debug="on" deprecation="off">
      <classpath refid="cp"/>
    </javac>
</target>

<target name="war" depends="compile">
   <war destfile="dist/safari.war"
   webxml="build/WEB-INF/web.xml">
    <classes dir="classes" />
      <fileset dir="build">
        <exclude name="WEB-INF/web.xml"/>
      </fileset>
    </war>
 </target>

</project>

Following is the output we'll get after running the Ant script:

D:\>cd %GERONIMO_DEV%

D:\gdev>ant
Buildfile: build.xml

prepare:
  [mkdir] Created dir: D:\gdev\dist
  [mkdir] Created dir: D:\gdev\classes
  [mkdir] Created dir: D:\gdev\build
  [mkdir] Created dir: D:\gdev\build\WEB-INF
  [mkdir] Created dir: D:\gdev\build\WEB-INF\lib
   [copy] Copying 1 file to D:\gdev\build\WEB-INF
   [copy] Copying 1 file to D:\gdev\build\WEB-INF
   [copy] Copying 1 file to D:\gdev\build

compile:

war:
      [war] Building war: D:\gdev\dist\safari.war

BUILD SUCCESSFUL
Total time: 3 seconds

This creates a .war file (placed inside the /dist directory), which will be deployed inside the Tomcat container shipped with Geronimo app server.

Deploy the App

Here, we'll use Geronimo's deployer to deploy the .war file. Geronimo provides a deploy command for this purpose. You must provide an administration login (system/manager) on the command line while deploying. If not explicitly specified, the deployer will ask you for it. The following command deploys the .war file:

D:\>cd %GERONIMO_HOME%

D:\geronimo-1.0>java -jar bin/deployer.jar --user
system --password manager deploy
%GERONIMO_DEV%/dist/safari.war
    Deployed com/onjava/safari/myApp @
    http://WINKJ185011-NZR:8080/myApp

The deployer is smart enough to figure out the kind of component being deployed; we just give it our .war file and the deployer will deploy the file as a Web application. The deployer.jar deploys the application module based on the information provided in the deployment plan (geronimo-web.xml) to the Geronimo server.

Alternatively, you can manually deploy the .war file using Geronimo's console window (as shown in Figure 2). Select the Deploy New link from the Console Navigation panel on the left, browse to the WAR file, and then click the Install button.

Deploy new web app in Geronimo
Figure 2. Deploy new web app in Geronimo

Once deployed, the web app will appear under the "Installed Web Applications" listing in Geronimo's console window as shown below in Figure 3.

Installed Web Applications
Figure 3. Installed Web Applications

Test the App

All that said, let's cheerily run through it. Start up a browser and try the URL http://localhost:8080/myApp/hello.jsp. The Tomcat web container processes and executes the JSP as shown in Figure 4 below:

Test JSP running on Geronimo app server
Figure 4. Test JSP running on Geronimo app server

Conclusion

Geronimo is modular by nature. This allows easy plugging of modules such as Apache Derby, which ships with Geronimo. Integration of frameworks like Spring is seamless. So, what's holding you up? It's time to give Geronimo a spin.

Resources

Kunal Jaggi is an independent Java consultant, primarily focused on enterprise solutions with Java-based technologies.


Return to ONJava.com.

Copyright © 2009 O'Reilly Media, Inc.