Discover the Geronimo Enterprise Server

This article was originally published in VSJ, which is now part of Developer Fusion.
Up until this year, if you created applications with a combination of Java servlets, JSPs (JavaServer Pages), JMS (Java Message Service) components and EJBs (Enterprise JavaBeans), you had very few inexpensive production deployment alternatives. While you could test your applications on evaluation copies of commercial servers such as IBM WebSphere, BEA Weblogic, SUN Java System Application Server, or the Oracle Application Server; production deployment on these servers could be very costly for small enterprises, or those with budgetary constraints. The only feasible alternative was the open source JBoss server. In 2005, this landscape changed in a dramatic way with the advent of the freely available, open source Apache Geronimo server.

This article tells you what you need to know about the Geronimo server, and guides you towards a rapid start working with the server. It provides an opportunity to install and run the server, then deploy a complete enterprise application.

Before you ask: what is Geronimo?

Geronimo is an open source project of the Apache Software Foundation, the same people who brought you such memorable titles as the Apache web server and the Tomcat servlets engine. It is an enterprise application server created to the J2EE 1.4 standard. This server will pass SUN’s stringent J2EE 1.4 certification before its official 1.0 release.

Figure 1 gives you a feel for the structure of the server, and how it may be useful to you.

Figure 1
Figure 1: Inside the Geronimo server

The yellow octagons are the application components that you can create and run within Geronimo. Web applications can be created using JSP and servlets, and the application can be accessed by users via standard web browsers. EJBs can also be deployed in Geronimo. EJBs can be accessed by other web tier components such as JSPs and servlets, or directly by standalone client applications. Other EJBs on the same (or another) server instance can also access Geronimo-hosted EJBs, as can legacy CORBA clients.

JMS destinations (topics and queues) can be created within Geronimo. A variety of JMS clients and components can make use of the JMS API to communicate with one another, and with components hosted within Geronimo. Geronimo also supports MDBs (Message Driven Beans), allowing these EJBs to be triggered by an incoming JMS request. Web services can be created and hosted within Geronimo. These web services can readily be consumed by web service clients created using any compatible technology (such as .NET).

Integrating robust sub-containers

You can see clearly in Figure 1 that Geronimo is actually composed of many other open source projects. In fact, you may even be already using one or more of these integrated projects. For example, if you have created and tested JSPs and servlets using Tomcat 5.5.x, you have already worked with the JSP/servlets container in Geronimo!

This style of integration allows the Geronimo team to use existing open source assets of the Apache Software Foundation (and those from other contributing open source groups with compatible software license). The benefits of this approach include:

  • there is no need to write container or engine code all over again
  • the technologies being integrated are mature and well-tested, adding to the robustness of the overall server from day one
  • the integrated technologies have existing user bases that can readily cross over to become users of the server
Other than Tomcat (and Jetty), ActiveMQ is used in handling JMS applications and MDBs. OpenEJB is used for hosting EJBs. Apache AXIS and Scout are used to support web services hosting in Geronimo.

Built into the Geronimo server is Apache Derby, providing a full-featured yet lightweight implementation of a relational database management system. This database engine is used internally by the Geronimo system, but is also available for general application use.

External legacy servers – for example, a relational database server – can be integrated via TranQL () – a persistence framework in Geronimo that can operate over JDBC.

The orchestration of all these sub-containers is the job of the Geronimo server. Namely, Geronimo provides the sub-containers with:

  • component lifecycle support, the control of individual container and applications that span across sub-containers to start and stop
  • configuration support, uniform access to setup and parameterisation of the individual sub-containers
  • server-wide security, including authentication and authorisation support
  • transaction support, potentially distributed across containers
  • manageability to enable the sub-containers to expose properties that can be externally monitored and managed via Java Management EXtension (JMX)

Downloading and installing Geronimo

The main project website for Geronimo is geronimo.apache.org – see Figure 2.

Figure 2
Figure 2: The Apache Geronimo home page

Click on the Downloads link on the left-hand column to download the latest release of Geronimo. At the time of writing, the latest available version is called Milestone 4 (or M4). Look for the binaries download, source code download is typically of interest only to advanced system developers. You will find the following choices:

Binaries file type Description
.zip Ideal for a Windows environment.
.tar.gz Perfect for *nix operating system.
Installer A self-installing binary distribution, suitable for both Windows and *nix systems.

If you select either the .zip or .tar.gz distribution, you can simply unzip (or tar zxvf) the file into your installation directory. If you’ve downloaded the installer version, perform the following at a command line:

