Starting with Geronimo 2.1 the servers are assembled entirely out of plugins.

• Most plugins are Geronimo modules, describing a classloader and services and possibly containing classes and resources.
• Plugins also contain descriptive information and include additional instructions on how the plugin fits into a server.
• Information about multiple plugins can be collected into a plugin catalog, often located in a maven repository
• A plugin repository is basically a plugin catalog together with a maven-structured repository containing plugins.
• Plugins can be installed from a plugin repository into an existing geronimo server using gshell commands or the admin console.
• Plugin metadata for an existing plugin in a geronimo server can be edited (to some extent) in the admin console.
• Maven can be used to assemble a new server out of plugins in a maven repository (not requiring a plugin catalog)
• A new server containing a specified set of plugins can be extracted from an existing server using a gshell command or the admin console.
• The dependency system assures that the resulting server has all needed plugins to operate.

This document is organized in the following sections:

Plugin basics

A Geronimo plugin is a jar-structured file that contains a META-INF/geronimo-plugin.xml descriptor following this schema:

Most plugins are Geronimo modules which means they include a classloader description, service configurations ("gbeans"), and possibly classes and resources. For instance, if you deploy a javaee application on geronimo, it turns into a geronimo module containing the description of the app's classloader, gbean configurations for the javaee components (web apps, ejbs, etc), and the classes and resources from your application. The additional information in the Geronimo plugin descriptor includes:

• Category (descriptive)
• Description
• License
• Dependencies: these will be automatically downloaded and installed when the plugin is installed. These are usually the same as the dependencies in the module classloader description.
• Prerequisites: These must be present before the plugin can be installed. This can be used to force the user to install an incompatibly licensed jar or to configure a modules such as a database pool before installing a dependent plugin.
• Obsoletes: These dependencies will be uninstalled before installing a plugin.
• Additional information about how the plugin fits into the server.

Additional information

• Content to be installed in a config.xml file to allow additional customization of gbeans, typically through properties.
• Default property values to be installed in a config-substitutions.properties file.
• Artifact aliases allowing one plugin or other artifact to replace another.
• Description of plugin content to be unpacked into the server. Plugins that are not modules typically exist only to install such content.

Where does this additional configuration information go?

A geronimo installation typically can run multiple jvms for different purposes. For instance, there's the main JavaEE server, a command line deploy tool, and a JavaEE application client container. Each of these requires configuration information from different files. The set of such information sufficient to configure such a jvm is collected together in a "server instance". In a geronimo server, these are represented by gbeans in the plugin module. When assembling a server using maven these are represented with xml in the maven pom. In any case, these have names, and for the plugin metadata specific to a server instance, you specify which instance you intend using the server attribute. This defaults to "default", the JavaEE server.

Building a plugin.

By far the easiest way to build a Geronimo plugin is with maven using the car-maven-plugin to build a module. Any such module will include a geronimo-plugin.xml descriptor with at least minimal information. When possible, such as the description and license, this information is taken from the pom itself. Normally you will build the dependency list from the modules dependencies which are constructed from the maven dependencies plus whatever additional dependencies the deployers determine are needed. For instance an ejb application will have the openejb plugin added as a dependency by the openejb deployer. If necessary you can specify the dependencies for both the module and plugin descriptor explicitly in the car-maven-plugin configuration.

Here's an example of a car-maven-plugin configuration using maven dependencies and configuring most of the additional information possible:

As you use maven to build plugins, a geronimo-plugins.xml plugin catalog is automatically maintained in your local maven repository. You can force this to be rebuilt by running

This might be necessary if you prune your maven repository and remove plugins listed in the catalog.

Alternatively, you can construct the geronimo-plugin.xml file by hand and include it in a deployed module in a geronimo server.

The admin console also allows limited editing of geronimo-plugin.xml files but editing the information about how the plugin fits into the server is not yet supported.

Installing plugins

If the appropriate admin console plugin is installed (and your geronimo server includes web app support) you can install plugins from a plugin repository. After selecting the "plugins" page from the navigation menu select the plugin repository you want, such as your local maven repository if you have been building your own plugins. Next you see a list of available plugins from the repository. Select multiple plugins using the checkboxes or a single plugin as a link, and on the next page you will see more information on the plugins. On your approval the plugins will be downloaded and installed.

Alternatively you can use gshell to install plugins using the deploy/list-plugins command. This can be run with a command line or interactively. Interactively you can select the plugin repository to use (if more than one is known), and then select the plugins to install. Again, they will be downloaded and installed. An example of command line usage will be seen in later when we discuss assembling a server.

Extracting a server from an existing server.

Just as with installing plugins, this can be done from the admin console or from gshell. In the admin console you specify the groupId and artifactId of the server you want, the version, and the archive type and then select the plugins you want installed. The server will be assembled in var/temp.

Similarly you can use the gshell deploy/assemble-server command specifying the same information on the command line or interactively.

TODO: The groupId is not currently used but the intention is to copy the assembled server into an appropriate maven repository.

Here's an example of a gshell script to install the roller plugin into the framework assembly and extract a server that only supports roller (and does not include the admin console or any deployment capabilities)

TODO: use something like this: snippet:url=geronimo/plugins/roller/trunk/roller-jetty-commands

TODO: get gshell to accept line continuations as in the following (these DO NOT WORK IN REAL LIFE):

Assembling a server using maven.

The easiest way to assemble a server is to use maven and the car-maven-plugin. The dependencies from your pom will be installed in your server, and if they are plugins they will be installed as modules with all dependencies and stuff unpacked and metadata installed into the correct files. Here's a simple example assembling a server that supports Roller and includes the basic admin console.

Upgrading jars and plugins to a new version

At times, you may need to upgrade a plugin or jar version, for instance if a new version of a dependency is released but you cannot rerelease all the artifacts that depend on it. Here are some methods to upgrade jar versions.

Simple jar upgrade

If the jar is to be installed as part of a plugin installation, see the section below. Otherwise, follow these steps. First, if the server is running, stop the server. Second, copy the new jar into the appropriate directory in your geronimo server's repository. For instance:

Alternatively, the admin console portlet Services->Repository can be used to add artifacts to the server's repository.

Finally, after the new jar is installed in the server's repository, add a line to var/config/artifact_aliases.properties (or the equivalent file, if the server is using a non-standard alias file). For instance, to replace myjar-1.0.jar with myjar-1.1.jar:

With this configuration, the server will substitute myjar-1.1.jar for any myjar-1.0.jar dependency.

Upgrading a jar while releasing a plugin

If the jar is installed as part of a plugin installation, you can include configuration upgrade information in the geronimo-plugin.xml. During plugin installation, the upgraded jar will be automatically installed. This is easiest to specify in the car-maven-config configuration in the pom.xml, prior to building the plugin.