Using the Deployer


The following is the generalized syntax of the command-line run-time deployer command:

 deployer [general options]  command  [command options]

The items enclosed in brackets are optional. You may specify one or more of them, or just leave them out.

If you are using the deploy.jar file directly, not using one of the scripts (deploy.bat or deploy.sh), the generalized command is:

 java -jar deploy.jar [general options]  command  [command options]

The following sections will examine each of available general options, commands, and command options.

Deployer General Options

The general options allow you to control the environment that the deployer will execute under. Table 6-1 describes the allowable general options.

Table 6-1: General Options for Command-Line Deployer
Open table as spreadsheet

Option

Description

--uri <URI to Geronimo server>

Specifies a URI for connect to a Geronimo server. By default, the deployer will connect to the server on the local host at TCP port 1099. Deploying to a remote server is possible by specifying a hostname (or IP address) and a TCP port number. The general format of the URI is deployer:geronimo: jmx:rmi:///jndi/rmi:[//host[:port]]/JMX Connector

--host

Another way to specify the host (or IP address) of the server that you are deploying to. The default is localhost.

--port

Another way to specify the TCP port of the server that you are deploying to. The default port value is 1099.

--driver <path to driver JAR file>

Allows you to use the deployer with other JSR-88-compatible servers. Ideally, this tool can work with other non-Geronimo servers. In practice, this is seldom used.

--user <user id>

Specifies the username for authentication to the Geronimo server. Use the --password option to specify the password. Most deployer commands require authentication. If you forget to specify this option, the deployer will prompt you for a user ID.

--password <password>

This is always used in conjunction with --user. Specifies the password associated with the specified username when authenticating to the Geronimo server. If you do not supply the password, the deployer will prompt you interactively for the password on the command line.

--syserr [ true | false ]

Instructs the deployer to log errors to syserr device. This is usually the console unless redirected. Default is false.

--verbose [ true | false ]

Turns verbose execution on or off. Default is false. Turning this on will give more information during deployment. Can be useful when debugging your deployments.

--offline

Use the offline deployer to deploy the module. As its name implies, the offline deployer allows you to deploy to the local repository without having an instance of the Geronimo server running.

Deployer Commands

There are several available deployer commands. These commands can be readily grouped as follows:

  • Commands that work with modules

  • Commands that provide information

  • Commands that work with Geronimo plug-ins

The following sections examine each of these groups in order.

Commands That Work with Modules

First, commands that work with modules are shown in Table 6-2.

Table 6-2: Commands That Work with Modules
Open table as spreadsheet

Command

Description

deploy

Deploy a module to the target server(s). A module can be an EAR, JAR, WAR, and so on. Internally, the module configuration is serialized to the repository by Geronimo. In addition, the var/config/config.xml file will be updated to include the module in the modules list. The deploy command will also start the module running. When this command is used with the offline deployer option (--offline), the module is marked to start the next time Geronimo starts up (via the var/config/config.xml file).

start

Start a stopped module running.

stop

Stop a running module.

undeploy

Remove and delete a previously deployed module from the repository, stopping it first if it is running.

redeploy

This is a shortcut command that combines an undeploy operation, immediately followed by a deploy on the specified module. This is useful when you are upgrading a deployed module.

distribute

Install a module without starting it. The operation performs the exactly sequence of steps as the deploy command, except the resulting module is not started by default. This also means that the module is added to the var/config/config.xml file with a load="false" attribute.

login

Save your user ID and password information to a file in your home directory (\Documents and Settings\<username> in Windows, and usually ~/<username> in *nix). The file is named .geron-imo-deployer. If you connect to multiple servers, Geronimo will save each of your user ID and password for each server. If you save the user ID and password, future deployer invocation will not require the --user and --password options.

Each of the commands shown in Table 6-2 may be executed even if the corresponding server is not running (offline mode) by specifying the --offline option

In the offline mode, starting and stopping of modules cannot occur. However, the corresponding configuration will be marked so that it will either run (or not run) the next time the server is started. This is done by adding the module to the var/config/config.xml and setting the load attribute appropriately. Again, this offline mode of operation is only supported when the Geronimo module to be started/stopped is local to the deployer (on the same physical machine).

Commands That Supply Information

Several commands of the online deployer do not manipulate any modules or the repository, but simply provide information. The commands that provide information are shown in Table 6-3, together with a description of their options where applicable.

Table 6-3: Commands That Supply Information
Open table as spreadsheet

