Geronimo Classloading

In Geronimo each plugin or module has an associated classloader. These classloaders differ from normal URL classloaders in that they have multiple parents and various ways to customize the visibility of classes in the classloader itself and its parents. Classloaders associated with plugins are the only classloaders in Geronimo. Classloaders are uniformly configured in xml through an environment element allowed at the start of all geronimo plans.

Specifying what is in a classloader

The contents of a classloader are specified through dependency elements in the xml environment element. All dependencies refer to artifacts in the geronimo repository, using the same format as dependencies in a maven 2 pom. These dependencies can be plain jars or other plugins. Plugins become parents of the classloader whereas jars become available directly in the classloader.

Customizing classloader behavior

There are a number of customizations available for classloaders.

Inverse-classloading

Normally when loading a class the parents are searched first. By including <inverse-classloading/> the classloader is configured to search itself first, then the parents. This feature is probably most familiar in web app classloaders but can be configured on any geronimo classloader.
This technique should be used with caution because it affects all classes and can cause conflicts when objects constructed in your module are passed to a parent for processing. It can be a valuable tool for problem determination and testing, but should be avoided for production systems. In production systems, use the <hidden-classes> element instead and specify only those classes that can be used without conflict.

non-overridable-classes.

If you have configured inverse-classloading, you can override that for specific classes or packages by including filters for those classes you want to be loaded from parent classloaders even if they are present in the current classloader.
This is important when you want your module to share a common instance of a framework library with other modules.

hidden-classes

Including a filter in a hidden-classes element prevents matching classes from being loaded from any parent classloader. This is used when the current module depends on a different version or when the class represents a framework that must be initialized independently from the same framework used by the parent.
This feature is a bit odd. In addition, all child classloaders will not be able to load the class from any parent.

private-classes (new in 2.2, and experimental)

Including a filter in private-classes prevents and child classloader from loading the class from this classloader. It is similar to hidden-classes but on the parent rather than the child.

Startup plugin classloaders

A few jars are needed to set up the geronimo kernel and repository and logging and cannot be loaded from the geronimo repository. These jars are configured in a manifest-classpath in the jar manifest of startup plugins such as j2ee-system and client-system. These jars are copied under simpler names in bin and locate the jars in the lib directory. The relationship between the bin and lib directories must not be changed.

Other comments

Plugins are combinations of both classes and services. Dependencies can be on either classes, services, or both. Normally dependencies are on both. If this is not desired, the import element can be used in a dependency. Lets suppose we have a plugin B with a dependency on plugin A.

import classes

Starting plugin B will load plugin A so its classloader is available but will not start plugin A so the services will not necessarily be started. This is used in deployer plugins so that the runtime classes are available but e.g. a web server is not running.

import services

Starting plugin B will load and start plugin A so the services from A are available. However the classes in plugin A will not be available to plugin B. (This is apt to work only if the services in A implement interfaces available to B).

import all (default)

Starting plugin B will load and start plugin A and the both the classes and services from A are available for plugin B.

Special Cases

Xerces, Xalan and other endorsed packages

Some functionality is included in the vm but is intended to be user-replaceable. This includes the xml and xsl libraries. Usually you can't just include the version of xerces or xalan you want to use in your application, instead you need to put it in <geronimo_home>/lib/endorsed. Unfortunately this means all of geronimo will be using the same version of these libraries. A typical symptom of this problem might look like this:

java.lang.ClassCastException: org.apache.xerces.parsers.XIncludeAwareParserConfiguration cannot be cast to org.apache.xerces.xni.parser.XMLParserConfiguration