...

Overview

INLINE

The Geronimo-specific deployment plan for a Web application, which is usually packaged as a WAR file, is called "geronimo-web.xml".

...

Packaging

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

...

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^{Image Removed}

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 Geronimo System, Geronimo Naming, Geronimo Security, Geronimo Application, and Geronimo Persistence 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:

...

This schema is not container-specific, meaning that it can be used to deploy a web application to either of the Tomcat or Jetty web containers supported by Geronimo. If it is necessary to deploy to a specific container, one of the two following container-specific schemas can be used instead. These allow container-specific configuration elements that are only understood by either the Tomcat or Jetty web container.

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

...

• schemas-2.

...

• 1

...

• /docs/geronimo-jetty-2.0.2.xsd.html

Finally, while the generic schema has no container-specific elements, it does facilitate the inclusion of container-specific elements by using the <container-config> element. This element is described in more detail below.

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 Geronimo System, Geronimo Naming, Geronimo Security, Geronimo Application, and Geronimo Persistence 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:

...

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

...

The <sys:environment> element contains the following elements:

...

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

...

<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.1.1</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>

...

<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 documented here:

• 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 provide some degree of control of the Geronimo classloader hierarchy, and mitigate clashes between classes loaded by the server and classes loaded by the web application. It is used to lists packages or classes that may be in a parent classloader, but must not be exposed to the web application. Since Geronimo is entirely open-source and utilizes many other open-source libraries it is possible that the server itself and the web application may have different requirements and/or priorities for the same open source project libraries. The <hidden-classes> element is typically used when the web application has requirements for a specific version of a library that is different than the version used by Geronimo itself. A simple example of this is when a web application uses, and most importantly includes, a version of the Log4J common logging library that is different than the version used by the Geronimo server itself. This might not provide the desired results. Thus, the <hidden-classes> element can be used to "hide" the Log4J classes loaded by all the parent classloaders of the web application module, including those loaded by and for the Geronimo server itself, and only the Log4J classes included with the web application library will get loaded.
  
  
• The <non-overridable-classes> element can also be used to provide some degree of control of the Geronimo classloader hierarchy, but in the exact opposite manner than provided by the <hidden-classes> element. This element can be used to specify a list of classes or packages which will only be loaded from the parent classloader of the web application module to ensure that the Geronimo server's version of a library is used instead of the version included with the web application.
  
  
• The <inverse-classloading> element can be used to specify that standard classloader delegation is to be reversed for this module. The Geronimo classloader delegation follows the Java EE 5 specifications, and the normal behavior is to load classes from a parent classloader (if available) before checking the current classloader. When the <inverse-classloading> element is used, this behavior is reversed and the current classloader will always be checked before looking in the parent classloader(s). This element is similar to the <hidden-classes> element since the desired behavior is to give the libraries packaged with the web application (i.e., in WEB-INF/lib) precedence over anything used by the Geronimo server itself.
  
  
• 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). If the <suppress-default-environment> element is specified then any default environment build by a builder when deploying the plan will be suppressed. An example of where this is useful is when deploying a connector on an app client in a separate (standalone) module (not as part of a client plan). The connector builder defaultEnvironment includes some server modules that won't work on an app client, so you need to suppress the default environment and supply a complete environment including all parents for a non-app-client module you want to run on an app client. This element should not be used for web applications however.

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

...

<context-root>

The <context-root> XML element uses the Geronimo default namespace for the geronimo-web.xml file, and is documented here:

• 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. As an example, if the context root is specified as <context-root>web-app-test</context-root> then the URL to the application would look like http://host:8080/web-app-test/. If the context root is specified as <context-root>/</context-root> that would become the default web application for the server. The <context-root> element is optional, but if it is not specified the context root of the web application will default to the WAR name (without the extension). If the web application is packaged in an EAR, then the context root can be specified
in the EAR's application.xml deployment descriptor.

<work-dir>

The <work-dir> XML element uses the Geronimo default namespace for the geronimo-web.xml file, and is documented

