Deploying and administering applications

Starting and stopping applications

When you develop a Java EE asset, you must include Java EE deployment descriptors as required by the Java EE specification. Although necessary, Java EE deployment descriptors are not sufficient to deploy your asset in a server. They do not include information unique to the application server or a given server's configuration.

Your server uses deployment plans to provide the missing details. Each deployment plan is an XML document where the document schema depends on the Java EE module that you wish to deploy.

The following sections will help you choose the correct deployment plan schema and the correct deployment options.

Deploying without a deployment plan

If you want to deploy a Java EE asset without a deployment plan, the server will perform the operation with default values.

• If your asset is very simple, for example, just servlets and JSPs that require no security and do not access any external resources, you can deploy without a deployment plan.
• If the asset developers have carefully crafted their asset so that the required resource names precisely match the names configured in your server, you can deploy without a deployment plan.

This option might be convenient if you are deploying samples, migrating simple assets intended for other application servers, or working with assets under development, but it is typically worthwhile to take a broader view. Successful assets do not always stay simple and you need to provide a deployment plan when your asset

• Needs to be served from an explicit context
• Depends on external Java libraries not included in the default classpath
• Uses security roles or a security realm other than the system default realm
• References a resource (a data source, a message queue, a connector) that must be matched to the server's configuration
• Uses an external EJB
• Implements a connector that requires configuration.

Even if you believe that a deployment plan might not be necessary for a particular Java EE asset, consider providing a deployment plan so that your plans and procedures include it. This will simplify your effort when the asset is enhanced to the point where a deployment plan is required.

Choosing a deployment plan packaging option

Deployment plans can be packaged as a file within your Java EE asset's archive or as a separate file. To choose between these options consider the following trade-offs.

• If you place the plan within the archive, you simplify the effort required to distribute and deploy the asset. Users have only one file to manage and one file name to enter during a deploy operation. On the other hand, if the users need to modify the plan, they must extract the archive, make their changes, and rebuild the archive before they can deploy the asset.
• If you package the deployment plan as a separate file, you simplify the effort to modify the plan to match the users' particular server configuration. On the other hand, the users must manage two files, the archive and the deployment plan, and specify both when they deploy the asset.

If you are distributing the asset to a collection of users where the server configurations are identical and well known, packaging the deployment plan in the archive is preferred. If you are distributing the asset to a collection of users where server configurations are varied and unknown, the plan will need to be modified and an external plan is preferred.

If you choose to package your deployment plan within the archive, you must give the file a required name and place it in a required location. See the next section for details.

Choosing the correct XML document element

When you develop a deployment plan, the XML document element you use will depend on the Java EE module type that you intend to deploy. In addition, the format of the document must comply with the XML schema found in your server. Schemas can be found in <WASCE_HOME>/schema where <WASCE_HOME> is the server's installation directory.

Furthermore, if you intend to package your deployment plan within the module you wish to deploy, you must give the file a required name and place it in a required location.

There are several alternatives available for Deploying and undeploying applications:

• Geronimo Administration Console
• #Deployer tool (command line)
• #Hot deployment (command line)

When you package your application you may include the deployment plan within the package or not. At deployment time, Geronimo will look for the geronimo-web.xml and web.xml deployment plans (or geronimo-application.xml or geronimo-application-client.xml depending the type of application) in the WEB-INF directory within you packaged application. If Geronimo can not find those descriptors it will attempt to deploy the application using defaults. If using defaults fails you will have to provide a deployment plan either repackaged in the application or providing an external deployment plan, in the following sections we will discuss further these alternatives.

Geronimo Administration Console

To install a new application via the Geronimo Administration Console the Install New Applications portlet is available by selecting Deploy New on the Console Navigation menu on the left hand side. This portlet also allows you to start automatically the application right after it was deployed.

For this example we will be using the simple JSP HelloWorld sample created in the Quick start - Apache Geronimo for the impatient section. In that section however we used the --inPlace deployment option, in other words we did not need to package the application into a WAR file. To create the WAR file type the following command from the <app_home> directory

jar -cvf HelloWorld.war *

This WAR already has included in the package the deployment plans.

Back in the Geronimo Administration Console, from the Install New Applications portlet click on Browse to specify the path to the HelloWorld.war in the Archive: section. Make sure the Start app after install checkbox is selected (by default is checked) and then click on Install.