java -jar <distribution JAR file name>

Minimum system requirements

Before you start the server, make sure you have:
  • a version of SUN’s JDK 1.4.2 installed and tested – if you don’t yet have this, you’ll need to download it
  • a system with at least 512 Mb of RAM
Geronimo works well with most modern Windows versions that support SUN’s JDK 1.4.2, including Windows XP, Windows 2003, and Windows 2000. It has also been tested with many distributions of Linux (Redhat, SuSE, etc.) and Mac OS X.

NOTE: JDK 5 will not work, at this time, with the M4 release of Geronimo. This is mainly due to dependencies on SUN’s JDK 1.4.2 CORBA code, and may change with future releases.

Running the server

Don’t be overwhelmed by the immense scope of the Geronimo server. Getting Geronimo up and running is actually quite straightforward. To start Geronimo, first change directory into your installation directory. Then use the following command:
java -jar bin/server.jar
This will start the Geronimo server with a default configuration. The server will print out its startup status (as percentage progress) as it starts the various built-in configurations.

NOTE: to shutdown the server, just type a Ctrl-c on your console window and it will start the shutdown process. Later on, Geronimo will most likely be able to run as a system service.

The startup screen shows the services that have been started by the default configuration, and also the ports that they are listening to. For example, you can see in Figure 3 that Jetty (the default JSP and servlets container) is listening on port 8080 for incoming HTTP connections, and on port 8443 for HTTPS (SSL secured) connections.

Figure 3
Figure 3: A typical Geronimo startup screen

The set of default services are described in the table below.

Service and port Description
RMI Naming service – port 1099 Registry to locate RMI objects, used internally by Geronimo or by client RMI applications.
Derby RDBMS – port 1527 Instance of the Derby RDBMS. Your application can use the Derby JDBC driver to access this Geronimo managed instance over the network.
OpenEJB – port 4201 Network requests for EJBs goes through this service.
Jetty – port 8080 Web applications running on Jetty are accessed through this port. Jetty can also service static pages, acting as a web server. The JSP and servlets can also act as a web service (i.e. through the use of the Axis servlets).
Jetty – port 9443 A secure socket connection to the same Jetty sub-container.
ActiveMQ – port 61616 The TCP port to access the ActiveMQ broker. JMS clients can use this port to access destinations (queues and topics).

The default set of services is sufficient to support most typical J2EE applications. The next section shows the deployment and test of such an application.

Deploying applications to Geronimo

J2EE applications are bundled in JAR files. You must create these files in standardised formats. Each JAR file contains the software components (for example – JSPs, servlets, EJBs) and required deployment descriptor XML files (for example – web.xml and/or ejb-jar.xml). The placement of these components and descriptors are well defined by the J2EE specification. Applications targeted for the web tier are bundled into Web Application aRchives (WARs – JAR files with the .war extension). Applications with web tier components plus EJBs are called enterprise applications, and are bundled in Enterprise Application aRchives (EARs – JAR files with the .ear extension). If you develop your application using an IDE, the IDE may provide assistance in creating the JAR files. This can often simplify the tedious work of creating the JAR files and deployment descriptor.

The table below summarises these popular archive formats.

Archive format Components included Deployment descriptors and other details
WAR – web application archive JSP, sevlets, filters, Java classes, JSP tags The web.xml deployment descriptor must be placed in the WEB-INF directory. The WEB-INF/lib subdirectory can contain private library JAR files. The WEB-INF/classes directory contains servlets, tag implementations, and other Java support classes.
JAR – EJB archives EJBs The ejb-jar.xml deployment descriptor must be placed in the META-INF directory. The EJB implementation classes are placed at the top level directory within these JAR files.
EAR – enterprise application archive WAR file(s) containing JSP servlets, etc; and EJB JAR file(s) containing EJBs This archive bundles web tier components (WAR) and EJBs (JAR) together for one-shot deployment. The application.xml deployment descriptor must be placed in the META-INF directory. The included WAR and EJB JAR files are placed at in the top level directory.

In addition to the above mentioned standard deployment descriptors for each type of archive, the J2EE specification also allows vendor-specific deployment plans (XML files) to be included. In practice, these deployment plans are almost always necessary to provide additional information to the server – telling it specifically how to deploy the application.

To run these bundled applications on the Geronimo server, you must first deploy them. Essentially, deployment involves copying the archive file into storage that is managed by Geronimo (called a configuration repository), and starting the application. This process is transparent to you. Deployment is performed using the Geronimo runtime deployer tool. As shown in Figure 4, the deployer tool deploys and starts the bundled application in the target Geronimo server with one single command.

