Apache Geronimo is a free, open source Java EE application server from the Apache Software Foundation (ASF). The latest released version, 2.1.4, is Java EE 5 certified. In this chapter, we will quickly take you through:
The motivation behind the Geronimo project
Geronimo architecture
The constituent projects that it integrates
Downloading and running Geronimo
Building Geronimo from source code
Contributing to the Geronimo project
This should get you started with using the Geronimo application server right away, and give you a glimpse of what Geronimo has to offer.
Apache Geronimo started as an application server. The first release of Apache Geronimo, that is, version 1.0 was J2EE 1.4 certified. The latest version is backward compatible to the J2EE 1.4, 1.3, and 1.2 specifications. The rationale behind Apache Software Foundation creating this project was:
There was no open source J2EE server based on BSD license available in the market at the time Apache Geronimo was proposed. With BSD license, anyone could modify the source code and also include it in their derivative offerings without making the derivative open source.
There were many projects in the Apache Software Foundation that implemented parts of the J2EE specification. The rationale was to create a full application server that used these best-of-breed open source components internally and filled in the gaps that were missing.
There was still more room for innovation in the J2EE application server space.
Thus Apache Geronimo was born.
Apache Geronimo started as an application server. The first release of Apache Geronimo, that is, version 1.0 was J2EE 1.4 certified. The latest version is backward compatible to the J2EE 1.4, 1.3, and 1.2 specifications. The rationale behind Apache Software Foundation creating this project was:
There was no open source J2EE server based on BSD license available in the market at the time Apache Geronimo was proposed. With BSD license, anyone could modify the source code and also include it in their derivative offerings without making the derivative open source.
There were many projects in the Apache Software Foundation that implemented parts of the J2EE specification. The rationale was to create a full application server that used these best-of-breed open source components internally and filled in the gaps that were missing.
There was still more room for innovation in the J2EE application server space.
Thus Apache Geronimo was born.
As the aim was to integrate many existing Apache projects into Apache Geronimo, the server had a very modular architecture with a lightweight and compact kernel into which other services could be plugged in order to provide additional functionality. Other containers that implemented parts of the J2EE specifications could then be added on top of this, and they would be able to use the services that were available. The various components and services could be stopped when they were not required, to save on system resources. In newer versions, this was improved upon and you could install or uninstall plugins at runtime to add or remove functionality. The latest version even has the ability to generate custom-server assemblies from the Administration Console of the server.
Apache Geronimo leverages a lot of popular open source projects to provide Java EE 5 compliance. Some of the projects used are:
Apache Tomcat
Apache Tomcat is an open source JavaServer Pages(JSP) and Java Servlet container from the Apache Software Foundation. It is fast, lightweight, and very popular, and is used widely in the industry. It is considered as a benchmark for Servlet and JSP containers. Apache Tomcat is used by Apache Geronimo as its web container. It is thereby used to host the web applications that you deploy in Apache Geronimo. Apache Tomcat is hosted at http://tomcat.apache.org.
Apache OpenEJB
Enterprise JavaBeans (EJB) technology provides the server-side component architecture for Java Platform. EJB technology enables the rapid and simplified development of distributed, transactional, secure, and portable applications based on Java technology.
Apache OpenEJB is a free, open source EJB container. It is both embeddable and lightweight. The current version, OpenEJB 3.x, supports EJB 3.0 and is also backward compatible with previous EJB versions. It also has a few experimental EJB 3.1 features. Apache OpenEJB is used by Apache Geronimo as its EJB container. Therefore, all EJB applications that you deploy in Apache Geronimo will in turn be deployed into Apache OpenEJB by the deployment subsystem. Apache OpenEJB is a complete rewrite of OpenEJB 2.1, which was included in Apache Geronimo 1.x. Thus, it is more robust and has a higher order of performance than its predecessor. Apache OpenEJB can be made to work with different JPA providers. However, it provides Container Managed Persistence (CMP) of EJB 2.1 support, through a wrapper over OpenJPA. Apache OpenEJB is hosted at http://openejb.apache.org.
Apache Axis 1.x
Apache Axis is an open source web services engine from the Apache Software Foundation. This version of Apache Axis is used to provide support for JAX-RPC web services. Apache Axis is hosted at http://ws.apache.org/axis.
Apache Axis2
Apache Axis2 is a rewrite of the Apache Axis web services engine. Apache Axis2 is used to provide support for JAX-WS, SOAP 1.2, SAAJ, and all the other specifications of web services, which are required for Java EE 5 compliance. Apache Axis2 is hosted at http://ws.apache.org/axis2/.
Apache CXF
Apache CXF is an open source services framework. It is also available as the web services container in Geronimo. It can be used as an alternative to Apache Axis2. Apache CXF is hosted at http://cxf.apache.org.
Jetty from Mortbay
Jetty is a fast and lightweight open source web server and Servlet container. It is easily embeddable and, like Tomcat, is widely used. Jetty can also be used as the web container in Apache Geronimo, as an alternative to Tomcat. This project is hosted at http://www.mortbay.org/jetty and is distributed under the Apache License, Version 2.0.
Apache ActiveMQ
Apache ActiveMQ is a popular and powerful open source message broker. It is fast, lightweight, embeddable, and supports many cross language clients and protocols. It supports the JMS specification. It is used as a message broker in Apache Geronimo. Apache Geronimo 2.1.4 uses ActiveMQ 4.1.2. Apache ActiveMQ is hosted at http://activemq.apache.org.
Apache XBean
Apache XBean is a plugin-based server framework. It provides functionality to discover, download, and install server plugins from a remote repository. It also supports Inversion of Control(IoC), lifecycle and class loader management, JMX, and Spring Integration. Apache XBean is a subproject of the Apache Geronimo project, and is hosted at http://geronimo.apache.org/xbean/.
Apache Derby
Apache Derby is a free, open source, lightweight, and embeddable RDBMS, implemented entirely in Java. Derby is integrated in Apache Geronimo as the default database, and the Administration Console has built-in portlets for basic Apache Derby administration tasks. Apache Derby is a part of the Apache DB project, and is hosted at http://db.apache.org/derby.
Apache Scout
Apache Scout is an open source implementation of the Java API for XML Registries (JAXR). It provides a registry where web services can be registered by their providers, and users can look for the services they need in the registry. Apache Scout is hosted at http://ws.apache.org/scout/.
Apache OpenJPA
Apache OpenJPA is an open source Java Persistence API (JPA) container that can either be used as a standalone POJO persistence layer or integrated into any EJB 3.0 container. OpenJPA was donated by BEA to the Apache Software Foundation, and is based on BEA's Kodo JPA Engine. It is used as the default JPA provider for Apache Geronimo and Apache OpenEJB. The version used in Apache Geronimo 2.1.4 is OpenJPA 1.2. Apache OpenJPA is hosted at http://openjpa.apache.org/.
Apache log4j & SLF4J
Apache log4j is the logging framework that is used for logging in Apache Geronimo, and SLF4J is the logging adapter that is used so that the source is not tied down to any logging framework. Apache log4j is hosted at http://logging.apache.org/, and SLF4J is hosted at http://www.slf4j.org/
Apache Commons
The Commons is an Apache project focused on all aspects of reusable Java components. Some of the components are:
BeanUtils: Easy-to-use wrappers around the Java reflection and introspection APIsFileUpload: A file upload capability for servlets and web applicationsIO: Collection of I/O utilities, and so on
Apache Commons is hosted at http://commons.apache.org.
Apache GShell
Apache GShell is a framework for building rich command-line applications. GShell is used as a bootstrap launcher for Apache Geronimo. It provides a number of built-in commands, and many optional ones. GShell is extensible, and the version in Apache Geronimo has been extended with many Apache Geronimo specific commands. Apache GShell is a subproject of the Apache Geronimo project, and is hosted at http://cwiki.apache.org/GSHELL.
Apache Yoko
Apache Yoko is a robust and high-performance CORBA server written in Java that can run on any Java Virtual Machine (JVM). It provides the ORB and CORBA naming service that is used by Apache Geronimo. It is also used by Geronimo to expose EJBs as CORBA services. Apache Yoko is a subproject of the Apache Geronimo project, and is hosted at http://cwiki.apache.org/YOKO/.
TranQL
TranQL is an open source framework for building persistence engines. The TranQL project is hosted at the Codehaus. It's also a framework for building J2CA connectors. TranQL provides J2CA connector implementations that wrap drivers for several popular relational databases. The TranQL project is hosted at http://tranql.codehaus.org.
These open source projects are plugged into the Geronimo system via wrapper GBeans or as dependant libraries. You can configure Geronimo servers that contain all or a subset of these projects. Apache Geronimo also provides you with more choice when choosing the parts that will make up your application server than any other application server. For example, you can have a server with Apache Tomcat as the web container and Axis2 as the web services container, or you can have a server with Jetty and CXF. So one key differentiator at the time Apache Geronimo was released was that it was not monolithic like many other Java EE application servers. However, most application server vendors are now re-architecting their servers to also be modular and lightweight.
Apache Geronimo consists of an IoC kernel that provides dependency management, configuration management, lifecycle management, and repository services. The plumbing required by Java EE containers, namely, support for deployment, transactions, remoting, naming, work management, and security, is implemented on top of the kernel. On top of this are plugged in the various containers, such as Apache OpenEJB, Apache ActiveMQ, and so on, which provide parts of the Java EE functionality and together make Geronimo a Java EE application server.
GBeans are the basic building blocks of Geronimo. A GBean provides lifecycle callbacks and acts as a thin wrapper around the various containers and modules that are plugged into Geronimo. The kernel then manages these containers and modules via the GBeans that wrap them. A group of GBeans that wraps a particular module is called a configuration. Interestingly, a configuration itself is a GBean, thereby leading to the statement, "Everything in Geronimo is a GBean!!"
The Geronimo architecture is modular and extensible. The extensibility is achieved via plugins. Geronimo provides the ability for new functionality to be added as plugins. Plugins are actually configurations or groups of configurations, along with metadata about their dependencies. Plugins can be installed in Geronimo via the Administration Console or via the command-line tools. Geronimo has the ability to download and install plugins from a remote repository. One such remote repository is available at http://geronimoplugins.com/. Thus, the Geronimo kernel also provides plugin installation and management services. Each of the containers in Geronimo is actually installed as a plugin. This method of extending the features of Geronimo via plugins initially gave rise to a minimal version of the server called little Geronimo (Little-G) that consisted of the Geronimo kernel, the required plumbing, and the web container. Later, even more flexibility was provided and you could export servers containing only the components you needed, from the Administration Console. This provided a large amount of flexibility in the configurations. A set of predefined server profiles were also provided out of the box, for users to export.
Apache Geronimo can be downloaded from the project's web site at http://geronimo.apache.org. The Downloads section has the latest version as well as previous releases. The server is available for download in .zip and tar.gz formats.
Download the ZIP file and then extract it to a directory on your drive. Let us refer to this directory as <GERONIMO_HOME>. Open a command window and change directory to <GERONIMO_HOME>/bin. Set either the JAVA_HOME or the JRE_HOME environment variable to a directory where Sun Java 1.5 is installed, and type start-server, in Windows, or ./start-server, in Linux. This will start the Geronimo server in the same command window. The following screenshot shows the command-line console output from Geronimo server startup:
The console displays the port numbers on which the various services are running, a list of Started Application Modules, and the context-root for the running web applications.
You can use startup to start Geronimo in a new window. If you want to start GShell (a Java-based shell for Geronimo), then you need to use gsh. Invoking the GShell results in a new shell prompt in the format user@hostname:/>, for example, administrator@foo:/>.
GShell supports a large number of commands to perform a variety of operations in Geronimo. You can start or stop the server, install or uninstall applications, and even export a new server from the current installation. To get a list of commands that are supported by GShell, type help at the prompt.
To start the server from GShell, type geronimo/start-server at the GShell prompt. To stop the server, open another GShell prompt and enter geronimo/stop-server. You will be prompted to enter the username and password. Enter system for the Username and manager for the Password.
Note
If you encounter any port conflicts during startup, you will need to either shut down the other services that are using those ports or you will need to configure the Geronimo installation to use other ports. The steps for doing this are given in Appendix-B, Troubleshooting.
Geronimo has a powerful web-based Administration Console, consisting of portlets developed using Apache Pluto that can be used for various administrative tasks. The Administration Console provides a convenient and user friendly way to administer many aspects of the server. Once the Geronimo server has been started, the Administration Console can be accessed by using the URL http://localhost:8080/console. The default Username is system and the default Password is manager. The following figure shows the layout of the Administration Console.
The portlets are grouped into various portlet groups, such as, Server, Services, Applications, Security, and so on, according to the functions addressed by the portlets. The portlets can be broadly divided into the following two categories:
Portlets to monitor the server: Information portlet, Java System Info portlet, Monitoring portlet, Repository portlet, and DB Info portlet are some of the portlets that help monitor the server status.
Portlets to perform administrative operations: Web Server portlet, JMS Server portlet, Database Pools portlet, portlets under Applications group, and DB Manager portlet are some of the portlets that help in administering some aspect of the server.
In this section, we will briefly introduce some of the commonly-used portlets. See Chapter 10, Administration for more details on Administration Console.
The Information portlet is launched by clicking on the Information link under the Server portlet group in Console Navigation pane. This portlet displays information on the version number of the Geronimo server, the server Start Time, the server Up Time, the Name of the operating system, the JVM in which the server is running, and the current Server Memory Usage.
The Java System Info portlet is launched by clicking on the Java System Info link under the Server portlet group in Console Navigation. This portlet displays the system properties set in the JVM in which the server is running. For display purposes, the system properties are grouped into Java, Virtual Machine, Operating System, Sun, User, and Etc groups.
The Server Logs portlet is launched by clicking on the Server Logs link under the Server portlet group in Console Navigation. This portlet enables you to browse the server log messages, web access log messages, and Derby database log messages. The portlet provides the ability to filter the log messages based on various criteria, such as displaying log messages containing specified text, generated within a specific date range, and so on. The portlet also features a Log Manager, which allows the server log settings to be temporarily altered.
The Web Server portlet is launched by clicking on the Web Server link under the Server portlet group in Console Navigation. This portlet enables you to add new HTTP, HTTPS, and AJP ports or listeners to the web container, and perform Start, Stop, Restart, Edit, and Delete operations on existing listeners. In order to add a new HTTP port to the web container, click on Tomcat BIO HTTP Connector. On the next page, enter a uniqueName for the connector, change the default port number to a port number of your choice, and click on Save.
The JMS Server portlet is launched by clicking on the JMS Server link under the Server portlet group in Console Navigation. This portlet enables you to add new JMS listeners and perform Start, Stop, Edit, and Delete operations on existing JMS listeners.
The Repository portlet is launched by clicking on the Repository link under the Services portlet group in Console Navigation. This portlet displays a list of JAR files and configurations deployed on the server. The portlet also provides the ability to install a new archive into the server's repository.
The JMS Resources portlet is launched by clicking on the JMS Resources link under the Services portlet group in Console Navigation. This portlet enables you to create new JMS resources such as Connection Factory, Queue, and Topic.
The Database Pools portlet is launched by clicking on the Database Pools link under the Services portlet group in Console Navigation. This portlet enables you to Create a new database pool: Using the Geronimo database pool wizard and to perform Edit and Delete operations on existing database pools. You can also Run SQL commands against an existing data source.
The Deploy New portlet is launched by clicking on the Deploy New link under the Applications portlet group in Console Navigation. This portlet enables you to deploy a new application or a new service into the server. An archive or a Geronimo specific deployment plan, or both can be used to deploy new applications and services.
The Plan Creator portlet is launched by clicking on the Plan Creator link under the Applications portlet group in Console Navigation. This portlet enables creating a Geronimo specific deployment plan required to deploy an archive in a sequence of steps, and deploying the archive using the generated deployment plan.
The Plugins portlet is launched by clicking on the Plugins link under Applications portlet group in Console Navigation. This portlet provides the ability to install plugins onto a Geronimo server, export existing configurations as Geronimo plugins, and create a custom server assembly from configurations and plugins running in the server.
The Applications portlets lets you view the running status of the applications, perform operations like Stop, Start, Restart, and Uninstall applications. There are multiple portlets for this purpose, each of which displays a selected group of configurations running on the server. The portlets that fall into this category are:
Web App WARs portlet: Shows the web applications deployed on the server
System Modules portlet: Shows the services (such as ActiveMQ, Axis, and so on) deployed on the server
Application EARs portlet: Shows the enterprise applications deployed on the server
EJB JARs portlet: Shows the EJB applications deployed on the server
J2EE Connectors portlet: Shows the database pool and JMS resource configurations deployed on the server
App Clients portlet: Shows the enterprise application clients installed on the server
The Users and Groups portlet is launched by clicking on the Users and Groups link in the Security portlet group under Console Navigation. This portlet enables you to add new users, add new groups, change an existing user password, edit an existing group to change the user membership of the group, delete an existing user, and delete an existing group. Note that users belonging to the admin group have access to the Administration Console.
The DB Info portlet is launched by clicking on the DB Info link in the Embedded DB portlet group under Console Navigation. This portlet displays information on the embedded Derby database server.
The DB Manager portlet is launched by clicking on the DB Manager link in the Embedded DB portlet group under Console Navigation. This portlet enables an administrator to create new databases, delete an existing database, run SQL commands against an existing database, view database tables, and browse the contents of database tables.
You can download the source code of Geronimo and build the server from it. The Geronimo source code is maintained in a Subversion repository. The URL is https://svn.apache.org/repos/asf/geronimo/server. There are different tags for the different releases. For example https://svn.apache.org/repos/asf/geronimo/server/tags/2.1.4 corresponds to the 2.1.4 release. The branches are for making bug fixes to previous releases if required. The trunk is the latest codebase, where most of the new development is happening. You can check out and build any of these. We will now go through the procedure to download and check out the source code of version 2.1.4.
Go to the location on your disk where you want to check out the code and type the following command:
svn checkout https://svn.apache.org/repos/asf/geronimo/server/tags/2.1.4 server
Note
You need to install the Subversion client before you can actually checkout the code. The client is available at http://subversion.tigris.org/
Once the process has completed you will notice that a directory called server that contains the source is created. You will now need to download and install Apache Maven 2, which is required in order to build the server from the source code. You can download Maven 2 from http://maven.apache.org/download.html.
Note
You need to use Sun JDK 1.5.x and Apache Maven 2.0.9, to build Geronimo version 2.1.4 server from source code.
Once you finish installing Maven 2, you need to change your directory to the directory into which you checked out the source, and then run mvn install.
The build process will take 30 to 40 minutes and you will need to be connected to the Internet during the build. Once the build is successful (all the tests need to pass for the build to succeed), you can find the various server distributions in the assemblies directory. In case there is a build failure, due to test failures you can run the builds with the
-Dmaven.test.skip=true, -Dmaven.itest.skip=true
flags, so that test failures are ignored.
The assemblies directory contains the following subdirectories:
geronimo-boilerplate-minimalProvides boilerplate files for all of the Geronimo server assemblies
geronimo-frameworkA Geronimo server framework assembly
geronimo-jetty6-javaee5Java EE 5 certified Geronimo version with Jetty as the web container and CXF as the web services engine, and all the bells and whistles
geronimo-jetty6-minimalMinimal version of Geronimo with just the web container (Jetty) and the Geronimo framework
geronimo-tomcat6-javaee5Java EE 5 certified Geronimo version with Tomcat as the web container and Axis2 as the web services engine and all the bells and whistles
geronimo-tomcat6-minimalMinimal version of Geronimo with just the web container (Tomcat) and the Geronimo framework
Apache Geronimo is developed and distributed under the Apache License, Version 2.0, which is a derivative of the BSD License. This means that any individual or commercial entity can distribute Apache Geronimo for free. The big difference from GPL licensed software is that derivative works that are distributed need not be open source. This makes Geronimo attractive to corporations and software houses. Some corporations actually pay their employees to work full time on Geronimo. However, a lot of people contribute to Geronimo as a hobby or as a way to learn how to write scalable software.
Anyone can contribute new features, raise defects, contribute documentation, or contribute bug fixes to Geronimo. This is encouraged, as a more vibrant community will help to make a better product. The procedure to follow is to open an issue in the Geronimo issue tracker (JIRA) and attach a patch file. You can generate the patch file by invoking the svn diff subcommand. Once you attach a patch file, one of the committers (people who can make changes to the source code in the Geronimo subversion repository) will review your patch and if he or she feels it is valid, will commit it to the source tree in subversion repository.
Eclipse from the Eclipse Foundation is a popular open source IDE written in Java that supports a variety of languages, including Java. Support for Java EE 5 is provided by a set of Eclipse plugins called the Web Tools Platform or WTP. WTP provides extension points for application server vendors to extend WTP to integrate with their servers and provide deployment and debug functionality during server-side Java EE development. Apache Geronimo provides a WTP server adapter or an Eclipse plugin that runs on top of WTP and provides Java EE developers with features to develop, deploy, and debug Java EE applications on Apache Geronimo. The Geronimo Eclipse Plugin (GEP) can be downloaded from the subprojects site at http://geronimo.apache.org/development-tools.html. The source code for the Geronimo Eclipse Plugin is available from https://svn.apache.org/repos/asf/geronimo/devtools/eclipse-plugin/.
Apache Geronimo provides a set of sample Java EE 5 applications that exercise almost all aspects of the Java EE 5 specification. These samples range from the most trivial web applications such as the Inventory sample to reasonably complex enterprise applications like the Day Trader. The samples for different versions of Apache Geronimo can be obtained from the URL http://cwiki.apache.org/GMOxSAMPLES/.
The Day Trader sample is actually checked into the subversion tree for Apache Geronimo. Users can download it from the Subversion repository and build it. The Subversion (SVN) URL is https://svn.apache.org/repos/asf/geronimo/daytrader/.
The other samples are also available in SVN at https://svn.apache.org/repos/asf/geronimo/samples/.
In this chapter, we have provided an overview of Geronimo, various component projects in Geronimo, and we have briefly discussed the architecture of Geronimo. We have discussed how to download and run Geronimo, and given an introduction to the Administration Console. We have also provided instructions on how to build Geronimo from source code that has been checked out from the Geronimo Subversion repository.