<context-root>

The <context-root> XML element uses the Geronimo default namespace for a geronimo-web.xml file that is described here:

• http://geronimo.apache.org/schemas-2.1/docs/geronimo-web-2.0.1.xsd.html^{Image Removed}

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. As an example, if the context root is specified as <context-root>web-app-test</context-root> then the URL to the application would look like http://host:8080/web-app-test/^{Image Removed}. If the context root is specified as <context-root>/</context-root> that would become the default web application for the server. The <context-root> element is optional, but if it is not specified the context root of the web application will default to the WAR name (without the extension). If the web application is packaged in an EAR, then the context root can be specified
in the EAR's application.xml deployment descriptor.

<work-dir>

The <work-dir> XML element uses the Geronimo default namespace for a geronimo-web.xml file that is described here:

• http://geronimo.apache.org/schemas-2.1/docs/geronimo-web-2.0.1.xsd.html^{Image Removed}

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

• http://geronimo.apache.org/schemas-2.1/docs/geronimo-naming-1.2.xsd.html^{Image Removed}

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.1.1</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 here:

• http://geronimo.apache.org/schemas-2.1/docs/geronimo-web-2.0.1.xsd.html^{Image Removed}

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:

...

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 documented here:

...

• http://geronimo.apache.org/

...

• schemas-2.1/docs/geronimo-naming-1.2.xsd.html

This element is used to specify a reference to a web-container specific GBean either via a pattern to the moduleId of the configuration, or via a link to a GBean. As an example, consider the case where it is required to run a web application in a Tomcat container using a dedicated port such that no other web application is allowed to use that port. To accomplish this a separate GBean would have to be defined for the "Container", "Engine", "Host", and "Connector", and a <naming:web-container> element would have to be used to reference this new Tomcat container. An example geronimo-web.xml file is shown below:

...

<container-config>

As previously mentioned, there are actually three schemas that can be used for the geronimo-web.xml file. The first is container-independent and can be used to deploy a web application to either of the web containers supported by Geronimo. The second two are container-dependent that contain elements specific to either the Tomcat or Jetty web container:

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

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

• http://geronimo.apache.org/schemas-2.1/docs/geronimo-naming-1.2.xsd.html^{Image Removed}.

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

• http://geronimo.apache.org/schemas-2.1/docs/geronimo-naming-1.2.xsd.html^{Image Removed}

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>

...

2. http://geronimo.apache.org/schemas-2.1/docs/geronimo

...

1. -jetty-2.0.2.xsd.html

Which to use is left to the discretion of the user. If a web application is meant to be deployed to both Tomcat and Jetty, then the generic schema is typically used, and if a web application is meant to be deployed to only Tomcat or Jetty, then one of the container-specific schemas is typically used. However, another option is available since the generic schema allows the inclusion of the container-specific elements found in the container-specific schemas by using the <container-config> element. This allows the user to use the generic schema even when the web application requires container-specific configuration for Tomcat or Jetty (or both). An example geronimo-web.xml file is shown below using the <container-config> element to configure the Tomcat web container. Note that the <host>, <valve-chain>, and <tomcat-realm> elements are understood only by the Tomcat container, not Jetty:

...

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

...

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

...

<sys:gbean>

The <sys:gbean> XML element uses the Geronimo System namespace, and is documented

...

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

• http://geronimo.apache.org/schemas-2.1/docs/geronimo-namingmodule-1.2.xsd.html^{Image Removed}

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

• http://geronimo.apache.org/schemas-2.1/docs/geronimo-naming-1.2.xsd.html^{Image Removed}

It is used to configure a JMS queue or topic which acts like a destination for the messages delivered.

The <sys:gbean> element is used to define GBean(s) that are configured and deployed with the web application module. These additional Geronimo services will be deployed when the application is deployed (and stopped when the application is stopped). Normally, the implementation classes for these services are included at the server level and referenced using a dependency element.

<ee:persistence>

The <ee:persistence> XML element uses the Java EE Persistence namespace, and is documented here:

