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.

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:

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.

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:

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 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>@app.name@</context-root>
    </web>
    <alt-dd>deployment/web.xml</alt-dd>
  </module>
</application>

<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.