Command

Description

help

This is the general help command, very useful to get a reminder of the available commands and options. The command deploy help options will provide general help on the available options. The command deploy help <command> will provide specific help on a command, including the options that the command may take.

list-modules

List the currently deployed modules. There are command options to show only started (--started) modules or only stopped modules (--stopped). The default is to show all deployed modules (--all). You can also specify the target(s) that the deployer will query for modules. The default is to query the local host.

list-targets

List all known targets by the current server. As of release 1.1, Geronimo does not support deployment to multiple physical servers. In release 1.1, if the single server manages multiple repositories, then each repository is considered a separate target. This command does not support any of the general options.

For example, to see the help for the list-targets command, use the following command:

 deploy help list-targets

To see all the modules that are in the started state, use the following:

 deploy list-modules --started

To see all the modules that have been marked to start, when the Geronimo server is not running, use the following:

 deploy --offline list-modules --started

Commands That Work with Geronimo Plug-Ins

Geronimo plug-ins are ready-to-use features and applications that can be easily installed over a network (or the Internet). Plug-ins are maintained in remote repositories. Chapter 17 (available on the companion Web site) explains plug-ins in more details. Two of the deployer’s commands work with plug-ins. These commands are shown in Table 6-4.

Table 6-4: Plug-In Support Command
Open table as spreadsheet

Command

Description

install-plugin

This command installs a plug-in. The command option should specify a plug-in descriptor XML file. This is frequently called plugin.xml. If you have just created or downloaded a plug-in, you should have this file.

search-plugins

The command option you must specify is a URL to the remote plug-in repository. A plug-in repository is simply a Maven 2 repository with plug-in installed.

Searching and Installing Plug-Ins

For example, the command to show all the plug-ins at the publicly accessible geronimoplugins.com site is as follows:

 deploy search-plugins http://www.geronimoplugins.com/repository/geronimo-1.1/

This will search the repository at geronimoplugins.com and a typical output might be as follows:

 Using GERONIMO_BASE:   C:\gerbuild\geronimo-1.1 Using GERONIMO_HOME:   C:\gerbuild\geronimo-1.1 Using GERONIMO_TMPDIR: C:\gerbuild\geronimo-1.1 \var\temp Using JRE_HOME:        C:\javabin\jdk14211 Username: system Password:     Security         1 : Apache Directory 0.92 for Geronimo (1.1-SNAPSHOT)     Core Geronimo             Geronimo Welcome Web App (Jetty) (1.1-SNAPSHOT)         2 : Geronimo Welcome Web App (Tomcat) (1.1-SNAPSHOT)         3 : Geronimo Admin Console (Tomcat) (1.1-SNAPSHOT)             Geronimo Admin Console (Jetty) (1.1-SNAPSHOT)     Examples             Jakarta JSP Examples (Jetty) (1.1-SNAPSHOT)         4 : LDAP Example Security Realm (1.1-SNAPSHOT)         5 : LDAP Example Web App (Tomcat) (1.1-SNAPSHOT)             Jakarta Servlet Examples (Jetty) (1.1-SNAPSHOT)         6 : Jakarta JSP Examples (Tomcat) (1.1-SNAPSHOT)             LDAP Example Web App (Jetty) (1.1-SNAPSHOT)         7 : Jakarta Servlet Examples (Tomcat) (1.1-SNAPSHOT)     Resources         8 : Oracle XA Driver for Console (Tomcat) (1.0)             Oracle XA Driver for Console (Jetty) (1.0) Install Service [enter number or 'q' ; to quit ]:q

This menu allows you to choose a plug-in to install interactively.

Obtaining Module Run-Time State Information

