Apache Geronimo is now assembled completely out of plugins including the server configuration files, in this section we will explain the overview of plugin system and introduce concept of plugin groups betaken starting from v2.2.

Plugin basics

A Geronimo plugin is a jar-structured file that contains a geronimo plugin consists of a classloader specification, optional classes, optional service or component configuration, and information about how to install it in Geroninimo. The classloader specification and service configuration is specified in a Geronimo plan (and possibly other plans such as a javaee spec DD or annotations). The information about how to install the plugin is provided in the META-INF/geronimo-plugin.xml descriptor following this schema:

Wiki Markup
{snippet:url=geronimo/server/tags/2.1.0/framework/modules/geronimo-system/src/main/xsd/plugins-1.3.xsd\|lang=xml}

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.

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.

file. This file includes details such as the category and description, dependency information showing what else needs to be installed with this plugin, information on files to be unpacked on installation, and configuration information showing how and when the plugin will be started. Before looking at the more complicated aspects of the plugins lets look at a simple example of geronimo-plugin.xml. Here is an example for the jetty web container:

First we see fairly obvious cataloging information:

Code Block

	xml
	xml
borderStyle	solid


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<geronimo-plugin xmlns="http://geronimo.apache.org/xml/ns/plugins-1.3" xmlns:ns2="http://geronimo.apache.org/xml/ns/attributes-1.2">
    <name>Geronimo Configs :: Jetty 6</name>
    <category>Jetty</category>
    <description>Geronimo Jetty Web Server integration.</description>
    <url>http://geronimo.apache.org/</url>
    <author>The Apache Geronimo development community</author>
    <license osi-approved="true">The Apache Software License, Version 2.0</license>

Each geronimo-plugin.xml can specify information for many versions of the "same" plugin, so the plugin-artifact element specifying info for one version can occur multiple times. Here there is just one. First we see the plugin moduleId and the list of dependencies that will be installed if not already present.

Code Block

	xml
	xml
borderStyle	solid


    <plugin-artifact>
        <module-id>
            <groupId>org.apache.geronimo.configs</groupId>
            <artifactId>jetty6</artifactId>
            <version>2.1-SNAPSHOT</version>
            <type>car</type>
        </module-id>
        <geronimo-version>2.1-SNAPSHOT</geronimo-version>
        <jvm-version>1.5</jvm-version>
        <dependency start="true">
            <groupId>org.apache.geronimo.configs</groupId>
            <artifactId>j2ee-server</artifactId>
            <version>2.1-SNAPSHOT</version>
            <type>car</type>
        </dependency>
        <dependency start="true">
            <groupId>org.apache.geronimo.configs</groupId>
            <artifactId>server-security-config</artifactId>
            <version>2.1-SNAPSHOT</version>
            <type>car</type>
        </dependency>
        <dependency start="true">
            <groupId>org.apache.geronimo.configs</groupId>
            <artifactId>transaction</artifactId>
            <version>2.1-SNAPSHOT</version>
            <type>car</type>
        </dependency>
        <dependency start="true">
            <groupId>org.apache.geronimo.modules</groupId>
            <artifactId>geronimo-jetty6</artifactId>
            <version>2.1-SNAPSHOT</version>
            <type>jar</type>
        </dependency>
        <dependency start="true">
            <groupId>org.apache.geronimo.configs</groupId>
            <artifactId>clustering</artifactId>
            <version>2.1-SNAPSHOT</version>
            <type>car</type>
        </dependency>
        <dependency start="true">
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
            <version>1.4.3</version>
            <type>jar</type>
        </dependency>
        <dependency start="true">
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-jcl</artifactId>
            <version>1.4.3</version>
            <type>jar</type>
        </dependency>
        <dependency start="true">
            <groupId>org.mortbay.jetty</groupId>
            <artifactId>jetty</artifactId>
            <version>6.1.5</version>
            <type>jar</type>
        </dependency>
        <dependency start="true">
            <groupId>org.mortbay.jetty</groupId>
            <artifactId>jetty-ajp</artifactId>
            <version>6.1.5</version>
            <type>jar</type>
        </dependency>
        <dependency start="true">
            <groupId>org.mortbay.jetty</groupId>
            <artifactId>jetty-sslengine</artifactId>
            <version>6.1.5</version>
            <type>jar</type>
        </dependency>
        <dependency start="true">
            <groupId>org.mortbay.jetty</groupId>
            <artifactId>jetty-util</artifactId>
            <version>6.1.5</version>
            <type>jar</type>
        </dependency>
        <dependency start="true">
            <groupId>org.apache.geronimo.configs</groupId>
            <artifactId>webservices-common</artifactId>
            <version>2.1-SNAPSHOT</version>
            <type>car</type>
        </dependency>

