Geronimo Architecture: Part 2

Class loader architecture

This section covers the class loader architecture for Apache Geronimo. The following image shows the class loader hierarchy for an application that is deployed in Apache Geronimo:

Apache Geronimo 2.1: Quick Reference

The BootStrap class loader of the JVM is followed by the Extensions class loader and then the System class loader. The j2ee-system class loader is the primary class loader of Apache Geronimo. After the j2ee-system class loader, there are multiple other layers of class loaders before reaching the application class loaders. Applications have an application class loader, which loads any required application-level libraries and EJB modules. However, the web application packaged in the EAR will have its own class loader. The Administration Console has a ClassLoader Viewer portlet that can be used to view the class loader hierarchy as well as the classes loaded by each class loader.

Modifying default class loading behavior

In certain situations, we will need to follow a class loading strategy that is different from the default one that is provided by Apache Geronimo. A common situation where we need this functionality is when a parent configuration uses a library that is also used by the child and the library used by the parent is a different version, which is incompatible with the child's version of the library. In this case, if we follow the default class loading behavior, then we will always get the classes loaded by the parent configuration and will never be able to reference the classes in the library present in the child configuration.

Apache Geronimo provides you with the ability to modify the default class loading behavior at the configuration level to handle such scenarios. This is done by providing certain elements in the deployment plan which, if present, will change the class loading behavior. These elements and the changes in class loading behavior that they represent, are explained as follows:

  • hidden-classes: This tag is used to hide classes that are loaded in parent class loaders, so that the child class loader loads its own copy. Similarly, we can use this tag to specify the resources that should be loaded from the configuration class loader. For example, consider the case where you have a module that needs to load its copy of log4j. The server also has its own copy used for logging that is loaded in the parent class loader. We can add the hidden-classes element in the deployment plan for that module so that it loads its own copy of log4j, and the server loaded version of log4j is hidden from it.
  • non-overridable-classes: This element specifies the list of classes that can be loaded only from the parent configurations of this configuration. In other words, the classes specified in this element cannot be loaded by the current configuration's class loader. The non-overridable-classes element is for preventing applications from loading their own copies of classes that should always be loaded from the parent class loaders, such as the Java EE API classes.
  • private-classes: The classes that are defined by this tag will not be visible to class loaders that are the children of the current class loader. These classes will be loaded either from the current class loader or from its parents. The same class loading behavior can be achieved by using the hidden-classes tag in all of the child class loaders.
  • inverse-classloading: If this element is specified, then the standard class loading strategy will be reversed for this module. This in effect means that a class is first looked up from the current class loader and then from its parent. Thus, the class loader hierarchy is inverted.
  • suppress-default-environment: This will suppress the environment that is created by the builder for this module or configuration. This is a rarely-used element and can have nasty side effects if it is used carelessly.

Important modules

In this section, we will list the important configurations in Apache Geronimo. We will group them according to the Apache or other open source projects that they wrap. Configurations that do not wrap any other open source project will be listed under the Geronimo section.

Apache ActiveMQ



Apache Axis



Apache Axis2




Apache CXF





Apache Derby


Apache Geronimo
































Apache Yoko



Apache Jasper






JSR 88





Apache MyFaces



Apache OpenEJB




Apache OpenJPA




Apache Tomcat6






Apache WADI





Apache XmlBeans


Apache Pluto




If you check the configurations, then you will see that most of the components that make up Geronimo have a deployer configuration and a main configuration. The deployer configuration contains the GBeans that will deploy modules onto that component. For example, the openejb-deployer contains GBeans that implement the functionality to deploy an EJB module onto Apache Geronimo. For accomplishing this, the EJB JAR file and its corresponding deployment plan are parsed by the deployer and then converted into a format that can be understood by the OpenEJB subsystem. This is then deployed on the OpenEJB container. The main configuration will usually contain the GBeans that configure the container and also manage its lifecycle.

Server directory structure

It is important for a user or an administrator to understand the directory structure of a Geronimo server installation. The directory structure of a v2.1.4 server is shown in the following screenshot:

Apache Geronimo 2.1: Quick Reference

Please note that the directory that we will be referring to as <GERONIMO_HOME> is the geronimo-tomcat6-javaee5-2.1.4 directory shown in the screenshot.

The following are some important directories that you should be familiar with:

  • The bin directory contains the command scripts and the JAR files required to start the server, stop the server, invoke the deployer, and start the GShell.
  • The etc directory contains the configuration files for GShell.
  • The schema directory contains Geronimo schemas.
  • The var/config directory contains Geronimo configurations files. A Geronimo administrator or user can find most of the configuration information about the server here.
  • The var/derby directory contains the database files for the embedded Derby database server.
  • The var/log directory contains logging configuration and logfiles.
  • The var/security directory contains user credential and grouping files.
  • The var/security/keystores directory contains the cryptographic keystore files used for server SSL configuration.