• http://java.sun.com/xml/ns/persistence/

Apache Geronimo uses OpenJPA for providing Java Persistence API to Java EE applications deployed in the server. The persistence deployment descriptor information is typically provided using a persistence.xml file. The <ee:persistence> top-level element can be used include the persistence deployment descriptor in the geronimo-web.xml file. More information and details about the JPA deployment descriptor can be found here: Creating deployment plans for Java Persistence API.

Security

Additional information and details for configuring security for Geronimo can be found here:

• Administering Security

<security-realm-name>

The <security-realm-name> XML element uses the Geronimo default namespace for a the geronimo-web.xml file that , and is described documented here:

• http://geronimo.apache.org/schemas-2.1/docs/geronimo-web-2.0.1.xsd.html^{Image Removed}.

It The <security-realm-name> element 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 here: http://geronimo.apache.org/schemas-2.1/docs/geronimo-application-2.0.xsd.html^{Image Removed}.

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>

for the web application. It is used in conjunction with the <security-constraint> element in the corresponding web.xml deployment plan for this web application. This element will not cause the creation of a new security realm in Geronimo, it references a security realm that has already been created and configured. See Administering Security for details on how this is typically accomplished from the Geronimo Admin Console.

<sec:security>

The <sec:security> XML element uses the Geronimo Security namespace, and is documented The <sys:service> XML element uses the Geronimo System namespace described here:

• http://geronimo.apache.org/schemas-2.1/docs/geronimo-modulesecurity-12.20.xsd.html^{Image Removed}
  It is an empty generic element to be extended by GBean and other module types.

...

The <ee<sec:persistence> XML security> element uses the Java EE Persistence namespace described here:

• http://java.sun.com/xml/ns/persistence/^{Image Removed}

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.

...

groups the security role mapping settings for the web application. This is an optional element, but if it is present all the web modules must make the appropriate access checks as outlined in the JACC specification. This element includes the <role-mapping> section that references the role(s) defined in the <security-role> element in the web.xml file. An example web.xml and corresponding geronimo-web.xml file is shown below with the "admin" role name defined in the web.xml is referenced in the geronimo-web.xml:

...

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

...

JNDI Environment References

All the JNDI reference elements in this section use the Geronimo Naming namespace, which is used to identify the common elements for resolving EJB references, resource references, and Web services references, and is documented here:

• http://geronimo.apache.org/schemas-2.1/docs/geronimo-naming-1.2.xsd.html

Additionally, more information and details about JNDI references can be found here: Global JNDI.

<naming:abstract-naming-entry>

The <abstract-naming-entry> element is not technically a JNDI reference element. It is included in this section because it is an abstract element used for containing these JNDI reference types:

• <gbean-ref>
  
  The <gbean-ref> element is used to map GBean references to GBeans configured outside the current module
  
  
• <persistenceunit-ref>
  
  The <persistenceunit-ref> element is used to map persistence unit references to persistence units configured outside the current module
  
  
• <persistencecontext-ref>
  
  The <persistencecontext-ref> element is used to map persistence context references to persistence contexts configured outside the current module

An example geronimo-web.xml file is shown below using the <abstract-naming-entry> element to reference a persistence unit:

...

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

...

<naming:ejb-ref>

The <naming:ejb-ref> element 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 the current application.

<naming:ejb-local-ref>

The <naming:ejb-local-ref> element 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 the current application.

<naming:service-ref>

The <naming: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.

<naming:resource-ref>

The <naming:resource-ref> element is used to map resource references to resources like JDBC resources, JMS resources, etc. configured outside the current application.

<naming:resource-env-ref>

The <naming:resource-env-ref> element is used to map resource references to administrative objects deployed as a part of connectors.

<naming:message-destination>

The <naming:message-destination> element is used to map resource references to a message-destination which is used within the deployed web application. These are typically a JMS queue or topic which acts like a destination for the messages delivered. Like all the JNDI references in this section, this element will not cause the creation of a message-destination, references an existing message-destination used within the deployed web application

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