Now we see the list of repositories this plugin is expected to be available from. We normally include the local maven repository to make developing plugins easier.

Code Block

	xml
	xml
borderStyle	solid



        <source-repository>~/.m2/repository/</source-repository>
        <source-repository>http://repo1.maven.org/maven2/</source-repository>
        <source-repository>http://people.apache.org/repo/m2-snapshot-repository/</source-repository>
        <source-repository>http://people.apache.org/repo/m2-incubating-repository/</source-repository>

Here we see the prototype for plugin customization. The config.xml file has a section for each module or plugin it knows about and the contents of the config-xml-content is copied into such an element. Note the use of substitution variables such as ${ServerHostname}.

Code Block

	xml
	xml
borderStyle	solid


        <config-xml-content>
            <ns2:gbean name="JettyWebConnector">
                <ns2:attribute name="host">$\{ServerHostname\}</ns2:attribute>
                <ns2:attribute name="port">$\{HTTPPort + PortOffset\}</ns2:attribute>
                <ns2:attribute name="redirectPort">$\{HTTPSPortPrimary + PortOffset\}</ns2:attribute>
            </ns2:gbean>
            <ns2:gbean name="JettyAJP13Connector">
                <ns2:attribute name="host">$\{ServerHostname\}</ns2:attribute>
                <ns2:attribute name="port">$\{AJPPort + PortOffset\}</ns2:attribute>
                <ns2:attribute name="redirectPort">$\{HTTPSPortPrimary + PortOffset\}</ns2:attribute>
            </ns2:gbean>
            <ns2:gbean name="JettySSLConnector">
                <ns2:attribute name="host">$\{ServerHostname\}</ns2:attribute>
                <ns2:attribute name="port">$\{HTTPSPort + PortOffset\}</ns2:attribute>
            </ns2:gbean>
        </config-xml-content>

Here we see the default values of the substitution variables. These are copied into the config-substitutions.properties file; you are expected to modify these by hand as necessary.

Code Block

	xml
	xml
borderStyle	solid


        <config-substitution key="HTTPPort">8080</config-substitution>
        <config-substitution key="AJPPort">8009</config-substitution>
        <config-substitution key="HTTPSPort">8443</config-substitution>
        <config-substitution key="ServerHostname">0.0.0.0</config-substitution>
        <config-substitution key="webcontainer">JettyWebContainer</config-substitution>
        <config-substitution key="webcontainerName">jetty6</config-substitution>

Missing from this example is the <artifact-alias> element which can be used to replace one plugin by another. For instance you can switch databases by deploying e.g postgres-system-database and specifying <artifact-alias key="org.apache.geronimo.configs/system-database/2.1-SNAPSHOT/car">org.apache.geronimo.configs/postgres-system-database/2.1-SNAPSHOT/car</artifact-alias>

Code Block

	xml
	xml
borderStyle	solid


    </plugin-artifact>
</geronimo-plugin>

One of the more obvious parts of Geronimo is the repository which contains jars as well as plugins. However the plugins by themselves don't do anything; we need some information about which ones to start and how to customize them in order to get a functioning server. This kind of information is normally stored in configuration files in the var/config directory such as config.xml, config-substitutions.properties and artifact_aliases.properties. There are several "servers" you can start in a normal Geronimo installation, such as the "server", the app client container, the deployer, and the jsr88 tool. The plugin system abstracts this idea of a "server instance" with a ServerInstance gbean that specifies the attribute store (relating to the config.xml and config-substitutions.xml files) and artifact resolver (relating to the artifact_aliases.properties file). So the plugin system requires that you set up ServerInstances for all the kinds of servers you expect to start in a Geronimo installation. For instance, the normal Geronimo setup includes these:

Code Block

	xml
	xml
