To provide specific handling instructions to the Geronimo server during deployment of a code module, you must include deployment descriptors and deployment plans.
Deployment descriptors and deployment plans are both XML documents, with well-defined syntax, enforced by XML schemas. All of the schemas for Geronimo deployment descriptors and deployment plans are stored in the schema subdirectory of the Geronimo distribution.
Deployment descriptors are in a format specified by the J2EE specifications and are mandatory for compliance. Deployment descriptors are always included as part of the deployed archive.
Deployment plans are in a Geronimo-specific format and are optional when deploying modules. The deployment plan provides additional instructions to the Geronimo server, above and beyond those in the standard deployment descriptor. More specifically, additional information can be provided for the following:
External resource references
Security configuration
Mapping or remapping referenced resource names
Access an external EJB, not deployed with the module
Dependency on classes not located via J2EE-specified class loader hierarchy
Configuration of a JCA resource adapter in the module
The different software components that can be deployed in Geronimo include the following:
Web-tier applications, with JSP, servlets, JSP tags, tag libraries, framework coding, and so on
Business-tier EJBs in JAR bundles
Enterprise applications combining both a business-tier EJB JAR and a Web-tier application WAR
Connector resources such as JDBC drivers or JMS connection factories
Client applications that make use of Geronimo’s client application container
Each of these software components must be bundled in an archive (JAR file) before deployment into Geronimo. For all the J2EE components, a mandatory J2EE deployment descriptor must be included in the archive.
Table 9-1 shows all the standard mandatory J2EE deployment descriptors for the deployable software components listed in the preceding section. For each type of component, the type of archive file, and the location plus name of the standard J2EE deployment descriptor are shown.
Descriptor Deployable | Archive File | Standard J2EE Deployment and Location |
---|---|---|
Web-tier application (servlet, JSP, JSP tags, frameworks) | WAR | WEB-INF/web.xml |
Business-tier EJB bundle | JAR | META-INF/ejb-jar.xml |
Enterprise applications (containing both WAR and EJB JARs) | EAR | META-INF/application.xml |
J2EE client application | JAR | META-INF/application-client.xml |
JCA resource adapters (usually JDBC drivers or JMS connection factories) | RAR | META-INF/ra.xml |
All of the deployment descriptors shown in Table 9-1 are mandatory. If you do not have a correctly formatted deployment descriptor at the specified location within the archive, deployment will fail.
The deployment descriptors are XML files, and their syntax is specified in XML schemas. Each XML schema precisely describes and enforces the syntax of each of these descriptors.
Table 9-2 shows the schema for each of the J2EE deployment descriptors. Later chapters will cover the tags and elements contained in these deployment descriptors. Table 9-2 also has a chapter reference, showing where you can find more information on the use of each of the descriptors.
J2EE Deployment Descriptor | XML Schema | Chapter Reference |
---|---|---|
web.xml | web-app_2_4.xsd web-app_2_3.dtd web-app_2_2.dtd | Chapters 10,11 |
ejb-jar.xml | ejb-jar_2_1.xsd ejb-jar_2_0.dtd ejb-jar_1_1.dtd | Chapter 12 |
application.xml | application_1_4.xsd application_1_3.dtd application_1_2.dtd | Chapters 10,11,12 |
application-client.xml | application-client_1_4.xsd application-client_1_3.dtd application-client_1_2.dtd | Chapter 12 |
ra.xml | connector_1_5.xsd connector_1_0.xsd connector_1_0.dtd | Chapters 13,16 |
Unlike J2EE deployment descriptors, Geronimo-specific deployment plans are optional when deploying modules into Geronimo. However, unless you are working with very simple application or deployment scenario, you will likely need to create a custom deployment plan.
These deployment plans can either be embedded within the deployed module (typically besides the J2EE deployment descriptor that it extends) can exist externally (completely independent from the deployed module, and only used in conjunction with the module during deployment).
When a deployment plan is embedded inside the module, it must have the name specified in the Table 9-3. However, if you are using an external deployment plan, it can have any name you want.
Deployable | Archive File | Geronimo Specific Deployment Plan |
---|---|---|
Web-tier application (servlet, JSP, JSP tags, frameworks) | WAR | WEB-INF/geronimo-web.xml |
Business-tier EJB bundle | JAR | META-INF/openejb-jar.xml |
Enterprise applications (containing both WAR and EJB JARs) | EAR | META-INF/geronimo-application.xml |
J2EE client application | JAR | META-INF/geronimo-application-client.xml |
JCA resource adapters (usually JDBC drivers or JMS connection factories) | RAR | META-INF/geronimo-ra.xml |
The following are some best-practice guidelines to consider when determining whether you should place the plan internal to the module or keep it as an external plan.
An internal plan is distributed with the archive but is not easy to modify. An external plan is easier to modify but must be managed with its associated archive file and is an additional piece that must be distributed (and specified during deployment). This complicates the distribution and deployment process.
The tradeoff, therefore, is flexibility in configuration versus distribution and deployment simplicity.
In general, internal plans are better for the following:
Situations where you must deploy the same module to a large number of targets with the same configuration
Situations where you need maximum flexibility in configuration (such as where you are deploying to a small number of different targets, each requiring some changes in the deployment plan)
Figure 9-1 illustrates the possible locations of the deployment plans.
Figure 9-1: Deployment descriptors and deployment plans for modules’ deployment
In Figure 9-1, the two possible locations for a deployment plan are shown. You can use either location when you’re deploying the module using the Web console or the command-line deployment tool.
When you are placing the deployment plans inside a module, they must be placed in specific locations and have specific names for Geronimo to find them. Table 9-3 shows the name that an internally located deployment plans must have.
Each of the plans in Table 9-3 is an XML document with well-defined contents. The possible contents are restricted and enforced by XML schema files. Table 9-4 enumerates the deployment plans and the XML schema associated with each. You can find all of the schema under the schema directory within the Geronimo distribution.
J2EE Deployment Descriptor | XML Schema | Chapter Reference |
---|---|---|
web.xml | geronimo-web-1.1.xsd | Chapters 10,11 |
ejb-jar.xml | openejb-jar-2.1.xsd | Chapter 12 |
application.xml | geronimo-application-1.1.xsd | Chapters 10,11,12 |
application-client.xml | geronimo-application-client-1.1.xsd | Chapter 12 |
ra.xml | geronimo-connector-1.1.xsd | Chapters 13,16 |
If you are using an external deployment plan when deploying a module, you can name the plan whatever you like. In fact, you will specify the name of the plan to use during deployment.
In the case where there is already an embedded plan in a module, Geronimo will always allow you to override the internal plan with an external deployment plan. This is often useful in repurposing a module without removing the embedded plan in the archive.