10.3. Geronimo Deployment Plans

A Geronimo deployment plan is typically much like a J2EE deployment descriptor. It is an XML file, based on XML Schemas, which holds configuration information related to the application module or service.

Each of the subsequent chapters in Part III, “J2EE Applications on Geronimo” describes one of the module types, and covers the deployment plan for that module type in detail.

10.3.1. Necessity of Deployment Plans

In some cases, a Geronimo deployment plan is not strictly required for an application module. For example, it might not be needed for a web application with no security or resource references, where you're happy with the default context root and dependencies. However, this tends to be the case only for trivial application modules; most web, client, and EJB modules have security or resource references that must be resolved, and most connectors require detailed configuration. An enterprise application EAR is most likely to not need Geronimo settings, though it's often useful to at least specify some dependencies and a configuration name there.

The bottom line is that it's always recommended that you use a Geronimo deployment plan for every application module, even if you think it may not be absolutely necessary in the case of a particular module.

In the case of Geronimo services, a deployment plan is required.

10.3.2. Deployment Plan File Names & Packaging

There are actually three ways to manage Geronimo deployment plans, though only the first is available for Geronimo services. These are described in the following sections.

10.3.2.1. External Deployment Plans

The recommended way to manage Geronimo deployment plans is to keep them separate from the application or service archive. For example, in the case of a web application WAR file, you might maintain one .war file containing the web application, and one .xml file containing the Geronimo deployment plan for the web application. In this case, there are no particular naming requirements for the Geronimo deployment plans. When you deploy the web application, you can pass both the module archive and the deployment plan to the deploy tool. For example:

java -jar bin/deployer.jar deploy web-app.war web-app-plan.xml

In the case of a Geronimo service, you may not have a module at all; if the necessary libraries are included in the Geronimo repository, a plan alone may be enough to deploy the service:

java -jar bin/deployer.jar deploy new-service-plan.xml

The one complexity to maintaining deployment plans outside the archive comes with enterprise applications (EARs). There is only a single deployment plan allowed for an EAR, and it must somehow encapsulate the deployment information for the EAR itself as well as for all the modules contained within the EAR. To handle this, the EAR deployment plan can actually contain the deployment plans for other modules -- this is described in more details in Section 15.3.2, “Configuring Application Modules”. In cases like this, it may be most convenient to use a JSR-88 configuration tool to load and edit the deployment information for the entire application.

10.3.2.2. Internal Deployment Plans

The traditional alternative to external deployment plans is to actually package each Geronimo deployment plan into the application module, just like the J2EE deployment descriptors. In this case, each Geronimo deployment plan has a specific required name:

Table 10.2. Geronimo Deployment Plan File Names

Module TypeDeployment Plan File
Web ApplicationWEB-INF/geronimo-web.xml
EJB JARMETA-INF/openejb-jar.xml
J2EE ConnectorMETA-INF/geronimo-ra.xml
Client ApplicationMETA-INF/geronimo-application-client.xml
Enterprise ApplicationMETA-INF/geronimo-application.xml

If the Geronimo deployment plan is packaged in the application module, the module can be deployed without a separate plan:

java -jar bin/deployer.jar deploy web-app.war

This option is not available for Geronimo services.

10.3.2.3. EAR Deployment Plans

Just like the way J2EE deployment descriptors for application modules can be packaged in an EAR but outside the modules, Geronimo deployment plans can be packaged in an EAR but outside the modules. For example, an EAR containing an EJB JAR and a web application WAR might look like this:

Example 10.2. EAR with Deployment Information Outside the Modules

EAR Contents

some-application.ear
    some-web-app.war
    some-ejbs.jar
    deployment/
        web.xml
        ejb-jar.xml
        geronimo-web.xml
        openejb-jar.xml
    META-INF/
        application.xml
        geronimo-application.xml

application.xml

<application xmlns="http://java.sun.com/xml/ns/j2ee"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
                http://java.sun.com/xml/ns/j2ee/application_1_4.xsd"
              version="1.4">
  <module>
    <ejb>some-ejbs.jar</ejb>
    <alt-dd>deployment/ejb-jar.xml</alt-dd>
  </module>
  <module>
    <web>
      <web-uri>some-web-app.war</web-uri>
      <context-root>@[email protected]</context-root>
    </web>
    <alt-dd>deployment/web.xml</alt-dd>
  </module>
</application>

geronimo-application.xml

<application
    xmlns="http://geronimo.apache.org/xml/ns/j2ee/application-1.0"
    configId="MyConfigName"
    parentId="ParentConfigName">
  <module>
    <web>some-web-app.war</web>
    <alt-dd>deployment/geronimo-web.xml</alt-dd>
  </module>
  <module>
    <ejb>some-ejbs.jar</ejb>
    <alt-dd>deployment/openejb-jar.xml</alt-dd>
  </module>
</application>

In Example 10.2, “EAR with Deployment Information Outside the Modules”, the EAR deployment descriptor and Geronimo deployment plan are packaged in the usual locations in META-INF/. However, the deployment descriptors and deployment plans for the EJB and web modules are all stored in the deployment/ directory of the EAR, instead of in the JAR or WAR. This is managed with the alt-dd elements. The alt-dd elements in application.xml give alternate locations for the J2EE deployment descriptors, while the alt-dd elements in geronimo-application.xml give alternate locations for the Geronimo deployment plans.

This option is not available for Geronimo services.