Plugins

Plugins can be system modules, applications, classloader definitions, and plugin groups. The Geronimo server is assemblages of plugins. Assemblies are the different ways you can create a server out of the various pluging available. Starting with Geronimo 2.1 and 2.2, the servers are assembled entirely out of plugins.

Introduction to a plugin

Plugins have an identifier with groupId, artifactId, version, and type. It's possible to have a plugin without a moduleId but this is not currently used.

• A plugin can define a classloader in which case:
  • A plugin with a classloader can define geronimo services (gbeans) that can use classes in the classloader (and its parents).
  • A plugin can depend on this classloader. For exampple, it can have this classloader as a parent.
  • A plugin can contain classes which are made available in the classloader. This is used mostly for Java EE application plugins, where the application classes are packed in the plugin.
• A plugin can contain resources that are unpacked into the server upon installation (typically in the var/ directory in a plugin-specific location).
• A plugin includes a list of dependencies. This is intended to normally be as effective as the classloader dependencies, if there is a classloader.
• A plugin without a classloader definition still includes a list of dependencies. These are typically used as "plugin groups" to install a set of plugins at once.

Plugins can contain both server functionality and application functionality or both. For instance, you can include a web server configuration in a web application plugin.

Finding a plugin

Plugins are listed in plugin catalogs which contain information about the plugins (typically name and description) and where to get the plugin.
Plugins are normally stored in plugin repositories which act much like maven2 repositories. The most common examples of plugin repositories are the following:

• Your local maven repository if you have built geronimo or used maven to package plugins.
• The Apache plugin repository containing all the plugins packages by the Apache Geronimo project.
• Another geronimo server running the jetty or tomcat plugin-console plugin.

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, the admin console, or the Geronimo Eclipse Plugin.
• 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.

Look in to Administering plugins for more details.