Configuring and administering

Documentation

Developing

Every module that you install in Geronimo, whether it is a service, application, resource, and so on, can be configured via a deployment plan. These deployment plans are XML files based on XML Schemas containing the configuration details for a specific application module or component. The Java EE 5 specification defines standard deployment descriptors such as web.xml, application.xml, and so on. In some cases, the deployment descriptor is all that is required to install a module into a Geronimo server. However, in many cases, server-specific configuration is required when modules are installed. This server-specific configuration is accomplished by using Geronimo deployment plans.

Geronimo deployment plans can be packaged along with the application or specified externally at deployment time. If provided during deployment, this plan will overwrite any other Geronimo specific deployment plan provided with the application.

To package the deployment plans in you application you have to follow some naming conventions and place the file in a specific directory within your packaged application. For example, in a Web application you would include the geronimo-web.xml under the /WEB-INF directory, same place where you are also providing the web.xml descriptor, all within the WAR. For an enterprise application you would include the geronimo-application.xml under the /META-INF directory, same place where you are also providing the application.xml descriptor, all within the WAR.

The Java EE 5 specification also lets you use Annotations where you add resource references, dependencies and so on, directly in the code. Geronimo provides a Creating deployment plans using the deployment plan wizard that automatically generates the necessary deployment plans based on the standard deployment descriptors and annotations.

This section provides a guide for creating deployment plans, in which Geronimo-specific configuration is accomplished via resource reference, dependencies and so on. It is organized in the following parts:

The Deployment framework

Geronimo 2.2 provides a common deployment framework for managing assets on your server. An asset may be

• Web applications with servlets and JavaServer Pages (JSPs)
• Java EE Enterprise Java Beans (EJBs)
• Java EE enterprise applications
• Java EE connectors
• Java EE application clients
• GBean services.

Except for GBean services, these assets must be developed and packaged according to the Java EE specifications. These specifications define XML documents, called deployment descriptors, that provide configuration information for the asset as well as defining relationships to other components. See the reference site for more deployment descriptor schema information.

Deployment descriptors are necessary but are not always sufficient to deploy an asset on your server. In most cases, additional information must be provided to map each asset to the application server and a given server's configuration. In these cases, deployment plans provide the information.

Deployment plans

Like deployment descriptors, deployment plans are XML documents, defined by XML schemas, that hold configuration information needed to deploy an asset. Deployment plans can be kept as a separate file, outside of the Java EE module and easily edited, or it can be included in the package where it is more convenient to use but more difficult to modify. When kept as a separate file, the plan can have any name. When included in the module, the plan is required to have a specific name. In both cases, the schema is the same and can be found in <GERONIMO_HOME>/schema where <GERONIMO_HOME> is the server's installation directory.

GBean services are not Java EE assets and are not associated with a Java EE module or a deployment descriptor. The schema for the deployment plan is unique to the service, even if it is a replaceable service with common interfaces, and defined by the service developer. Before a service can be deployed, the JAR file that contains the classes that implement the service must be placed in the server's repository and the schema for its deployment plan must be placed in the server's schema library.

Deploying without a deployment plan

If you want to deploy a Java EE asset without a deployment plan, the server will perform the operation with default values.

• If your asset is very simple, for example, just servlets and JSPs that require no security and do not access any external resources, you can deploy without a deployment plan.
• If the asset developers have carefully crafted their asset so that the required resource names precisely match the names configured in your server, you can deploy without a deployment plan.

This option might be convenient if you are deploying samples, migrating simple assets intended for other application servers, or working with assets under development, but it is typically worthwhile to take a broader view. Successful assets do not always stay simple and you need to provide a deployment plan when your asset

• Needs to be served from an explicit context
• Depends on external Java libraries not included in the default classpath
• Uses security roles or a security realm other than the system default realm
• References a resource (a data source, a message queue, a connector) that must be matched to the server's configuration
• Uses an external EJB
• Implements a connector that requires configuration.

Even if you believe that a deployment plan might not be necessary for a particular Java EE asset, consider providing a deployment plan so that your plans and procedures include it. This will simplify your effort when the asset is enhanced to the point where a deployment plan is required.

Choosing a deployment plan packaging option

Deployment plans can be packaged as a file within your Java EE asset's archive or as a separate file. To choose between these options consider the following trade-offs.

• If you place the plan within the archive, you simplify the effort required to distribute and deploy the asset. Users have only one file to manage and one file name to enter during a deploy operation. On the other hand, if the users need to modify the plan, they must extract the archive, make their changes, and rebuild the archive before they can deploy the asset.
• If you package the deployment plan as a separate file, you simplify the effort to modify the plan to match the users' particular server configuration. On the other hand, the users must manage two files, the archive and the deployment plan, and specify both when they deploy the asset.

If you are distributing the asset to a collection of users where the server configurations are identical and well known, packaging the deployment plan in the archive is preferred. If you are distributing the asset to a collection of users where server configurations are varied and unknown, the plan will need to be modified and an external plan is preferred.

If you choose to package your deployment plan within the archive, you must give the file a required name and place it in a required location. See the next section for details.