Installing a plugin

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.

Creating a plugin

You can create a plugin as part of a maven build 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 using the Geronimo administrative console to create or edit the plugin metadata.

Building,installing plugins and assembling a server from an exsiting server

More details about this topic, please see Buidling,installing plugins and assembling a server from an exsiting server

Assembling a server using maven.

The easiest way to assemble a server is to use maven and the car-maven-plugin. The dependencies from your pom will be installed in your server, and if they are plugins they will be installed as modules with all dependencies and stuff unpacked and metadata installed into the correct files. Here's a simple example assembling a server that supports Roller and includes the basic admin console.

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the "License"); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at
    
       http://www.apache.org/licenses/LICENSE-2.0
    
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
-->

<!-- $Rev$ $Date$ -->

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.apache.geronimo.plugins</groupId>
        <artifactId>roller-parent</artifactId>
        <version>1.0-SNAPSHOT</version>
    </parent>

    <groupId>org.apache.geronimo.assemblies</groupId>
    <artifactId>geronimo-jetty-roller</artifactId>
    <name>Geronimo Assemblies :: Roller + Jetty6</name>
    <packaging>application-assembly</packaging>

    <description>
        A Geronimo server assembly for Roller using the Jetty web-container.
    </description>

    <dependencies>
        <dependency>
            <groupId>org.apache.geronimo.assemblies</groupId>
            <artifactId>geronimo-boilerplate-minimal</artifactId>
            <version>${geronimoVersion}</version>
            <type>jar</type>
        </dependency>

        <dependency>
            <groupId>org.apache.geronimo.plugins</groupId>
            <artifactId>roller-jetty</artifactId>
            <version>${version}</version>
            <type>car</type>
        </dependency>
        <dependency>
            <groupId>org.apache.geronimo.plugins</groupId>
            <artifactId>roller-themes</artifactId>
            <version>${version}</version>
            <type>car</type>
        </dependency>
        <dependency>
            <groupId>org.apache.geronimo.plugins</groupId>
            <artifactId>console-jetty</artifactId>
            <version>${geronimoVersion}</version>
            <type>car</type>
        </dependency>
    </dependencies>

    <build>

        <plugins>

            <plugin>
                <groupId>org.apache.geronimo.buildsupport</groupId>
                <artifactId>car-maven-plugin</artifactId>
                <executions>
                    <execution>
                        <id>install</id>
                        <phase>compile</phase>
                        <goals>
                            <goal>install-modules</goal>
                        </goals>
                    </execution>
                    <execution>
                        <id>archive</id>
                        <phase>package</phase>
                        <goals>
                            <goal>archive</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <servers>
                        <serverInstance>
                            <name>default</name>
                            <configFile>var/config/config.xml</configFile>
                            <configSubstitutionsFile>var/config/config-substitutions.properties</configSubstitutionsFile>
                            <configSubstitutionsPrefix>org.apache.geronimo.config.substitution.</configSubstitutionsPrefix>
                            <artifactAliasesFile>var/config/artifact_aliases.properties</artifactAliasesFile>
                        </serverInstance>
                        <serverInstance>
                            <name>client</name>
                            <attributeManagerFrom>default</attributeManagerFrom>
                            <artifactAliasesFile>var/config/client_artifact_aliases.properties</artifactAliasesFile>
                        </serverInstance>
                        <serverInstance>
                            <name>offline</name>
                            <configFile>var/config/offline-deployer-config.xml</configFile>
                            <configSubstitutionsFile>var/config/config-substitutions.properties</configSubstitutionsFile>
                            <configSubstitutionsPrefix>org.apache.geronimo.config.substitution.</configSubstitutionsPrefix>
                            <artifactAliasesFile>var/config/artifact_aliases.properties</artifactAliasesFile>
                        </serverInstance>
                        <serverInstance>
                            <name>jsr88</name>
                            <configFile>var/config/jsr88-configurer-config.xml</configFile>
                            <configSubstitutionsFile>var/config/config-substitutions.properties</configSubstitutionsFile>
                            <configSubstitutionsPrefix>org.apache.geronimo.config.substitution.</configSubstitutionsPrefix>
                            <artifactAliasesFile>var/config/artifact_aliases.properties</artifactAliasesFile>
                        </serverInstance>
                    </servers>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

