Excerpt |
---|
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 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
file. This file includes details such as the category and description, dependency information showing what else needs to be installed with this plugin, information about 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 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 information 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 |
---|
|
<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 |
---|
|
<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 in geronimo-plugin.xml
are copied into such an element in config.xml
. Note the use of substitution variables such as ${ServerHostname}.
Code Block |
---|
|
<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 |
---|
|
<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 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 |
---|
|
</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 |
---|
|
<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 |
---|
|
<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>
|
Plugins group
Include Page |
---|
| Plugins group |
---|
| Plugins group |
---|
|
Look into Administering plugins for how to manage a plugin
Plugins
Plugins can be system modules, applications, classloader definitions, and plugin groups. The WASCE 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.
What is 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.
How do I find plugins?
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.
How do I install plugins?
You can install a plugin into an existing server in different ways:
- Gshell deploy/list-plugins command
- Geronimo administrative console
- Using maven and the geronimo-maven-plugin
You can also install a plugin into a new server assembly using the car-maven-plugin.
Note that in all cases the dependency system assure that if you install a plugin, everything 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.
How do I create plugins?
...
.