10.5. Maven 1.x Deployment Plugin

10.5. Maven 1.x Deployment Plugin
	Chapter 10. Development & Deployment Overview [DRAFT (1.0)]

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

Element	Attributes	Description
distribute	uri, username, password, module, plan	Distributes 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.
start	uri, username, password, id	Starts 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.
stop	uri, username, password, id	Stops 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).
undeploy	uri, username, password, id	Undeploys 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.
startServer	geronimoHome, kernelName, domainName, configs	Starts a Geronimo server within the Maven VM.
startRemoteServer	geronimoTarget, vmArgs, configs, debugPort, output, error	Starts a Geronimo server in a new VM.
waitForStarted	uri, username, password, maxTries, retryIntervalMilliseconds, id	Stalls 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.
stopServer	kernelName	Stops a Geronimo server that was started within the Maven VM.
stopRemoteServer	uri, username, password	Stops a Geronimo server that was started in a separate VM.
velocityFilter	sourceDir, targetDir, force	Runs 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>


10.4. The Deploy Tool		10.6. JSR-88 Configuration & Deployment Tools