Upgrading jars and plugins to a new version

Aliasing jars and modules

You may want to change the version of jars or plugins from those used when you geronimo server was assembled, or completely replace one with another. This can be done for any artifact in the geronimo repository, but not for jars in the lib directory. We hope to move almost all the jars out of lib shortly, but this is not yet possible.

Recall that the geronimo repository, like a maven 2 repository, is structured like

/path/like/groupId/artifactId/version/artifactId-version.type

for an artifact

path.like.groupId/artifactId/version/type

To install a new version of an artifact you typically need to create a new directory corresponding to the version, then copy the artifact into that directory. There is an admin console page that helps with this.

Dependencies in geronimo plugins can be specified with or without a fixed version. If all the dependencies on the artifact you are replacing are specified without a fixed version, you can simply add your new artifact to the appropriate place in the geronimo repository and, if the version is newer than the old artifact, it will be used by geronimo the next time the plugins that use it are started. If your artifact has a lower version than what it is replacing, you need to remove the old artifact.

If at least one dependency is specified with a fixed version or you are using a different artifact, you need to specify the replacement more explicitly. For the main geronimo server this would be in the var/config/artifact_aliases.properties file, and for the app client it would be in the var/config/client_artifact_aliases.properties file.

The format for entries in these files is oldartifactid=newartifactId, here are two examples. Versions can be omitted on the left side but not the right. This can also specify explicit versions in the same format. Note that many of these examples have two lines for the "same" replacement. If all the dependencies specify the version, only need the line with the version specified in the left hand side. If all the dependencies omit the version, you only need the line without the version specified in the left hand side. At the moment whether or not versions are specified in geronimo dependencies is somewhat disorganized and random.

artifact-aliases.properties

org.apache.geronimo.configs/j2ee-server//car=org.apache.geronimo.configs/j2ee-server/2.1/car

client-artifact-aliases.properties

org.apache.geronimo.framework/j2ee-system//car=org.apache.geronimo.framework/client-system/2.1/car
org.apache.geronimo.framework/j2ee-security//car=org.apache.geronimo.configs/client-security/2.1/car
org.apache.geronimo.framework/j2ee-system/2.1/car=org.apache.geronimo.framework/client-system/2.1/car
org.apache.geronimo.configs/j2ee-server//car=org.apache.geronimo.configs/client/2.1/car
org.apache.geronimo.configs/transaction//car=org.apache.geronimo.configs/client-transaction/2.1/car
org.apache.geronimo.configs/transaction/2.1/car=org.apache.geronimo.configs/client-transaction/2.1/car
org.apache.geronimo.framework/j2ee-security/2.1/car=org.apache.geronimo.configs/client-security/2.1/car
org.apache.geronimo.configs/j2ee-server/2.1/car=org.apache.geronimo.configs/client/2.1/car

While you can modify these files by hand, a more recommended method is to deploy your applications as geronimo plugins and to install these aliases through the geronimo-plugin.xml descriptor, which is genereated when you build your plugin using maven. There are some examples Plugins in Geronimo

Updating a plugin

At times, you may need to upgrade a plugin or jar version, for instance if a new version of a dependency is released but you cannot rerelease all the artifacts that depend on it. Here are some methods to upgrade jar versions.

Simple jar upgrade

If the jar is to be installed as part of a plugin installation, see the section below. Otherwise, follow these steps. First, if the server is running, stop the server. Second, 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, the admin console portlet Services->Repository can be used 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). For instance, to replace myjar-1.0.jar with myjar-1.1.jar:

org.foo/myjar/1.0/jar=org.foo/myjar/1.1/jar

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

<artifact-alias key="org.foo/myjar/1.0/jar">org.foo/myjar/1.1/jar</artifact-alias>