borderStyle	solid


    <gbean name="DefaultServer" class="org.apache.geronimo.system.plugin.ServerInstance">
        <attribute name="serverName">default</attribute>
        <reference name="PluginAttributeStore">
            <name>AttributeManager</name>
        </reference>
        <reference name="ArtifactResolver">
            <name>ArtifactResolver</name>
        </reference>
    </gbean>

    <gbean name="Offline" class="org.apache.geronimo.system.plugin.ServerInstance">
        <attribute name="serverName">offline</attribute>
        <reference name="PluginAttributeStore">
            <name>OfflineAttributeManager</name>
        </reference>
        <reference name="ArtifactResolver">
            <name>ArtifactResolver</name>
        </reference>
    </gbean>
    <gbean name="OfflineAttributeManager" class="org.apache.geronimo.system.configuration.LocalAttributeManager">
        <reference name="ServerInfo">
            <name>ServerInfo</name>
        </reference>
        <attribute name="readOnly">true</attribute>
        <attribute name="configFile">var/config/offline-deployer-config.xml</attribute>
        <attribute name="substitutionsFile">var/config/config-substitutions.properties</attribute>
        <attribute name="substitutionPrefix">org.apache.geronimo.config.substitution.</attribute>
    </gbean>

    <gbean name="Client" class="org.apache.geronimo.system.plugin.ServerInstance">
        <attribute name="serverName">client</attribute>
        <reference name="PluginAttributeStore">
            <name>AttributeManager</name>
        </reference>
        <reference name="ArtifactResolver">
            <name>ClientArtifactResolver</name>
        </reference>
    </gbean>
    <gbean name="ClientArtifactResolver" class="org.apache.geronimo.system.resolver.ExplicitDefaultArtifactResolver">
        <reference name="ArtifactManager">
            <name>ArtifactManager</name>
        </reference>
        <reference name="Repositories"></reference>
        <attribute name="versionMapLocation">var/config/client_artifact_aliases.properties</attribute>
        <reference name="ServerInfo">
            <name>ServerInfo</name>
        </reference>
    </gbean>

    <gbean name="Jsr88" class="org.apache.geronimo.system.plugin.ServerInstance">
        <attribute name="serverName">jsr88</attribute>
        <reference name="PluginAttributeStore">
            <name>Jsr88AttributeManager</name>
        </reference>
        <reference name="ArtifactResolver">
            <name>ArtifactResolver</name>
        </reference>
    </gbean>
    <gbean name="Jsr88AttributeManager" class="org.apache.geronimo.system.configuration.LocalAttributeManager">
        <reference name="ServerInfo">
            <name>ServerInfo</name>
        </reference>
        <attribute name="readOnly">true</attribute>
        <attribute name="configFile">var/config/jsr88-configurer-config.xml</attribute>
        <attribute name="substitutionsFile">var/config/config-substitutions.properties</attribute>
        <attribute name="substitutionPrefix">org.apache.geronimo.config.substitution.</attribute>
    </gbean>

By default, plugins are installed into the default server instance. If you need to install into a different instance you can specify this in the config-xml-content, config-substitution, and artifact-alias elements. Here's an example from client-transaction, showing how it redirects any dependencies to the server transaction plugin to itself.

Code Block

	xml
	xml
borderStyle	solid


<artifact-alias server="client" key="org.apache.geronimo.configs/transaction//car">org.apache.geronimo.configs/client-transaction/2.1-SNAPSHOT/car</artifact-alias>
<artifact-alias server="client" key="org.apache.geronimo.configs/transaction/2.1-SNAPSHOT/car">org.apache.geronimo.configs/client-transaction/2.1-SNAPSHOT/car</artifact-alias>

plugin groups

Include Page

	GMOxDOC22:Plugin groups
	GMOxDOC22:Plugin groups

Look into Administering plugins for how to manage a pluginLook in to Administering plugins for more details.

Child pages

Versions Compared

Old Version 15

New Version 16

Key

Plugin basics

Additional information

Where does this additional configuration information go?

Finding a plugin

plugin groups

Child pages

Page History

Versions Compared

Old Version 15

New Version 16

Key

Plugin basics

Additional information

Where does this additional configuration information go?

Finding a plugin

plugin groups