Administering plugins

Creating a plugin

• You can create a plugin as part of a maven build by using the car-maven-plugin.
• You can create a plugin "virtually" by installing a deployed application from a running Geronimo server acting as a plugin repository.
• You can create a plugin by using the Geronimo administration console to create or edit the plugin metadata.

By far the easiest way to build a Geronimo plugin is with maven using the car-maven-plugin. Any such module includes a geronimo-plugin.xml descriptor with at least minimal information. When possible, this information, such as the description and license imformation, is taken from the pom file itself. Normally, you will build the dependency list from the modules dependencies that are constructed from the maven dependencies plus whatever additional dependencies the deployer determine that 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 the following command:

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 administration console also allows limited editing of the geronimo-plugin.xml files, but editing the information about how the plugin fits into the server is not yet supported.

Installing a plugin

If the appropriate administration console plugin is installed (and your Geronimo server includes Web application support), you can install plugins from a plugin repository. After selecting the Plugins page from the navigation menu, select the plugin repository that you want, such as your local maven repository if you have been building your own plugins. Next, you will see a list of available plugins from the repository. Select multiple plugins using the check boxes or a single plugin as a link, and on the next page you will see more information about the plugins. On your approval the plugins will be downloaded and installed.

Alternatively you can use GShell to install plugins using the deploy/install-plugin 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 as followed:

You can install a plugin into an existing server in different ways:

• GShell deploy/install-plugin command
• Geronimo administrative console
• Using maven and the geronimo-maven-plugin

You can also install a plugin into a new server assembly by using the car-maven-plugin.
Note that in all cases the dependency system assure that if you install a plugin, everything that is needed to run the plugin will also be installed. For instance, if you install a Java EE application plugin, such as one of the samples, into the framework server, openejb, openjpa, the transaction manager and connector framework, and the appropriate Web container will also be installed as dependencies.

Updating a plugin

At times, you might need to upgrade a plugin or jar version without rereleasing all the artifacts that depend on it. Here are some methods to upgrade jar versions.

Simple jar upgrade

If you want to install the upgraded jar as part of a plugin installation, see the following #Upgrading a jar while releasing a plugin section. Otherwise, use the following steps to upgrade the jar file:

1. If the server is running, stop the server.
2. Copy the new jar into the appropriate directory in your geronimo server's repository. For instance: mkdir -p repository/org/foo/myjar/1.1/ cp ~/newFooJar/myjar-1.1.jar repository/org/foo/myjar/1.1/ Alternatively, you can use the Services->Repository portlet on the administration console 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) to configure the server to substitute the version for any old version dependency . For instance, to replace myjar-1.0.jar with myjar-1.1.jar, add the following line:

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 the easiest way to specify in the car-maven-config configuration in the pom.xml, prior to building the plugin.