10.5. Maven 1.x Deployment Plugin

Geronimo includes a Maven 1 plugin that can start and stop a Geronimo server, deploy applications to a running server, start and stop applications, etc. This plugin is known as the geronimo-deployment-plugin (currently geronimo-deployment-plugin-1.0.0.jar).

10.5.1. Deployment Plugin Commands

The Geronimo deployment plugin for Maven has the following tasks (XML elements used in the Maven script):

Table 10.3. Maven Deployment Plugin Commands

ElementAttributesDescription
distributeuri, username, password, module, planDistributes a module to all the available targets on a server. This means the module will be validated and made available on the server, but not actually started.
starturi, username, password, idStarts a module that is available on the server but not running (actually, starts any modules with the specified name which are on any targets known to the server but are not yet running). A distribute followed by a start is what we typically think of as a deployment.
stopuri, username, password, idStops a module that is running on the server (technically, stops any modules with the specified name which are on a target known to the server and are currently running).
undeployuri, username, password, idUndeploys a module, which stops it if necessary and then removes it from the server's environment. Again, this operates on all modules with the specified name available on targets known to this server.
startServergeronimoHome, kernelName, domainName, configsStarts a Geronimo server within the Maven VM.
startRemoteServergeronimoTarget, vmArgs, configs, debugPort, output, errorStarts a Geronimo server in a new VM.
waitForStarteduri, username, password, maxTries, retryIntervalMilliseconds, idStalls until a Geronimo server becomes available at the specified location. This waits for a certain configuration to be registered, and it retries a specified number of times before giving up. The default is to retry every second and fail after 40 tries.
stopServerkernelNameStops a Geronimo server that was started within the Maven VM.
stopRemoteServeruri, username, passwordStops a Geronimo server that was started in a separate VM.
velocityFiltersourceDir, targetDir, forceRuns velocity on all .xml, .list, or .properties files in a specified directory, outputting the results to a different directory.

The attributes mentioned in Table 10.3, “Maven Deployment Plugin Commands” are:

uri

A URI to connect to a server. For stopRemoteServer and waitForStarted, this is a JMX URI to connect to the server, such as jmx:rmi://localhost/jndi/rmi:/JMXConnector. For distribute, start, stop, and undeploy, this is a JSR-88 URI such as deployer:geronimo:jmx://host:port.

username

The administrative username used to connect to the server.

password

The administrative password used to connect to the server.

id

The configId of the module to start, stop, undeploy, or wait for.

module

The file path of the module archive or directory to deploy. This required for applications and application modules, and optional when deploying new services.

plan

The file path of the deployment plan for the deployment. This is usually not required (the plan may be packed into the archive, for example).

geronimoHome

The installation directory of the Geronimo instance to start.

kernelName

The name to use for the new Geronimo kernel to start. This will be used to identify the Geronimo instance to stop.

domainName

The JMX domain name to use for the Geronimo instance

configs

A list of configuration names that should be started (equivalent to the --override command-line argument). It's best to avoid this as it's difficult to get the list exactly right and the server configuration can easily be corrupted.

geronimoTarget

The installation directory of the Geronimo instance to start.

vmArgs

Arguments to pass to the Java VM when starting the new Geronimo instance

debugPort

If specified, the new instance will be started in remote debug mode, and will listen on this port. Leave blank to start normally.

output

The name of a file to redirect the new instance's standard output to. If blank, set to the Maven VM's standard output.

error

The name of a file to redirect the new instance's standard error to. If blank, set to the Maven VM's standard error.

maxTries

If the task is unable to connect to the remote server after this many tries, it fails. Defaults to 40.

retryIntervalMilliseconds

How long to wait between connection attempts. Defaults to 1000 (one second).

sourceDir

The directory where the unaltered "source files" are stored.

targetDir

The directory to place the output files in after Velocity has processed each of the source file.

force

If set to "true", Velocity processing will be performed even if the files in the target directory appear to be up to date. This may be necessary, for example, if the substitution variables used by Velocity have been updated but the source filed have not.

10.5.2. Deployment Plugin Example

Example 10.3, “Maven 1 Script Using Geronimo Deployment Plugin” shows a sample Maven script using this plugin.

Example 10.3. Maven 1 Script Using Geronimo Deployment Plugin

The sample Maven 1 script fragment has three goals: one to start a server and wait for it to come up, one to deploy an application, and one to stop the server again at the end.

<goal name="startServer">
    <deploy:startRemoteServer
        geronimoTarget="/server/geronimo-1.0"
        vmArgs="-Xmx512m" />
    <ant:echo message="Waiting for server to start..." />
    <deploy:waitForStarted
            uri="jmx:rmi://localhost/jndi/rmi:/JMXConnector"
            username="system"
            password="manager"
            maxtries="120"
            id="geronimo/j2ee-deployer/1.0/car" />
    <echo message="Deployer has started" />
</goal>

<goal name="deployApplication">
    <deploy:distribute
            uri="deployer:geronimo:jmx"
            username="system"
            password="manager"
            module="my-application.ear"
            plan="my-ear-plan.xml" />
    <deploy:start
            uri="deployer:geronimo:jmx"
            username="system"
            password="manager"
            id="MyApplicationConfigID" />
</goal>

<goal name"stopServer">
    <deploy:stopRemoteServer
            uri="deployer:geronimo:jmx"
            username="system"
            password="manager" />
</goal>