Converting applications into Geronimo plugins using GEP

In this section we discuss how to use the Geronimo Eclipse Plugin to convert Applications into Geronimo Plugins and install them to the server.

We are using Apache Geronimo v2.2 for this tutorial.

We have used an existing tutorial from tutorial section. See Stateless Session Bean for application development and deployment. Once done see the illustration in this tutorial to export and import JEE artifacts using the Geronimo Eclipse Plugin.

Creating Geronimo Plugins

In order to convert applications into Geronimo plugins, the Geronimo Server must be installed and started.

Double clicking the Geronimo server will display the Server Editor in the main window. Items for working with the server can be found on the Plugin page. Clicking on the Convert Apps to Plugins button will show the Plugin Manager wizard that is shown below.

Enter or create a directory and select the create Geronimo plugin radio button. The directory is a temporary place to save the application and you will have a chance to make any manual updates if necessary.

The next page of the dialog contains a drop-down list of all the objects that can be converted into Geronimo plugins. Many of the objects in this list are already plugins that are used by the Geronimo server. For example, select the console.dbpool/jdbcuserds/1.0/rar from the list.

Selecting your application objects (one at a time) and clicking Next will bring up pages that will allow you to change the geronimo-plugin.xml before saving. All fields on the next two pages are data that will be saved with the plugin and will help with installation.

Name
A human-readable name that will be displayed for this plugin.

id
The globally unique ID for this plugin. This is determined from the installation in the server you're exporting. This defines the version number for the plugin, so make sure it's correct.

Category
The category this plugin falls into. Plugins in the same category will be listed together. If this plugin is intended to be listed on geronimoplugins.com then you should use one of the category names there if any of them fit. Otherwise, you can select this freely, or according to the categories acceptable to the repository where you plan to post this.

Description
A description of this plugin. You should use plain text only, with blank lines to separate paragraphs.

Plugin URL
A URL to get more information about the plugin (for example, the plugin home page).

Author
The author of the plug, which may be a person, company, open source project, etc.

Geronimo Versions
An optional list of Geronimo versions supported by this plugin. If no values are listed, the plugin can be installed in any version of Geronimo. Otherwise, you can install this plugin in one acceptable Geronimo version.

JVM Versions
An optional list of JVM version prefixes supported by this plugin. If no values are listed, the plugin can be installed in Geronimo running in any version of the JVM. Otherwise, you can install this plugin in one acceptable JVM version.

Dependencies
A list of JARs or other module IDs that this plugin depends on. These will be downloaded automatically when this plugin is installed. Normally you shouldn't change this list. However, you can move entries from the dependency list to the prerequisite list if the user must install the dependency manually before installing the plugin (for example, for a database pool where a plugin wouldn't know what server to connect to). Each entry in this list should use the Unique ID format like is used for this plugin above. You may remove the version number if you'd like to work with any version of the dependency, though that may be risky. Each value should be on a separate line.

Obsoletes
A list of module IDs that this plugin replaces. Those plugins or modules will be removed when this one is installed. That may include previous versions of this plugin if you want installing it to "upgrade" rather than just offering an additional alternative. This should be a list with one module ID per line.

The next page has 2 tables. You can update the data in both the License table and Prerequisite table using the Add, Edit, and Remove buttons.

Licenses
The name of the license that this plugin is covered by. Ideally, it would be prefixed by the class of license, like "BSD – (name)" or "GPL – (name)". Specify whether the license is an OSI-approved open source license. See http://www.opensource.org/licenses/index.php for more information about open source licenses.

Prerequisites
The module IDs of prerequisites for this plugin. These are modules that must be present in the server before the plugin can be installed. They may be something like a specific web container for a web application (geronimo/jetty/1.0/car) or something like a database pool or security realm that the user must install because the plugin author can't create a value that will be valid in the destination server. You may want to leave out as many segments of the module ID as possible in order to accommodate more users.

(e.g. */mypool/*/* rather than myapp/mypool/1.2/car)

Clicking Next on this page saves the plugin and the geronimo-plugin.xml file and returns the user back to the first page.

For saving multiple projects or applications, repeat the above steps. For example, do the same for ApplicationClient and StatelessSessionEJB, selecting them from the drop-down list.

The above process creates an appropriate directory structure in the directory specified by the Local Plugin Repository field of the first page of the wizard. geronimo-plugin.xml files have been created for each plugin and the top directory includes a geronimo-plugins.xml that keeps track of all the plugins that have been created. The values in these files came from data from the last two pages in the Plugin Manager.

If you need to update the geronimo-plugin.xml file after saving, you can edit this file manually. When it is installed in the next step, the updates will be saved.

Installing Geronimo Plugins

If you haven't done so already, remove the projects from the server. In this example, we uninstall the EJB jar, Application Client WAR and database pool from server.This can be down by removing the Web and EJB projects from the server and by using the GShell command line to undeploy the database.

From the main page of the Plugin Manager wizard, select the Install Geronimo plugins and click Next.

Select all the Geronimo plugins that you want to install on the server. If Installable is false, then the plugin cannot be selected. The most common reasons that a plugin cannot be installed are if the version of the plugin is already installed on the server or if prerequisites are not available.

Clicking Next will install all selected plugins, and these three plugins will be installed and a confirmation page will be displayed showing what has been installed.