You should see the " The application was successfully deployed. " and " The application was successfully started. " confirmation messages on the top of the portlet.

Another way to verify that the application has been successfully installed and started is by checking the Installed Web Applications portlet which is available by selecting Web App WARs on the Console Navigation menu on the left hand side. You should see the application listed as hello and with the status running.

Since the application we installed is HelloWold.WAR we use this portlet, when you install an EAR you would check the status using the Installed Application EARs portlet available by selecting Application EARs on the Console Navigation menu on the left hand side. The installation procedure is the same for both WAR and EAR applications.

To remove the applications through the Geronimo Administration Console you would use these two portlets, either the Installed Web Applications or the Installed Application EARs portlets depending on the application to uninstall.

For our example, access the Installed Web Applications portlet and click on Uninstall for the Component Name listing sample.applications/HelloWorldApp/2.0/war. This will stop the application first and then uninstall it. The confirmation message " Uninstalled application " should be listed at the bottom of the portlet.

These are the basic steps for installing and uninstalling applications via the Geronimo Administration Console, the following two sections will focus on the command line options.

Deployer tool

The deployer tool will allow you, among other things, install and uninstall applications via a command line. In this section we will focus on just these two tasks for the sample application, the remaining functionality is fully covered in the Deployer tool section.

To deploy the HelloWorld.war sample application using the Deployer tool open a command line window and type the following command from the <geronimo_home>\bin directory:

deploy --user system --password manager deploy <app_home>\HelloWorld.war

If your application does not include the Geronimo specific deployment plan in the WEB-INF directory you can still, just like with the Geronimo Administration Console, specify it externally. You just need to add to the previous command the path and file name of the deployment plan.

deploy --user system --password manager deploy <app_home>\HelloWorld.war <deployment_plan_home>\plan.xml

Note that when specifying the deployment plan externally you can use any file name to identify that plan, there is no need to use the geronimo-XYZ.xml form. In our example we do not need to specify any additional deployment plans as we have the Geronimo specific ones already included in the package.

Once deployed you should see a confirmation message similar to this one:

D:\geronimo-tomcat6-jee5-2.0-M2\bin>deploy --user system --password manager deploy \HelloWorld_2.0\HelloWorld.war
Using GERONIMO_BASE:   D:\geronimo-tomcat6-jee5-2.1
Using GERONIMO_HOME:   D:\geronimo-tomcat6-jee5-2.1
Using GERONIMO_TMPDIR: D:\geronimo-tomcat6-jee5-2.1\var\temp
Using JRE_HOME:        C:\Java\jdk1.5.0_06\\jre
    Deployed sample.applications/HelloWorldApp/2.0/war @
    http://hcunico:8080/hello

As a difference from the deployment via the Geronimo Administration Console, using the command line tool you receive more information in the confirmation message. For instance you receive the Component Name (a.k.a. moduleId) and you also receive the context root and port where the application was deployed. This is very useful when installing, testing and uninstalling several different applications where it would be hard to remember all these values.

Alternatively, if you have not yet packaged your application you could use the --inPlace option for deploying your application directly from the directory you are actually developing the application. This option is used to deploy this sample application in the [ Quick start - Apache Geronimo for the impatient] section.

In this case you would use this command from the <geronimo_home>\bin directory:

deploy --user system --password manager deploy --inPlace <app_home>

The Deployer tool can also be used to list all the installed applications. The list-modules command allows you to list all the applications, it also lets you narrow down the query by asking for just the started or stopped applications. The list-modules command without additional parameter will list by default all the started applications.

To uninstall an application you may want to list it first to get the right Component Name (or moduleId). Run the following command from the <geronimo_home>\bin directory:

deploy --user system --password manager list-modules

You will receive a list similar as the one shown in the following example.

