4.3. Introduction to Deployment

4.3.1. XML Schema and Geronimo Deployment Plans

Every service, application, or resource in Geronimo is configured with an XML deployment plan. For application modules, there's typically one standard J2EE deployment descriptor (such as WEB-INF/web.xml or META-INF/ejb-jar.xml) and one Geronimo deployment plan (such as WEB-INF/geronimo-web.xml or META-INF/openejb-jar.xml). In some cases (particularly for simple application modules in an EAR) the default values are sufficient, in which case no Geronimo deployment plan actually needs to be present. However, this tends to be the exception rather than the rule.

[Tip]Tip

You may be used to thinking of the Geronimo deployment plan as a "server-specific deployment descriptor". However, J2EE 1.4 and the J2EE Application Deployment specification introduced the term "deployment plan" to refer to this, and Geronimo has adopted that terminology.

A Geronimo deployment plan contains configuration information such as:

  • A name for the configuration, and the name of its parent configuration

  • Service-specific information for GBeans, like the listen port for the web container or the transaction timeout for the transaction manager

  • Which server resource should satisfy each resource reference declared by an application module

  • How to map CMP entity beans to a specific database

Like the J2EE deployment descriptors in J2EE 1.4, Geronimo deployment plans are defined by XML Schemas (as opposed to DTDs). Schemas are more flexible than DTDs, and can provide more validation than DTDs (for example, by identifying values that should be numeric). While the basic XML file structure is unchanged, the header of an XML document controlled by a Schema looks slightly different than a similar document controlled by a DTD.

Example 4.3. Web Application Deployment Descriptor: Schema vs. DTD

Here's a typical J2EE 1.3 web application deployment descriptor (WEB-INF/web.xml) based on a DTD:

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE web-app
  PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
  "http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>
  ...
</web-app>

Here's the same for J2EE 1.4, based on a Schema:

<?xml version="1.0" encoding="ISO-8859-1"?>

<web-app 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/web-app_2_4.xsd"
         version="2.4">
  ...
</web-app>