Figure 4
Figure 4: The operation of the deployer tool

RAR files (shown in Figure 4) are resource archive bundles. They contain connector components compatible with the J2EE Connector Architecture (JCA 1.5) for connecting from the server to EIS systems. Connectors that are typically found in RAR files include JDBC connectors for external RDBMS and/or JMS connectors for external message queue brokers.

Deploying your first Geronimo application

The code download comes with complete source code for an enterprise application that includes JSP, servlets, and a stateless session bean. You can find a ready to deploy EAR file in the earapp/dist directory, called showdept.ear.

Copy the showdept.ear to your Geronimo installation directory, then use the following deployer command to deploy the application:

java -jar bin/deployer.jar
	-user system
	-password manager deploy
		showdept.ear
If everything goes well, you should see the message:
Deployed showdept
The default user and password is system/manager. You can add or change this by editing the var/security/user.properties file in your Geronimo installation.

Once deployed, applications will run on the Geronimo server until you explicitly stop or uninstall them. This means that you can reboot the machine and server, and your application will still be running within Geronimo. You do not have to re-deploy the application on every server restart.

The deployer tool can perform many other operations. You can use the deployer to see all the applications and system configurations that are currently deployed on the server. The command is:

java -jar bin/deployer.jar
	-user system
	-password manager list-modules
A typical output from this command is show in Figure 5.

Figure 5
Figure 5: Typical Geronimo output

Note that the showdept application is one of the modules listed. A module in this case refers either to a deployed application, or to a system configuration. The other modules listed are all system configuration that start the basic set of servers.

To access the showdept application, point your browser to:

http://localhost:8080/ShowDept/
	employees.cgi
This simple application has only one dynamically generated web page. As can be seen in Figure 6, the application shows a hypothetical list of employees at the VSJ office, with their names and departments displayed.

Figure 6
Figure 6: A dynamic page

If you need to stop the application, you can use the command.

java -jar bin/deployer.jar
	-user system
	-password manager stop showdept
To uninstall the application, perform an undeploy command:
java -jar
	bin/deployer.jar
	-user system
	-password manager
	undeploy showdept

Exploring the showdept application

The showdept application is a classic enterprise application in the sense that it contains JSP, servlets, and EJB components. Figure 7 illustrates how these components work together in showdept.

Figure 7
Figure 7: Geronimo components

In Figure 7, the AppController servlet serves as the controller in the MVC architecture. It forwards incoming requests, and supplies the presentation layer JSP with the required business data. In this case, AppController accesses the EmployeesBean stateless session EJB to obtain the data – a list of employee names. This data is attached as an attribute to the session and passed to showdept.jsp for display. showdept.jsp formats and displays the business data using the JSP Standard Tag Library (JSTL). You can find showdept.jsp in the earapp/jsp directory of the source code. This code is shown below:

<%@ taglib prefix=”c” uri=
”http://java.sun.com/jsp/jstl/core” %>
<%@ taglib prefix=”fmt” uri=
”http://java.sun.com/jsp/jstl/fmt” %>
<%@ page session=”true” %>
<html>
<head>
<title>VSJ department listing</title>
<link rel=stylesheet type=”text/css”
	href=”showdept.css”>
</head>
<body>
<table width=”600”>
	<tr>
	<td class=”mainHead” colspan=”3”>
	VSJ department listing
	</td>
	</tr>
	<c:forEach var=”employee”
		items=”${emps}”>
	<tr>
	<td width=”100”>
		${employee.firstName}</td>
	<td width=”100”>
		${employee.lastName}</td>
	<td align=”left”>
		${employee.dept}</td>
	</tr>
	</c:forEach>
</table>
</body>
</html>
The highlighted code above is the iterative JSTL code that prints the list of employees. Note that it depends on an attribute called emps. This emps attribute is attached to the session by AppController. You can find the code to AppController.java in the earapp/src directory of the code distribution. The code of AppController.java is shown below:
package uk.co.vsj.geronimo;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.servlet.*;
import javax.servlet.http.*;
import java.util.*;
import java.io.IOException;

