geronimo-ra.xml

Understanding deployment plans

openejb-jar.xml

Overview

The Geronimo-specific 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 requirements of web application.

Packaging

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

1. Embedded in a WAR file. In this case, the 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) when the WAR file is deployed. Note that in this case, the filename may be named something other than geronimo-web.xml but must adhere to the same schema. Also note that this will not work if the EJB JAR file is to be embedded in an enterprise application EAR file (see below).
   
   
3. Embedded in an enterprise application EAR file: In one case, the high-level element <web-app> can be embedded outside the WAR file 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 documented here:

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

Schema top-level elements

The root XML element in the geronimo-web-2.0.1.xsd schema is the <web-app> element. The top-level XML elements of the <web-app> root element are described in the sections below. The deployment plan should always use the Web application namespace, and it typically requires elements from the Geronimo Naming, Geronimo Security, and Geronimo System namespaces. Additionally, it has a required attribute to identify its configuration name, and an optional attribute to select a parent configuration. A typical deployment for geronimo-web.xml can be presented as follows:

<web: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" 
             xmlns:name="http://geronimo.apache.org/xml/ns/naming-1.2" 
             xmlns:app="http://geronimo.apache.org/xml/ns/j2ee/application-2.0" 
             xmlns:sec="http://geronimo.apache.org/xml/ns/security-2.0" 
             xmlns:pers="http://java.sun.com/xml/ns/persistence">
             ...
</web:web-app>

<sys:environment>

The <sys:environment> XML element uses the Geronimo System namespace, which is used to specify the common elements for common libraries and module-scoped services, and is described at http://geronimo.apache.org/schemas-2.1/docs/geronimo-module-1.2.xsd.html. The <sys:environment> element contains the following elements:

