...

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

...

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:

...

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.

...

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):

...

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.

...

In order to get a working server you must include the geronimo-boilerplate-minimal plugin which includes several files used to start the server

...

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,

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.

{snippet:url=geronimo/plugins/roller/trunk/geronimo-jetty-roller/pom.xml|lang=xml}

Upgrading jars and plugins to a new version

Often 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 versions.

Upgrading a jar without releasing any plugins

If no plugins will be (re)-released using the new dependency, you have to do some work by hand. First copy the new jar into the appropriate place in your geronimo server's repository. Then add a line to var/config/artifact_aliases.properties (or the equivalent file for , if the server using the jar) like this, for 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 you are releasing the jar is installed as part of a plugin installation, you can including include configuration upgrade information in the geronimo-plugin.xml to automatically install the jar upgrade entry when the plugin is . 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.

...