public class AppController extends
	HttpServlet {
protected static final String
	HOME_PAGE = “/showdept.jsp”;
protected void doGet(
	HttpServletRequest request,
	HttpServletResponse response)
	throws ServletException,
		IOException {
		HttpSession session =
			request.getSession(true);
		ServletContext context =
			getServletContext();
		EmployeesLocal emp = null;
		try {
			Context ic =
				new InitialContext();
			Object o =
	ic.lookup(“java:comp/env/EmpEJB”);
			EmployeesHomeLocal ejbhome =
	(EmployeesHomeLocal) o;
			emp = ejbhome.create();
		} catch (Exception ex) {
			ex.printStackTrace();
		}
		session.setAttribute(“emps”,
			emp.getEmployees());
	context.getRequestDispatcher(
		HOME_PAGE).
		forward(request, response);
	}
	protected void doPost(
		HttpServletRequest request,
		HttpServletResponse response)
		throws ServletException,
			IOException {
			doGet(request, response);
		}
	}
The portion of code that is highlighted above performs the following work, in order:
  1. looks up the EmployeesBean session EJB via JNDI (named EmpEJB)
  2. creates an instance of the EJB and assign it to a variable called emp
  3. calls the getEmployees() method of the EJB, and attaches the resulting list to a session attribute called emps
  4. forwards the request to the showdept.jsp page
The code of the stateless session bean, EmployeesBean, is found in the earapp/ejb directory. The code to EmployeesBean.java is listed below.
package uk.co.vsj.geronimo;
import javax.ejb.SessionContext;
import javax.ejb.SessionBean;
import java.util.ArrayList;
public class EmployeesBean implements
	SessionBean {
	private SessionContext ctx;
	public void setSessionContext(
		SessionContext ctx) {
		this.ctx = ctx;
	}
	public void ejbCreate() {
	}
	public void ejbActivate() {
	}
	public void ejbPassivate() {
	}
	public void ejbRemove() {
	}
	public ArrayList getEmployees() {
		ArrayList values =
			new ArrayList();
		values.add(new Employee(
			“John”, “Myers”, “sales”));
		values.add(new Employee(
			“Sue”, “Grant”,”sales”));
		values.add(new Employee(
		“Ben”, “Wong”, “engineering”));
	return values;
	}
}
The highlighted code is where the list of employees is created. In a production scenario, this session bean will likely obtain the list from entity beans in the system – instead of generating it.

The EmployeesBean, being an EJB, also has an EJB home interface, called EmployeesHomeLocal, and an EJB interface called EmployeesLocal. The source code to both of these interfaces are located in the earapp/ejb directory.

These interfaces are associated with the EJB via the standard J2EE ejb-jar.xml deployment descriptor. Geronimo gets the information on EmployeesBean EJB from this deployment descriptor. The source of ejb-jar.xml is shown below, you can find it in the earapp/dd directory of the source download.

<?xml version=”1.0” encoding=”UTF-8”?>
<!DOCTYPE ejb-jar PUBLIC ‘-//Sun
Microsystems, Inc.//DTD Enterprise
JavaBeans 2.0//EN’
‘http://java.sun.com/dtd/ejb-
jar_2_0.dtd’>
<ejb-jar>
	<enterprise-beans>
		<session>
			<display-name>
			Stateless Session Bean Local
				Interfaces
			</display-name>
			<ejb-name>EmpEJB</ejb-name>
			<local-home>
uk.co.vsj.geronimo.EmployeesHomeLocal
			</local-home>
			<local>
	uk.co.vsj.geronimo.EmployeesLocal
			</local>
			<ejb-class>
	uk.co.vsj.geronimo.EmployeesBean
			</ejb-class>
			<session-type>
				Stateless</session-type>
			<transaction-type>
			Container</transaction-type>
		</session>
	</enterprise-beans>
</ejb-jar>
The highlighted code shows where the home, EJB interface, and implementation class are identified to Geronimo. Note that this EJB is referenced through local semantics. This is a standard feature of a J2EE 1.4 EJB container. It allows the application to access the bean via direct Java references within the same Java VM – resulting in high performance access.

The EJB is referenced from the AppController servlet. This means that the EJB reference must be configured with the servlet’s deployment descriptor. This is the standard web.xml file. You can find the source of web.xml in the earapp/dd directory. web.xml contains:

<?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_4.xsd” version=”2.4”>
	<description>
		VSJ Employee List Example -
		for Geronimo
	</description>
	<display-name>
		VSJ Employee List Example for Geronimo
	</display-name>
	<servlet>
		<servlet-name>
			ShowDept</servlet-name>
		<servlet-class>
	uk.co.vsj.geronimo.AppController
		</servlet-class>
	</servlet>
	<servlet-mapping>
		<servlet-name>
			ShowDept</servlet-name>
		<url-pattern>
			/employees.cgi</url-pattern>
	</servlet-mapping>
	<ejb-local-ref>
