Deployment Descriptors and Plans


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 Geronimo Deployable Modules

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.

Standard J2EE Deployment Descriptors

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.

Table 9-1: Standard J2EE Deployment Descriptors
Open table as spreadsheet

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.

Table 9-2: XML Schema for Each of the J2EE Deployment Descriptors
Open table as spreadsheet

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

Deployment Plans Naming

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.

Table 9-3: Location and Name of Plans Placed Inside Deployed Module
Open table as spreadsheet

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.

image from book
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.

Deployment Plan Internal to the Module

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.

Table 9-4: XML Schema for Geronimo-Specific Deployment Plans
Open table as spreadsheet

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.




Professional Apache Geronimo
Professional Apache Geronimo (Wrox Professional Guides)
ISBN: 0471785431
EAN: 2147483647
Year: 2004
Pages: 148

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net