Looking at Example 4.3, “Web Application Deployment Descriptor: Schema vs. DTD”, several things are apparent:

  • The extra information is provided within the first element, instead of before it

  • The document type is identified by an XML namespace (the xmlns attribute) instead of by a URI (the bit starting with -//Sun...)

  • You still provide a URL pointing to the schema like you did for the DTD, but now it's provided by the xsi:schemaLocation attribute (which takes a namespace and then a URL for that namespace)

Like packages in Java, namespaces in XML are a way to separate XML element definitions by content area, or to avoid collisions between vendors who might use the same names for their elements. For example, all the J2EE elements are defined in the namespace http://java.sun.com/xml/ns/j2ee while Geronimo elements are in several namespaces, generally of the form http://geronimo.apache.org/xml/ns/... (there are separate namespaces for each Geronimo deployment plan type).

In many cases each XML file is controlled by a single Schema covering a single namespace. However, it's also possible to build a document including content from several namespaces -- typically one or more namespaces containing shared content, and a single namespace specific to the document in question. In that case, an element might declare a new prefix and indicate what namespace that prefix identifies. The element itself or any content within that element that uses the same prefix would be controlled by the Schema that defines the namespace for that prefix (see Example 4.4, “Nested Schemas in a Geronimo Deployment Plan”). Geronimo deployment plans sometimes use this, when common elements defined in a common schema are used in module-specific deployment plans.

Example 4.4. Nested Schemas in a Geronimo Deployment Plan

In this example, a Geronimo web deployment plan (WEB-INF/geronimo-web.xml) uses some elements from the common Geronimo naming schema:

<?xml version="1.0" encoding="ISO-8859-1"?>

<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.0"
         xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.0"
         configId="MyWebApp"
         parentId="MyEJBJar">
    <context-root>/MyWebApp</context-root>
    <context-priority-classloader>
      true
    </context-priority-classloader>
    <naming:resource-ref>
        <naming:ref-name>jdbc/DataSource</naming:ref-name>
        <naming:resource-link>
          DefaultDatasource
        </naming:resource-link>
    </naming:resource-ref>
</web-app>

The elements with no prefix are from the namespace http://geronimo.apache.org/xml/ns/j2ee/web-1.0, while the elements with the naming: prefix are from the namespace http://geronimo.apache.org/xml/ns/naming-1.0. Both namespaces are identified in the web-app header (which makes them available anywhere within the document), though the naming: namespace could also have been declared on the naming:resource-ref element (in which case it would be available only to that element and its children).

[Tip]Tip

When writing Geronimo deployment plans, you can omit the prefixes for the nested namespaces. In Example 4.4, “Nested Schemas in a Geronimo Deployment Plan”, for example, all the naming: prefixes could have been omitted. This can be useful when writing deployment plans by hand, and Geronimo will accept the plans using that syntax. However it is not actually valid XML. Therefore it's often better to use the proper namespace prefixes, as most XML tools or IDEs that support J2EE 1.4 can validate the structure of the properly-formatted deployment plan.

4.3.2. Deploying J2EE Application Modules

Geronimo can deploy any J2EE application module, either on its own or packaged into a J2EE application, including:

  • Web Applications (WAR modules)

  • EJBs (EJB JAR modules)

  • J2EE Connectors (RAR modules)

  • Client Applications (Client JAR modules)

  • Enterprise Applications (EAR modules)

Each module includes a standard J2EE deployment descriptor, packaged into the module. In order to deploy a J2EE module in Geronimo, you typically need to provide a Geronimo deployment plan in addition. A Geronimo deployment plan can be provided in two ways:

  • Packaged into the module, like the J2EE deployment descriptor

  • Provided separately to the deployment tool

Table 4.1, “Geronimo Deployment Plan File Names” summarizes the file names that should be used if a Geronimo deployment plan is packaged into a J2EE application module.

Table 4.1. Geronimo Deployment Plan File Names

Module TypeDeployment Plan File
Web ApplicationWEB-INF/geronimo-web.xml
EJB JARMETA-INF/openejb-jar.xml
J2EE ConnectorMETA-INF/geronimo-ra.xml
Client ApplicationMETA-INF/geronimo-application-client.xml
Enterprise ApplicationMETA-INF/geronimo-application.xml

To deploy an application module with a deployment plan packaged in the module (in this case, WEB-INF/geronimo-web.xml), you could use a command like this:

java -jar bin/deployer.jar deploy mywebapp.war

To deploy the same with the deployment plan in a separate file (in this case mywebapp-plan.xml) you could use a command like this:

java -jar bin/deployer.jar deploy mywebapp.war \
       mywebapp-plan.xml

For more information on deployment options and what goes into the Geronimo deployment plan for each module, see Part III, “J2EE Applications on Geronimo”.

4.3.3. Deploying JDBC and JMS Resources

JDBC resources are implemented using a J2EE Connector, which means they are configured and deployed like any other application components. The Connector for a database connection pool can be deployed as a top-level module in the server, or included within an application EAR. Chapter 6, Database Configuration [DRAFT (1.0-pre)] has full details on configuring and deploying JDBC connection pools.

JMS resources are slightly different. A JMS Server must be running for any JMS resources to work. The JMS Server is implemented using GBeans, so it is configured and deployed like a custom service. Geronimo includes a configuration for a default JMS Server, so usually you can just leave that active and you don't need to worry about customizing GBeans.

JMS application resources like connection factories, topics, and queues are implementing using a J2EE Connector, which can be configured and deployed like any other application component, with the restriction that it depends on a running JMS Server. The Connector for JMS resources can be deployed as a top-level modules in the server, or included within an application EAR.

Chapter 7, JMS Configuration [DRAFT (1.0)] has full details on configuring and deploying a JMS Server and JMS resources.

4.3.4. Deploying GBeans

Every service in Geronimo is deployed as a group of one or more GBeans. Typically, it is not necessary to customize or deploy any GBeans in order to run a J2EE application (Geronimo automatically creates GBeans for the application components, and you don't normally need to add any custom GBeans to an application). However, you might deploy custom GBeans to add new services to Geronimo. For example, you could deploy a GBeans that runs a more advanced scheduler than the EJB timer service. Chapter 18, GBeans: Adding New Services to Geronimo [EMPTY] describes how to construct GBeans to add new services to Geronimo.

In addition to deploying new services, it is also possible to reconfigure some of the basic GBeans provided with Geronimo. For example, Section 7.5.2, “Message Broker GBean Configuration” shows how to deploy a JMS Server with a nonstandard configuration.

Deploying GBeans involves creating a Geronimo deployment plan just like anything else you might deploy. For example, a deployment plan to add a scheduler might look like this:

scheduler-plan.xml

<deployment xmlns="http://geronimo.apache.org/xml/ns/deployment-1.0"
            configId="Scheduler">
  <dependency>
    <uri>scheduler/scheduler/1.5/jar</uri>
  </dependency>

  <gbean name="geronimo.server:type=Scheduler"
         class="com.example.SchedulerGBean">
    <attribute name="configDB" type="java.lang.String">
      MySchedulerDatabase
    </attribute>
  </gbean>  
</deployment>

To deploy the scheduler with the deploy tool, you could use a command like this:

java -jar bin/deployer.jar deploy scheduler-plan.xml