It is possible to obtain run-time state information using the deployer. The following shows the typical output from a list-modules command of the run-time deployer:

 C:\gerbuild\geronimo-1.1-rc1\bin>deploy --user system --password manager list-mo dules Using GERONIMO_BASE:   C:\gerbuild\geronimo-1.1 Using GERONIMO_HOME:   C:\gerbuild\geronimo-1.1 Using GERONIMO_TMPDIR: C:\gerbuild\geronimo-1.1\var\temp Using JRE_HOME:        C:\javabin\jdk14211 Found 32 modules   + geronimo/activemq/1.1/car   + geronimo/activemq-broker/1.1/car   + geronimo/axis/1.1/car   + geronimo/axis-deployer/1.1/car   + geronimo/client-deployer/1.1/car   + geronimo/geronimo-gbean-deployer/1.1/car   + geronimo/hot-deployer/1.1/car   + geronimo/j2ee-deployer/1.1/car   + geronimo/j2ee-security/1.1/car   + geronimo/j2ee-server/1.1/car   + geronimo/j2ee-system/1.1/car   + geronimo/openejb/1.1/car   + geronimo/openejb-deployer/1.1/car   + geronimo/remote-deploy-tomcat/1.1/car @ http://your-e7427193eb:8080/remo te-deploy   + geronimo/rmi-naming/1.1/car   + geronimo/sharedlib/1.1/car   + geronimo/system-database/1.1/car   + geronimo/tomcat/1.1/car   + geronimo/tomcat-deployer/1.1/car   + geronimo/webconsole-tomcat/1.1/car       `-> standard.war @ http://your-e7427193eb:8080/console-standard       `-> framework.war @ http://your-e7427193eb:8080/console   + geronimo/welcome-tomcat/1.1/car @ http://your-e7427193eb:8080/     geronimo/client/1.1/car     geronimo/client-corba/1.1/car     geronimo/client-security/1.1/car     geronimo/client-system/1.1/car     geronimo/j2ee-corba/1.1/car     geronimo/javamail/1.1/car     geronimo/online-deployer/1.1/car     geronimo/shutdown/1.1/car     geronimo/uddi-tomcat/1.1/car     geronimo/upgrade/1.1/car     geronimo/upgrade-cli/1.1/car

Note in this listing that some modules listed are marked with a leading “+” sign, while others are not. Every one of the modules marked with a leading “+” is started and in the running state. Any listed module that does not have a leading “+” is in the repository but has not been started.

There is an alternative way to obtain this run-time state information via the Geronimo Web console. Using the Web console, you can select one of the options in the Applications heading and see the current run-time state of installed modules of different type. Figure 6-4 shows the Web Console display of System Modules.

image from book
Figure 6-4: Using the Web console to display module run-time state

In Figure 6-4, the actual state of each configuration is show in its own column. You can see that the geronimo/client-corba/1.1/car module is stopped, while the geronimo/tomcat/1.1/carmodule is running.

Chapter 8 provides more detail on the options available with the Web console.

The Maven Deployment Plug-In

Another very useful tool (directly related to online deployer) is the deployment plug-in designed for Maven 1.x. This plug-in takes advantage of the Geronimo deployer’s JSR-88 compliance, and enables deployment from within a Maven script.

Maven is Geronimo’s project management tool designed to work with very large projects that may include many subprojects. If you need to rebuild Geronimo (say, to create a custom assembly), you will need to install and run Maven. Using Maven, you can also script frequently performed administration tasks as Maven build goals.

If you are not already familiar with Maven, consult the official Maven documentation at the URL below:

http://maven.apache.org/maven-1.x

The official Maven Web site provides an overview, introduction, and examples for using Maven. There are two current versions of Maven: Maven 1.1 and Maven 2.0. The plug-in for Geronimo 1.1 currently works with Maven 1.x only.

The remainder of this chapter covers the Maven plug-in for Geronimo deployment. This plug-in enables you to create Maven scripts to automate some administrative tasks. A couple of cookbook-style examples will show how you may use the deployment plug-in with Maven.

Maven 1.x can be configured to find this plug-in and its associated tag libraries through two XML configuration files: project.xml and maven.xml. To allow Maven to find the plug-in, add the following <dependency> to the <dependencies> section of the project.xml file:

 <dependencies>         <dependency>             <groupId>geronimo</groupId>             <artifactId>geronimo-deployment-plugin</artifactId>             <version>1..1</version>             <type>plugin</type>         </dependency>         ...        <dependency>             ....         </dependency>        .... </dependencies> 

You can then add a namespace for the elements in your plug-in by adding the highlighted element of the <project> element in the maven.xml file:

 <project default="default"     xmlns:j="jelly:core"     xmlns:u="jelly:util"     xmlns:ant="jelly:ant"     xmlns:define="jelly:define"     xmlns:velocity="jelly:velocity"     xmlns:bootstrap="geronimo:bootstrap"     xmlns:deploy="geronimo:deploy"     xmlns:artifact="artifact"     xmlns:m="jelly:maven"     >

Once you have declared the namespace, you can use the various elements available for the plug-in. Table 6-5 enumerates the available elements and describes their functions.

