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.

	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:

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.

<?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>

<?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.4, “Web Application Deployment Descriptor: Schema vs. DTD”, several things are apparent:

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.6, “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.

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

<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.1"
    xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.1"
    xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.1">
    <sys:environment>
        <sys:moduleId>
            <sys:artifactId>MyWebApp</sys:artifactId>
            <sys:version>1.2</sys:version>
        </sys:moduleId>
        <sys:dependencies>
            <sys:dependency>
                <sys:artifactId>MyEJBJar</sys:artifactId>
                <sys:type>jar</sys:type>
            </sys:dependency>
        </sys:dependencies>
    </sys:environment>

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

Namespaces can also be set on elements other than the first, and then they apply to everything inside that element. For example, here is the same plan as above, without using prefixes:

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

<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.1">
    <environment
      xmlns="http://geronimo.apache.org/xml/ns/deployment-1.1">
        <moduleId>
            <artifactId>MyWebApp</artifactId>
            <version>1.2</version>
        </moduleId>
        <dependencies>
            <dependency>
                <artifactId>MyEJBJar</artifactId>
                <type>jar</type>
            </dependency>
        </dependencies>
    </environment>

    <context-root>/MyWebApp</context-root>
    <context-priority-classloader>
      true
    </context-priority-classloader>

    <resource-ref
      xmlns="http://geronimo.apache.org/xml/ns/naming-1.1">
        <ref-name>jdbc/DataSource</ref-name>
        <resource-link>
          DefaultDatasource
        </resource-link>
    </resource-ref>
</web-app>

Tip

When writing Geronimo deployment plans, you can omit the declarations and prefixes for the nested namespaces. In Example 4.5, “Nested Schema Prefixes in a Geronimo Deployment Plan”, for example, all the naming: and sys: 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 declarations or prefixes, as most XML tools or IDEs that support J2EE 1.4 can validate the structure of the properly-formatted deployment plan.

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

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:

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.

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

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.1)] 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.1)] has full details on configuring and deploying a JMS Server and JMS resources.

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 [DRAFT (1.1)] 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.1">
  <environment>
    <moduleId>
      <artifactId>Scheduler</artifactId>
    </moduleId>
    <dependencies>
      <dependency>
        <groupId>SomeProvider</groupId>
        <artifactId>SomeScheduler</artifactId>
        <type>jar</type>
      </dependency>
    </dependencies>
  </environment>

  <gbean name="Scheduler" class="com.example.SchedulerGBean">
    <attribute name="schdeulerDataStore">
      MySchedulerDatabase
    </attribute>
  </gbean>  
</deployment>

To deploy the scheduler with the deploy tool, you could use a command like this (assuming the GBeans and other necessary code was included in the JAR listed as a dependency):

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