The following are some important configuration files under the Geronimo directory structure:

  • config.xml: This file is located under the &ltGERONIMO_HOME>/var/config directory. This file preserves the information regarding GBean attributes and references that were overridden from the default values used at deployment time.
  • This file is located under the &ltGERONIMO_HOME>/var/config directory. The property values specified in this file are used in expressions in config.xml. The property values in this file can be overridden by using a system property or environment variable with a property name that is prefixed with org.apache.geronimo.config.substitution.
  • This file is located under the &ltGERONIMO_HOME>/var/config directory. This file is used to substitute one module or configuration ID for another module or configuration ID. The entries in this file are of the form oldArtifactId=newArtifactId, for example default/mylib//jar=default/mylib/2.0/jar. Note that the version number in the old artifact ID may be omitted, but the version number in the new artifact ID must be specified.
  • This file is located under the &ltGERONIMO_HOME>/var/config directory. This file is used for artifact aliasing with application clients.
  • This file is located under the &ltGERONIMO_HOME>/var/log directory. This file contains the logging configuration for the server.
  • This file is located under the &ltGERONIMO_HOME>/var/log directory. This file contains the logging configuration for the deployer.
  • This file is located under the &ltGERONIMO_HOME>/var/log directory. This file contains the logging configuration for application clients.
  • This file is located under the &ltGERONIMO_HOME>/var/security directory. This file contains the authentication credentials for the server.
  • This file is located under the &ltGERONIMO_HOME>/var/security directory. This file contains the grouping information for the users defined in

Among the directories that contain sensitive information, such as user passwords, are var/security, var/derby, and var/config. These directories should be protected using operating system provided directory and file security.

Deployment architecture

In this section, we discuss some of the important aspects of deployment of artifacts on a Geronimo server.


The deployer aggregates all instances of the ConfigurationBuilder available on the server and invokes the appropriate ConfigurationBuilder to deploy an archive, or a Geronimo-specific deployment plan XML file, or both. The deployer can be used through the web-based Administration Console, command-line deploy tool, hot-deployer, or GShell. Note that Administration Console, command line deploy tool, and GShell provide the option to specify an archive and a plan, whereas hot-deployer requires that the plan be packaged inside the archive.

Installed modules, applications, and services configurations can be uninstalled using the command-line deploy tool or GShell, and specifying the configuration ID. Configurations can also be uninstalled by clicking on the uninstall link in the Administration Console from the appropriate Applications portlets page.


Geronimo uses the Maven 2 type artifact repositories for library files, resources, and deployed configurations. The root of this repository is the directory &ltGERONIMO_HOME>/repository. This repository contains all of the server runtime configurations. An artifact with ID <groupId>/<artifactId>/<version>/<type> is located under the directory <GERONIMO_HOME>/repository/&ltgroupId>/&ltartifactId>/&ltversion> with the filename <artifactId&gt-&ltversion&gt.&lttype&gt. For example, the log4j JAR file that has an artifact ID of log4j/log4j/1.2.14/jar is located in the &ltGERONIMO_HOME>/repository/log4j/log4j/1.2.14 directory under the filename log4j-1.2.14.jar. When the groupId contains a dot (period), it results in a subdirectory rather than a directory with a dot in the directory name. For example, the RAR file corresponding to org.tranql/tranql-connector-ra/1.4/rar is located under the &ltGERONIMO_HOME>/repository/org/tranql/tranql-connectorra/1.4 directory rather than &ltGERONIMO_HOME>/repository/org.tranql/tranqlconnector-ra/1.4.

Configuration builder

A configuration builder creates a runtime configuration containing a class loader definition and GBeans that represent the function to be provided by deploying an application archive or a service plan in Geronimo. The archive or plan is translated into a set of GBeans. The definition of the GBeans is already available on the server or provided in the archive that is being deployed. The configuration builders deployed in the server are aggregated by the Deployer to provide a single interface for deploying all kinds of supported archives and/or plans. EARConfigBuilder and ServiceConfigBuilder are two configuration builders that are included in a Geronimo server by default.

A configuration builder implements the org.apache.geronimo.deployment. ConfigurationBuilder interface shown in the following listing:

public interface ConfigurationBuilder {
static final String CONFIG_BUILDER = "ConfigBuilder";
Object getDeploymentPlan(File planFile, JarFile module,
ModuleIDBuilder idBuilder)
throws DeploymentException;
Artifact getConfigurationID(Object plan, JarFile module,
ModuleIDBuilder idBuilder)
throws IOException, DeploymentException;
DeploymentContext buildConfiguration(
boolean inPlaceDeployment, //Boolean specifying whether to deploy in
Artifact configId,// the configuration id
Object plan, // the deployment plan
JarFile module, // the archive to deploy
Collection configurationStores, // the list of config stores
ArtifactResolver artifactResolver,
ConfigurationStore targetConfigurationStore // target store
) throws IOException, DeploymentException;

During the deployment, the getDeploymentPlan() method of each ConfigurationBuilder is invoked with the archive and/or plan files received for deployment. The configuration builder examines the provided archive and plan files, and returns the plan if that configuration builder can handle the deployment. The first configuration builder to return a non-null plan is chosen as the candidate to deploy the archive and/or plan. The candidate configuration builder's getConfigurationID() method determines the ID of the configuration under which the deployment will happen. Note that any fields in the configuration ID that are not determined by the configuration builder will be set to the default values by the deployer. The configuration ID will determine the directory under the repository into which the configuration will be deployed. The configuration builder's buildConfiguration() performs the moving of unpacked configuration directories to the repository and creates the necessary GBeans to complete the deployment.

Configuration builders use instances of ModuleBuilder and NamingBuilder to handle the individual modules in the deployment process. Any new ConfigurationBuilder GBeans that are started in the server at runtime get dynamically added to the deployer and are immediately available for use.

Module builder

Geronimo's EARConfigBuilder uses instances of ModuleBuilder to process individual web, EJB, connector, and application client modules in the deployment process. A ModuleBuilder processes the configuration and creates GBeans corresponding to a module that ModuleBuilder is capable of processing. Some instances of the ModuleBuilder that are available in Geronimo are given as follows:

  • EjbModuleBuilder
  • TomcatModuleBuilder
  • JettyModuleBuilder
  • ConnectorModuleBuilder
  • AppClientModuleBuilder

A ModuleBuilder GBean implements the interface org.apache.geronimo.j2ee.deployment.ModuleBuilder. The interface definition is as follows:

public interface ModuleBuilder {
Module createModule(File plan, JarFile moduleFile,
Naming naming, ModuleIDBuilder idBuilder)
throws DeploymentException;
Module createModule(Object plan, JarFile moduleFile,
String targetPath, URL specDDUrl,
Environment environment,
Object moduleContextInfo,
AbstractName earName, Naming naming,
ModuleIDBuilder idBuilder)
throws DeploymentException;
void installModule(JarFile earFile, EARContext earContext,
Module module,
Collection configurationStores,
ConfigurationStore targetConfigurationStore,
Collection repository)
throws DeploymentException;
void initContext(EARContext earContext, Module module,
ClassLoader cl) throws DeploymentException;
void addGBeans(EARContext earContext, Module module,
ClassLoader cl, Collection repository)
throws DeploymentException;
String getSchemaNamespace();

The createModule() method processes the individual Java EE module—that is, either a part of an EAR or being deployed as a standalone module, creates the artifacts that need to be installed, and also creates additional dependencies that need to be added to the configuration.

The installModule() method handles the copying of artifacts to the repository.

The initContext() method handles the initialization of the application context.

The addGBeans() method handles the adding of any GBeans to the module's configuration.

Module builder extension

A ModuleBuilderExtension to a ModuleBuilder provides additional processing on the module over and above those provided by the ModuleBuilder. A ModuleBuilderExtension implements the interface org.apache.geronimo.j2ee.deployment.ModuleBuilderExtension. This interface definition is given in the following listing:

public interface ModuleBuilderExtension {
void createModule(Module module, Object plan,
JarFile moduleFile,
String targetPath, URL specDDUrl,
Environment environment,
Object moduleContextInfo,
AbstractName earName,
Naming naming,
ModuleIDBuilder idBuilder)
throws DeploymentException;
void installModule(JarFile earFile, EARContext earContext,
Module module,
Collection configurationStores,
ConfigurationStore targetConfigurationStore,
Collection repository)
throws DeploymentException;
void initContext(EARContext earContext, Module module,
ClassLoader cl) throws DeploymentException;
void addGBeans(EARContext earContext, Module module,
ClassLoader cl, Collection repository)
throws DeploymentException;

Each ModuleBuilder can be configured with zero or more instances of ModuleBuilderExtension. During each of the method invocations in ModuleBuilder, once the processing by the ModuleBuilder is completed, the method invokes the corresponding method on each of the configured instances of ModuleBuilderExtension so that the extension completes additional processing. For example, MyFacesModuleBuilderExtension for TomcatModuleBuilder takes care of processing MyFaces configuration files and adding necessary additional dependencies and GBeans to the configuration.

Naming builder

Instances of ModuleBuilder and ModuleBuilderExtension use instances of NamingBuilder to process the Geronimo naming of related XML elements, for example, EJB references, GBean references, and so on, in the deployment plans. Some instances of the NamingBuilder are:

  • EjbRefBuilder
  • ResourceRefBuilder
  • CorbaRefBuilder
  • TSSLinkBuilder
  • EnvironmentEntryBuilder
  • GBeanRefBuilder

The instances of NamingBuilder to be used by instances of ModuleBuilder and ModuleBuilderExtension are configured in a NamingBuilderCollectionGBean

Hot deployment

Geronimo provides hot deployment by means of DirectoryHotDeployer, whereby the files copied to the &ltGERONIMO_HOME>/deploy directory are automatically deployed to the Geronimo server.

Deployment watcher

A DeploymentWatcher enables the receipt of notifications about configurations being deployed to and removed from the server. A DeploymentWatcher implements the interface org.apache.geronimo.kernel.DeploymentWatcher. The interface definition is given in the following listing:

public interface DeploymentWatcher {
void deployed(Artifact id);
void undeployed(Artifact id);

For example, the DirectoryHotDeployer, which is a DeploymentWatcher, handles the removal of files from the hot-deploy directory when the configuration being removed is originally deployed using the hot deployer.


A Geronimo plugin is a predeployed configuration that contains a class loader description, GBeans, and other resources. An example is the Quartz plugin that, upon installation, provides sophisticated scheduling functionality to applications being deployed on Apache Geronimo. A plugin defines prerequisite configurations as well as dependencies that must be downloaded. As it is already processed by the deployer, a plugin JAR is directly extracted into the server's repository without going through a deployment step where the configuration is created. A plugin installation differs from a normal deployment in the way that any non-prerequisite dependencies for the plugin will be downloaded during installation. The prerequisite configurations must have already been deployed in the server for the plugin to be installed. Note that in case of a regular deployment, all of the dependencies must already exist in the repository. Plugins can be installed by using the command-line deploy tool, the Administration Console, or the GShell.

Plugin catalog and plugin repository

A Plugin archive file contains a metadata file geronimo-plugin.xml under the META-INF directory. This geronimo-plugin.xml file contains descriptive information about the plugin, such as the plugin category, URL for a site that contains more information on the plugin, content to be added to config.xml for customization of GBeans, property values to be added to, artifact aliases to be added to, a description of the content to be unpacked to the server directory, and so on. The information from multiple plugins is collected into a plugin catalog called geronimo-plugins.xml. A maven repository containing plugins and a plugin catalog is referred to as a plugin repository.

Custom server assemblies

Starting from v2.1, a Geronimo server is completely assembled out of plugins. This architecture provides the ability to assemble a server containing only selected configurations according to a user's interest, and the necessary dependencies. This provides the users with the ability to start with a full Java EE server, deploy the user's applications, and then extract a server with the minimum footprint required to run the user's applications. Assembling a server in this manner can be done using the Plugins portlet in the Administration Console or by using the assemble-server GShell command. Note that the org.apache.geronimo.assemblies/geronimoboilerplate-minimal/2.1.4/jar configuration must be included in order to have a working server. Another way to create a custom server assembly is to use the car-maven plugin and build the server using Maven to include geronimoboilerplate-minimal, along with your plugin(s) that need to be part of the server.

Extensible Administration Console

The flexible server assemblies require that the Administration Console is also flexible, in order to provide the administration functionality for the newly added components as plugins to be made available from a single place. New functions can be added to the Administration Console by installing Administration Console Extensions. This provides the plugin developers with the capability to package administration components along with the functional components of their plugin.


We conclude this article after having gone through a fairly detailed overview of the architecture of Apache Geronimo, as well as the base pattern behind the Geronimo kernel—that is, dependency injection. We have covered GBeans, configurations, dependencies, and the repository. We then had a look at the high-level architecture of Apache Geronimo. We covered the functionality that the Apache Geronimo kernel exposes and had a look at the class loader hierarchy in Apache Geronimo. We listed the important system-level modules and explained the difference between normal and deployer modules. Finally, we discussed the deployment architecture and plugins. This brings us to the end of the article on the Apache Geronimo architecture. The authors hope that you now have a fairly detailed understanding of the Kernel and that you will be able to understand the Apache Geronimo source code better with this in mind.

If you have read this article you may be interested to view :

[ 1 | 2 ]

You've been reading an excerpt of:

Apache Geronimo 2.1: Quick Reference

Explore Title