Table 6-5: Functional Elements Available in the Geronimo Maven Deployment Plug-In
Open table as spreadsheet

Element

Description

<deploy:deploy>

Deploy a module, a module and a plan, or a plan to the specified server. The specified module will be started on the server. The server is specified via a uri attribute. You can supply a username and password attribute to authenticate the user. Both the module and plan attributes are optional, but one of them must exist.

<deploy:undeploy>

Undeploy a module to the specified server. The server is specified via a uri attribute. The module will be removed from the repository and the server instance’s var/config/config.xml file.

<deploy:distribute>

Deploy a module, a module and a plan, or a plan to the specified server. The specified module will not be started on the server. Instead, it will be installed. The server is specified via a uri attribute. You can supply a username and password attribute to authenticate the user. Both the module and plan attributes are optional, but one of them must exist.

<deploy:waitForStarted>

Wait for the startup of a remote server. This element is useful when you need to synchronize with the starting of a Geronimo server.

<deploy:startRemoteServer>

Start a Geronimo server instance.

<deploy:stopRemoteServer>

Stop a Geronimo server instance.

<deploy:start>

Start a Geronimo module.

<deploy:stop>

Stop a Geronimo module.

The following sections provide you with cookbook-style Maven script segments that you can use to perform specific functions using the elements shown in Table 6-5.

Deploying a Module to a Geronimo Server and Starting It

The following script segment can be used within Maven to deploy a module to a Geronimo server and start it:

 <deploy:deploy   uri="deployer:geronimo:jmx:rmi://localhost/jndi/rmi:/JMXConnector"   username="system"   password="manager"   plan="c:/myplans/mywebdeployment.xml"   module="c:/mymodules/mywebapp.war"   />

Note the format of the uri attribute. This is the JMX connector used by Geronimo for run-time deployment.

The plan attribute is optional, and you only need it if you have a Geronimo-specific deployment plan for the module that you are deploying.

Distributing a Module to a Geronimo Server without Running It

The following script segment can be used within Maven to distribute a module to a Geronimo server without starting it. This will install the application in the server’s repository. The application will be marked to start the next time the server is started (by modifying the config/config.xml file).

 <deploy:distribute    uri="deployer:geronimo:jmx"    username="system"    password="manager"    plan="c:/myplans/mywebdeployment.xml"    module="c:/mymodules/mywebapp.war"    />

Note the format of the uri attribute. This is the JMX connector used by Geronimo for run-time deployment.

The plan attribute is optional, and you only need it if you have a Geronimo-specific deployment plan for the module that you are deploying.

Starting Geronimo Server Instance

You can launch an instance of a Geronimo server using a Maven script and the startRemoteServer element, as shown here:

 <deploy:startRemoteServer    geronimoTarget="c:/gerbuild/geronimo-1.1"    vmArgs="-Xmx512m ... />

To ensure that the server starts properly, you must specify the Geronimo installation directory (on the local host) with the geronimoTarget attribute. You can then set any JVM arguments in the vmArgs attribute.

Waiting for a Geronimo Configuration to Start

It is not safe to start interacting with a server instance immediately after the preceding script is executed. This is because it takes a significant amount of time to start all the configurations for a running server instance. Because one module may depend on another, Geronimo may have to start many other modules before starting a specified module that is to run.

The following Maven script segment can be used to wait until a specific Geronimo configuration has started successfully. In the following example, the script segment will wait for the geronimo/tomcat/1.1/car, the Tomcat server module, to start. This is specified by the id attribute of the element. Note that this specific element uses a polling algorithm to determine if a configuration has started, and the maxtries attribute specifies how many times to retry if the configuration has not yet started

 <deploy:waitForStarted    uri="deployer:geronimo:jmx:rmi://localhost/jndi/rmi:/JMXConnector"    maxtries="125"    username="system"    password="manager"    />

Shutting Down Geronimo Server from a Script

It is possible to shut down an instance of the Geronimo server from a Maven script. Use the following script segment to shut down the Geronimo server on the local host. You need not change the value of any of the attributes.

 <deploy:stopRemoteServer     uri="deployer:geronimo:jmx:rmi://localhost/jndi/rmi:/JMXConnector"     username="system"     password="manager"/>




Professional Apache Geronimo
Professional Apache Geronimo (Wrox Professional Guides)
ISBN: 0471785431
EAN: 2147483647
Year: 2004
Pages: 148

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net