• The <moduleId> element is used to provide 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 a list of classes which will never be loaded from parent ClassLoaders of this module. For example, if Log4J was listed here, the module would never see Geronimo's copy of Log4J. If the module provided it's own Log4J JAR it would use that, otherwise it would not be able to load Log4J at all.
  
  
• The <non-overridable-classes> element can be used to specify a list of classes which will only be loaded from parent ClassLoaders of this module (never from the module's own ClassLoader). For example, this is used to prevent a web application from redefining "javax.servlet", so those classes will always be loaded from the server instead of from the web application's own ClassPath.
  
  
• The <inverse-classloading> element can be used to specify that standard classloader delegation is to be reversed for this module.
  
  
• The <suppress-default-environment> element can be used to suppress inheritance of environment by module (i.e., any default environment built by a Geronimo builder when deploying the plan will be suppressed).

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

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

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

<context-root>

The <context-root> XML element uses the Geronimo default namespace for a geronimo-web.xml file that is described at http://geronimo.apache.org/schemas-2.1/docs/geronimo-web-2.0.1.xsd.html. This element can be used to provide the web context path of the deployed web application, which appears in the URL used to address the application on a Geronimo server.

<work-dir>

The <work-dir> XML element uses the Geronimo default namespace for a geronimo-web.xml file that is described at http://geronimo.apache.org/schemas-2.1/docs/geronimo-web-2.0.1.xsd.html. This element can be used to provide the work directory that will be used by this web application. For Jetty this will be relative to jetty home which is var/jetty by default, and for Tomcat this will be relative to catalina.home.

<naming:web-container>

The <naming:web-container> XML element uses the Geronimo Naming namespace, which is used to identify the common elements for
resolving EJB references, resource references, and Web services references, and is described at http://geronimo.apache.org/schemas-2.1/docs/geronimo-naming-1.2.xsd.html. It is used to specify a reference to a web-container specific GBean either via a pattern or via a link to a GBean. An example geronimo-web.xml file is shown below using the <naming:web-container> elements:

<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-2.0.1"
         xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.2"
         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:dependencies>

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

    </sys:environment> 

    <context-root>contextroot</web:context-root>

    <work-dir>workdir</web:work-dir>   

    <naming:web-container>
        <naming:pattern>
            <naming:groupId>gbeanlocator-pattern-groupid</naming:groupId>
            <naming:artifactId>gbeanlocator-pattern-artifactid</naming:artifactId>
            <naming:version>gbeanlocator-pattern-version</naming:version>
            <naming:module>gbeanlocator-pattern-module</naming:module>
            <naming:name>gbeanlocator-pattern-name</naming:name>
        </naming:pattern>
        <naming:gbean-link>gbeanlocator-gbeanlink</naming:gbean-link>
    </naming:web-container>

</web-app>

<container-config>

The <container-config> XML element uses the Geronimo default namespace for a geronimo-web.xml file that is described at http://geronimo.apache.org/schemas-2.1/docs/geronimo-web-2.0.1.xsd.html. This element is used for the configuration of elements specific to the underlying Geronimo web container (i.e., Jetty or Tomcat). An example geronimo-web.xml file is shown below using the <container-config> elements for the Tomcat web container:

<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-2.0.1"
         xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.2"
         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:dependencies>

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

    </sys:environment> 

    <context-root>contextroot</web:context-root>

    <work-dir>workdir</web:work-dir>   

    <naming:web-container>
        <naming:pattern>
            <naming:groupId>gbeanlocator-pattern-groupid</naming:groupId>
            <naming:artifactId>gbeanlocator-pattern-artifactid</naming:artifactId>
            <naming:version>gbeanlocator-pattern-version</naming:version>
            <naming:module>gbeanlocator-pattern-module</naming:module>
            <naming:name>gbeanlocator-pattern-name</naming:name>
        </naming:pattern>
        <naming:gbean-link>gbeanlocator-gbeanlink</naming:gbean-link>
    </naming:web-container>

    <container-config>
        <tomcat xmlns="http://geronimo.apache.org/xml/ns/web/tomcat/config-1.0">
            <host>testhost.com</host>
            <valve-chain>FirstValve</valve-chain>
            <tomcat-realm>TomcatRealm</tomcat-realm>
        </tomcat>
    </container-config>

</web-app>

<naming:abstract-naming-entry>

The <naming:abstract-naming-entry> XML element uses the Geronimo Naming namespace, which is used to identify the common elements for resolving EJB references, resource references, and Web services references, and is described at http://geronimo.apache.org/schemas-2.1/docs/geronimo-naming-1.2.xsd.html. It is an abstract element used as a generic element for multiple reference types.

<naming:ejb-ref>

The <naming:ejb-ref> XML element uses the Geronimo Naming namespace, which is used to identify the common elements for resolving EJB references, resource references, and Web services references, and is described at http://geronimo.apache.org/schemas-2.1/docs/geronimo-naming-1.2.xsd.html. It 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.

<naming:ejb-local-ref>

The <naming:ejb-local-ref> XML element uses the Geronimo Naming namespace, which is used to identify the common elements for resolving EJB references, resource references, and Web services references, and is described at http://geronimo.apache.org/schemas-2.1/docs/geronimo-naming-1.2.xsd.html. It 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.

<naming:service-ref>

The <naming:service-ref> XML element uses the Geronimo Naming namespace, which is used to identify the common elements for
resolving EJB references, resource references, and Web services references, and is described at http://geronimo.apache.org/schemas-2.1/docs/geronimo-naming-1.2.xsd.html. It 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.

<naming:resource-ref>

The <naming:resource-ref> XML element uses the Geronimo Naming namespace, which is used to identify the common elements for resolving EJB references, resource references, and Web services references, and is described at http://geronimo.apache.org/schemas-2.1/docs/geronimo-naming-1.2.xsd.html. It is used to map resource references to resources's like JDBC resources, JMS resources, etc. configured outside the current application.

<naming:resource-env-ref>

The <naming:resource-env-ref> XML element uses the Geronimo Naming namespace, which is used to identify the common elements for resolving EJB references, resource references, and Web services references, and is described at http://geronimo.apache.org/schemas-2.1/docs/geronimo-naming-1.2.xsd.html. It is used to map resource references to administrative objects deployed as a part of connectors.

<naming:message-destination>

The <naming:message-destination> XML element uses the Geronimo Naming namespace, which is used to identify the common elements
for resolving EJB references, resource references, and Web services references, and is described at http://geronimo.apache.org/schemas-2.1/docs/geronimo-naming-1.2.xsd.html. It is used to configure a JMS queue or topic which acts like a destination for the messages delivered.

<security-realm-name>

The <security-realm-name> XML element uses the Geronimo default namespace for a geronimo-web.xml file that is described at http://geronimo.apache.org/schemas-2.1/docs/geronimo-web-2.0.1.xsd.html. It is used to specify the name of the security realm that will be used for user authentication.

<app:security>

The <app:security> XML element uses the Geronimo Applicaiton namespace described at http://geronimo.apache.org/schemas-2.1/docs/geronimo-application-2.0.xsd.html. It is used to maps roles specified in the WAR file to roles or principals in the security realm that will be used when deploying the module.

<sys:service>

The <sys:service> XML element uses the Geronimo System namespace described at http://geronimo.apache.org/schemas-2.1/docs/geronimo-module-1.2.xsd.html. It is an empty generic element to be extended by GBean and other module types.

<ee:persistence>

The <ee:persistence> XML element uses the Java EE Persistence namespace described at http://java.sun.com/xml/ns/persistence/. Apache Geronimo uses OpenJPA for providing Java Persistence API to Java EE applications deployed in the server.

Samples

For example, the following web.xml and geronimo-web.xml are the deployment descriptor and Geronimo deployment plan respectively, of a web application that connects to a datasource deployed on DB2 and retrieves data from a table.

<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
         http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" version="2.5">
    
    <resource-ref>
        <res-ref-name>jdbc/DataSource</res-ref-name>
        <res-type>javax.sql.DataSource</res-type>
        <res-auth>Container</res-auth>
        <res-sharing-scope>Shareable</res-sharing-scope>
    </resource-ref>
    
    <welcome-file-list>
        <welcome-file>jsp/EMPdemo.jsp</welcome-file>
    </welcome-file-list>
</web-app>

The web module connects to back end datasource using its JNDI name jdbc/DataSource as declared in the web.xml.

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

    <sys:environment>
        <sys:moduleId>
            <sys:groupId>samples</sys:groupId>
            <sys:artifactId>EmployeeDemo</sys:artifactId>
            <sys:version>2.5</sys:version>
            <sys:type>war</sys:type>
        </sys:moduleId>
        
        <sys:dependencies>
            <sys:dependency>
                <sys:groupId>samples</sys:groupId>
                <sys:artifactId>EmployeeDatasource</sys:artifactId>
                <sys:version>2.5</sys:version>
                <sys:type>rar</sys:type>
            </sys:dependency>
        </sys:dependencies>
    </sys:environment>
    
    <context-root>/EmployeeDemo</context-root>
        <naming:resource-ref>
        <naming:ref-name>jdbc/DataSource</naming:ref-name>
        <naming:resource-link>jdbc/EmployeeDatasource</naming:resource-link>
    </naming:resource-ref>
</web-app>

Observe the various XML tags and corresponding namespaces used in the deployment plan for various purposes.

<sys:environment> .. </sys:environment> : These elements provide the moduleid configuration and the dependencies. The moduleId elements provide the configuration name for the web module. So, when the web module is deployed, it is given the configuration name samples/samples/2.5/jar. The dependencies elements provide the configurations and third party libraries on which the web module is dependent on. These configurations and libraries will be available to the web module via a classloader hierarchy. In this case, the web module is dependent on samples/EmployeeDatasource/2.5/rar which is the configuration of the deployed Datasource that connects to a back end DB2 database. The Datasource deploys a database connection pool (javax.sql.Datasource) with name jdbc/EmployeeDatasource.

<sys:context-root> .. </sys:context-root> : The XML elements used to provide the web context root of the web applications.

<naming:resource-ref> .. </naming:resource-ref> : These elements help us to configure the resource references. In this case, the datasource reference jdbc/DataSource is mapped to jdbc/EmployeeDatasource.

In the EMPdemo.jsp, the following java code snippet is used to obtain a connection from the datasource.

....
....
Context initContext = new InitialContext();
Context envContext  = (Context)initContext.lookup("java:comp/env");
DataSource ds = (DataSource)envContext.lookup("jdbc/DataSource");
Connection con = ds.getConnection();
....
....

The above descriptor and the plan files are the simple illustrations that explain how web modules are developed and assembled for Apache Geronimo. Similarly, many other configurations can be performed in the geronimo-web.xml.

All the XML schema files are located at <geronimo_home>/schema directory. Please go through the .xsd files to have a feel of XML tags that can be used in geronimo-web.xml for configuring web applications.