<ejb-ref-name>EmpEJB</ejb-ref-name>
		<ejb-ref-type>
			Session
		</ejb-ref-type>
		<local-home>
uk.co.vsj.geronimo.EmployeesHomeLocal
		</local-home>
		<local>
uk.co.vsj.geronimo.EmployeesLocal
		</local>
	</ejb-local-ref>
</web-app>
The highlighted code in web.xml above shows where the JNDI lookup name (EmpEJB) of the EJB is setup. Also, the home and EJB interface of the EmployeesBean is also specified. These interfaces can be used to identify the actual EJB that is referenced – as long as there is only one EJB that supports the two interfaces.

The complete source code of the showdept application is supplied in the code download. You can modify the source and recompile it at any time using Ant. The build.xml file contains the detailed Ant build script. You must set the geronimo.home property in this file to point to your own Geronimo installation for the build to work. In my case, it contains:

<property name=”geronimo.home”
value=”e:/gerbuilds/geronimo-1.0-M4”/>
To rebuild, simply change into the earapp directory and type:
ant
After a successful build, the showdept-ejbs.jar, showdept.war, and showdept.ear files will be in the earapp/dist subdirectory.

Applications running in Geronimo can be scaled up as user demand increases. This can be achieved via the addition of inexpensive networked PC hardware and software re-configuration of the application.

Scaling apps on Geronimo servers

Applications deployed on a Geronimo server can be scaled quite effectively to handle increasing application load.

In Figure 8, the server at the top of the figure runs all the components – both web tier and EJBs – within one instance of the Geronimo server.

Figure 8
Figure 8: A typical Geronimo server scaling example

To handle increasing incoming application requests, the hardware running the Geronimo server can be upgraded. An example may be to add processor in a dual or quad processor server. This form of increasing the request handling capacity of a server is called vertical scaling, and can often be effective up to certain hardware constraints.

To further scale a system, horizontal scaling can help. The bottom scenario separates the web tier components from the EJB components and runs them in separate Geronimo instances (potentially on different server machines). This involves separating an EAR file into its constituent WAR and EJB JARs, and re-deploying them on separate servers. This can be useful where vertical scaling is no longer possible, or hardware upgrades no longer cost-effective. Clustering support is an ongoing sub-project in Geronimo, and will soon provide even further horizontal scaling capabilities.

Conclusions

The open source Apache Geronimo server can be your one-stop-shop for J2EE 1.4 application hosting needs. Robust support for standard J2EE components such as JSP, servlets, EJBs, JMS, web services, etc. is accomplished through the integration of mature open source container technologies such as Tomcat, Jetty, ActiveMQ, Axis, and OpenEJB. The Geronimo server is easy to set up, and runs any standard J2EE applications. At long last, businesses with J2EE-sized application needs but without a J2EE-sized budget have something solid to turn to.


Sing Li is a consultant, trainer and freelance writer specialising in Java, Windows NT and distributed object technologies. Li’s most recent publication is Early Adopter JXTA: Peer-to-Peer Computing with Java from Wrox Press.

Recently IBM has taken a key interest in Geronimo. It acquired a company called Gluecode, which employed hard-core Geronimo developers. In addition, IBM has pledged to integrate Geronimo into its Websphere line of application servers, and has started to offer commercial support for this open source product on a major Linux platform. Meanwhile, IBM has started to add tooling support for Geronimo – in the form of integration with its open source Eclipse IDE.

You can activate Tomcat instead of Jetty for processing JSP and servlets components. However, the activation process is rather complex, and requires re-compilation from source code. The Geronimo team is addressing this. Geronimo will have a release binary that uses Tomcat instead of Jetty by M5. If you need to activate Tomcat with M4, see the detailed instructions.

You might also like...

Comments

About the author

Sing Li United States

Sing Li has been writing software, and writing about software for twenty plus years. His specialities include scalable distributed computing systems and peer-to-peer technologies. He now spends ...

Interested in writing for us? Find out more.

Contribute

Why not write for us? Or you could submit an event or a user group in your area. Alternatively just tell us what you think!

Our tools

We've got automatic conversion tools to convert C# to VB.NET, VB.NET to C#. Also you can compress javascript and compress css and generate sql connection strings.

“UNIX is basically a simple operating system, but you have to be a genius to understand the simplicity.” - Dennis Ritchie