D:\geronimo-tomcat6-jee5-2.0-M2\bin>deploy --user system --password manager list-modules
Using GERONIMO_BASE:   D:\geronimo-tomcat6-jee5-2.1
Using GERONIMO_HOME:   D:\geronimo-tomcat6-jee5-2.1
Using GERONIMO_TMPDIR: D:\geronimo-tomcat6-jee5-2.1\var\temp
Using JRE_HOME:        C:\Java\jdk1.5.0_06\\jre
Found 85 modules
  + org.apache.geronimo.configs/activemq-broker/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/activemq-ra/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/axis/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/axis-deployer/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/axis2/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/axis2-deployer/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/axis2-ejb/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/axis2-ejb-deployer/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/ca-helper-tomcat/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/client-deployer/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/clustering/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/connector-deployer/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/cxf/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/cxf-ejb/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/dojo-legacy-tomcat/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/dojo-tomcat/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/hot-deployer/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/j2ee-corba-yoko/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/j2ee-deployer/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/j2ee-server/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/jasper/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/jasper-deployer/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/javamail/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/jaxws-deployer/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/jaxws-ejb-deployer/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/jsr88-rar-configurer/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/mejb/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/myfaces/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/myfaces-deployer/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/openejb/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/openejb-corba-deployer/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/openejb-deployer/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/openjpa/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/persistence-jpa10-deployer/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/remote-deploy-tomcat/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/sharedlib/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/spring/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/system-database/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/tomcat6/2.1-SNAPSHOT/car
  + org.apache.geronimo.configs/tomcat6-clustering-builder-wadi/2.1-SNAPSHOT/car

Look for the sample.applications/HelloWorldApp/2.0/war entry, that is the value you will have to use when trying to uninstall the application.

To uninstall the application run the following command from the <geronimo_home>\bin directory using the Component Name you identified while listing the modules.

deploy --user system --password manager undeploy sample.applications/HelloWorldApp/2.0/war

This command will first stop the running application and then uninstall it. You should see a confirmation message similar to this:

D:\geronimo-tomcat6-jee5-2.0-M2\bin>deploy --user system --password manager undeploy sample.applications/HelloWorldApp/2.0/war
Using GERONIMO_BASE:   D:\geronimo-tomcat6-jee5-2.1
Using GERONIMO_HOME:   D:\geronimo-tomcat6-jee5-2.1
Using GERONIMO_TMPDIR: D:\geronimo-tomcat6-jee5-2.1\var\temp
Using JRE_HOME:        C:\Java\jdk1.5.0_06\\jre
    Module sample.applications/HelloWorldApp/2.0/war unloaded.
    Module sample.applications/HelloWorldApp/2.0/war uninstalled.

    Undeployed sample.applications/HelloWorldApp/2.0/war

In this example you have used the same tool with three different commands:

• deploy
• list-modules
• undeploy

These are not the only options and commands available for this tool, please visit the Tools and commands section for additional details.

Hot deployment

Apache Geronimo has support for Hot Deployment. This means that you can copy an application JAR file into the <geronimo_home>/deploy directory and the application will be deployed automatically. This will also work for uninstalling or refreshing applications previously deployed via this method. Alternatively, you may also copy the directory (unpacked) for the application module instead of copying a single JAR file.

Note that with this deployment method you have to include the deployment plan in the application package, this method does not support external deployment plans. Also note that applications deployed via the Deployer tool or the Geronimo Administration Console will not be listed in the <geronimo_home>/deploy directory.

When you copy an application in the deploy directory, let's say HelloWorld.war, you will see a confirmation message in the console where Geronimo is running stating the application was deployed and the context to access that application.

11:45:23,500 INFO  [DirectoryHotDeployer] Deploying HelloWorld.war
11:45:23,953 INFO  [DirectoryHotDeployer]     Deployed sample.applications/HelloWorldApp/2.0/war @
    http://hcunico:8080/hello

To remove the application, just delete the WAR or EAR file from the deploy directory. When the application has been removed you should see a confirmation message in the console where Geronimo is running stating the application was undeployed.

11:46:17,953 INFO  [DirectoryHotDeployer] Undeploying HelloWorld.war
11:46:18,281 INFO  [DirectoryMonitor] Hot deployer notified that an artifact was removed: sample.applications/HelloWorldApp/2.0/war
11:46:18,281 INFO  [DirectoryHotDeployer]     Undeployed sample.applications/HelloWorldApp/2.0/war

Summary

In this section we has discussed three different methods for installing and uninstalling applications, one graphical, one command line and for the hot deployment you can choose command line or the GUI of your choice. While considering you are using multiple Geronimo servers as a cluster, you can deploy applications to them at one shot by using clustered deployment. For more information of this task, see Farming using Deployment for the details.
You can visit the Tools and commands section as well for further details on the available options and parameters.