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.
In the case of Geronimo services, the Geronimo deployment plan contains all the configuration information for the service.
In the case of an application module, the J2EE deployment descriptor contains much of the basic configuration information, such as what resources the application requires, what security roles it needs, and so on. However, it doesn't contain any information specific to the application server, or the specific server configuration. So while it might indicate that the application needs a database or a security role, it doesn't indicate which database, or which users should have that security role. The Geronimo deployment plan contains that configuration-specific information, as well as options for Geronimo-specific features such as CMP table mapping and more.
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.
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.
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.
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:
Table 10.2. Geronimo Deployment Plan File Names
|Module Type||Deployment Plan File|
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:
Example 10.2. EAR with Deployment Information Outside the Modules
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>@[email protected]</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.