geronimo-ra.xml

Understanding deployment plans

openejb-jar.xml

Overview

The Geronimo deployment plan for a Web application, which is usually packaged as a WAR file is called "geronimo-web.xml". The geronimo-web.xml deployment plan is used to in conjunction with the web.xml JAVA EE deplopyment plan to deploy web applications consisting of Java Servlet Pages (JSP) and servlets to the Geronimo application server, and optionally can be used to configure the Geronimo web server (i.e., Tomcat or Jetty) where the Web application is going to be deployed. The geronimo-web.xml deployment plan is an optional file, but is typically used when deploying a WAR file. It is used to specify the application security roles, ejb names, database resources, JMS resources, etc. declared in web.xml to corresponding entities deployed in the server. In addition to that, if there are any web container specific configurations, such as Tomcat or Jetty specific, depending on the application needs, all these settings are configured as well here. If the web application depends on any third party libraries or other services running in the server, all these dependencies are declared in the plan. Some web applications require class loading requirements different from the default class loading behavior. The geronimo-web.xml allows application deployer to configure this as well. There are many more configurations that could be done through geronimo-web.xml depending on the needs of web application.

Packaging

The geronimo-web.xml deployment plan can be packaged as follows:

1. Embedded in a WAR file. In this case, a geronimo-web.xml file must be placed in the /WEB-INF directory of the WAR, which is the same place where the web.xml file must be located.
2. Maintained separately from the WAR file. In this case, the path to the file must be provided to the appropriate Geronimo deployer (e.g., command-line or console). Note that in this case, the filename can be named something other than geronimo-web.xml but must adhere to the same schema.
3. Embedded in an enterprise application EAR file: In one case, the high-level element <web-app> can be embedded in the EAR file's geronimo-application.xml file.
4. Embedded in an enterprise application EAR file: In another case, the actual geronimo-web.xml file can be placed in the /META-INF directory of the EAR, which is the same location as the application.xml file.

Schema

The geronimo-web.xml deployment plan is defined by the geronimo-web-2.0.1.xsd schema located in the <geronimo_home>/schema/ subdirectory of the main Geronimo installation directory. The geronimo-web-2.0.1.xsd schema is briefly described here:

http://geronimo.apache.org/schemas-2.1/docs/geronimo-web-2.0.1.xsd.html

Top-level elements

The top-most element in the geronimo-web-2.0.1.xsd is <web-app> element. The top-level elements of the <web-app> element are described below:

<sys:environment>

The <sys:environment> elements use the Geronimo deployment namespace described at http://geronimo.apache.org/schemas-2.1/docs/geronimo-module-1.2.xsd.html. The <sys:environment> contains the following elements:

• The <moduleId> element is used to provid the configuration name for the web application as deployed in the Geronimo server. It contains elements for the groupId, artifactId, version and module type. Module IDs are normally printed with slashes between the four components, such as GroupID/ArtifactID/Version/Type.
• The <dependencies> element is used to provide the configurations and third party libraries on which the web module is dependent upon. These configurations and libraries are made available to the web module via the Geronimo classloader hierarchy.
• The <hidden-classes> element can be used to specify classes that are hidden from parent class loaders
• The <non-overridable-classes> element can be used to specify classes that are only loaded from parent class loaders
• The <inverse-classloading> element can be used to specify that standard classloader delegation should be reversed
• The <suppress-default-environment> element can be used to suppress inheritance of environment by module

An example geronimo-web.xml file is shown below using the <sys:environment> elements:

<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-2.0.1"
         xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.2">

    <sys:environment>

        <sys:moduleId>
            <sys:groupId>default</sys:groupId>
            <sys:artifactId>geronimo-web-6</sys:artifactId>
            <sys:version>1.0</sys:version>
            <sys:type>car</sys:type>
        </sys:moduleId>

        <sys:dependencies>
            <sys:dependency>
                <sys:groupId>org.apache.geronimo.configs</sys:groupId>
                <sys:artifactId>tomcat6</sys:artifactId>
                <sys:version>2.2-SNAPSHOT</sys:version>
                <sys:type>car</sys:type>
            </sys:dependency>

            <sys:dependency>
                <sys:groupId>default</sys:groupId>
                <sys:artifactId>geronimo-web-5</sys:artifactId>
                <sys:version>1.0</sys:version>
                <sys:type>car</sys:type>
            </sys:dependency>

            <sys:dependency>
                <sys:groupId>default</sys:groupId>
                <sys:artifactId>geronimo-web-4</sys:artifactId>
                <sys:version>1.0</sys:version>
                <sys:type>car</sys:type>
            </sys:dependency>

            <sys:dependency>
                <sys:groupId>default</sys:groupId>
                <sys:artifactId>geronimo-web-2</sys:artifactId>
                <sys:version>1.0</sys:version>
                <sys:type>car</sys:type>
            </sys:dependency>
        </sys:dependencies>

        <sys:hidden-classes/>
        <sys:non-overridable-classes/>
        <sys:inverse-classloading/>
        <sys:suppress-default-environment/>

    </sys:environment> 
   
</web-app>

<context-root>

The <context-root> uses the default namespaced described at

The XML elements used to provide the web context root of the web applications.

Specifies a context path to the deployed application. This context path appears in the URL used to address the application on a Geronimo server. By default, the application deploy module base name (without the extension) is used. Typically, this element is used in a WAR deployment.

<work-dir>

The <work-dir> uses the default namespaced described at

'This is the work directory that will be used by this application. For Jetty this will be relative to jetty home which is var/jetty by default. For Tomcat this will be relative to \"catalina.home\".

<naming:web-container>

The <work-dir> uses the default namespaced described at

<container-config>

The <context-root> uses the default namespaced described at

If you use the generic (geronimo-web-2.0.xsd) web application configuration, you can use these elements in the container-config element to configure Tomcat-specific behavior.

'Geronimo supports both Jetty and Tomcat web containers. This element is for a web application needs to take container specific settings. It can hold either a Tomcat element or a Jetty element or both.'

This element is reserved for the configuration of elements specific to the underlying Web-tier container. In Geronimo's case, this is either Jetty or Tomcat.

<naming:abstract-naming-entry>

<ejb-ref>

The <context-root> uses the default namespaced described at
'The element ejb-ref is used to map EJB references to EJB\'s in other applications using remote home and remote interface. The application which contains the EJB being referenced should either be in same EAR or should be included in dependency list of this application. Also note as the EJB\'s referenced are in a different JVM all the Client interfaces should also be included in current application.'

<ejb-local-ref>

The <context-root> uses the default namespaced described at
'The element ejb-local-ref is used to map EJB references to EJB\'s in other applications using local home and local interface. The application which contains the EJB being referenced should either be in same EAR or should be included in dependency list of this application. Also note as the EJB\'s referenced are in a different JVM all the Client interfaces should also be included in current application.'

<service-ref>

The <context-root> uses the default namespaced described at

'The element service-ref is used to map service references to service\'s in other applications. The application which contains the EJB being referenced should either be in same EAR or should be included in dependency list of this application.'

<resource-ref>

The <context-root> uses the default namespaced described at
'The element resource-ref is used to map resource references to resources\'s like JDBC resources, JMS resources, etc. configured outside the current application.'

<resource-env-ref>

The <context-root> uses the default namespaced described at
'The element resource-env-ref is used to map resource references to administrative objects deployed as a part of connectors.'

<naming:message-destination>

The <context-root> uses the default namespaced described at

References a message-destination (such as JMS queues), which is used within the deployed WAR file.

<security-realm-name>

The <context-root> uses the default namespaced described at

Specifies the name of the security realm that will be used for user authentication.

<app:security>

The <context-root> uses the default namespaced described at

Configures the security role mappings that will be used when deploying the module. Maps roles specified in the WAR file to roles or principals in the security realm

<sys:service>

The <context-root> uses the default namespaced described at

'Reference to abstract service element defined in imported \"geronimo-module-1.2.xsd\"'

<ee:persistence>

The <context-root> uses the default namespaced described at

default namespace is http://java.sun.com/xml/ns/javaee. The XML elements that do not have a namespace prefix belong to the default namespace.

Samples