{scrollbar}

top
This article will be an introduction to understand the Geronimo deployment plan to the user in different Web application development areas. As Geronimo deployment plan for Web application is a wide topic to discuss, in this article I will be covering the following scope with the hope of expanding to cover more topics in the future. The article will describe the geronimo-web.xml plan's structure and elements in depth and how it's organized to refer different resources.To provide a great deal of information about the geronimo web deployment plans, starting from simple Helloworld sample and continued to discuss about geronimo web deployment plans of existing sample applications.

This article is organized into the following sections : -

• #1.0 Describing the geronimo-web deployment plan
  • #1.1 Web application deployment plan overview
    • #1.1.1 Web application identity and Deployment path
    • 1.1.2 Web application:Deployment path
    • 1.1.3 Web application: Context Root
    • 1.1.4 Web application: Binding to Specific Ports
• #2.0 Work out deployment plans with samples
  • #2.1 Deployment plan for HelloWorld WAR module
  • 2.2 Resolving references in Geronimo-web
    • #2.2.1 Common resource mapping elements
    • 2.2.2 Web application: common references
  • #2.3 Resolving GBean references
    • #2.3.1 GBean reference example
    • #2.3.2 Accessing the GBean from the Web application
  • #2.4 Resolving EJB references
    • #2.4.1 EJB reference example
    • #2.4.2 Accessing the EJB from the Web application
  • 2.5 Referring to JMS in Web application
  • #2.6 Referring to database connection pools from Web applications
  • #2.7 Security settings
    • #2.7.1 Security realm sample

1.0 Describing the geronimo-web deployment plan

The Geronimo deployment plan for a Web application is an XML document. It is defined by the geronimo-web-1.1.xsd schema, which can be found in the <geronimo_home>/schema/ subdirectory of the main Geronimo installation directory. This deployment plan should be placed in WEB-INF folder and named as geronimo-web.xml and included in the Web application WAR.
The deployment plan should always use the Geronimo web namespace, and it typically requires elements from the Geronimo Naming namespace. Additionally, it has a required attribute to identify its configuration name, and an optional attribute to select a parent configuration. A typical Web application deployment plan will include the following attributes and should be placed in WEB-INF folder:

xmlsolidgeronimo-web.xml <?xml version="1.0" encoding="UTF-8"?> <web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.1" xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.1" xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.1" xmlns:security="http://geronimo.apache.org/xml/ns/security-1.1"> ... </web-app>

Description of the content of the above code :

• The Geronimo schema for the server plans and common elements (http://geronimo.apache.org/xml/ns/deployment-1.1)is used to deploy new services in Geronimo in a standalone plan, and also contains common elements used by many other plans.

• The elements with no prefix are from the namespace http://geronimo.apache.org/xml/ns/j2ee/web-1.1, while the elements with the naming: prefix are from the namespace http://geronimo.apache.org/xml/ns/naming-1.1 and the elements with the sys: prefix are from the namespace http://geronimo.apache.org/xml/ns/deployment-1.1. All three namespaces are identified in the web-app header(which makes them available anywhere within the document).

• If the Jetty version of Geronimo is being used then the the server namespace can be used as http://geronimo.apache.org/xml/ns/j2ee/jetty-1.1 and if it is Tomcat then, http://geronimo.apache.org/xml/ns/j2ee/tomcat-1.1. Therefore, the common use of the target namespace of Web application in Geronimo used http://geronimo.apache.org/xml/ns/j2ee/web-1.1

• ModuleID and dependencies are defined in the <environment> block of an XML file. Any application or module can declare a moduleID for itself using moduleID element and can declare dependencies using the dependency element. The following snippet details the dependencies declared in the <enviroment> block.

xmlsolidExcerpt from the sample application below <environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1"> <moduleId> <groupId>geronimo</groupId> <artifactId>HelloWorld</artifactId> <version>1.1</version> <type>war</type> </moduleId> </environment>

Once you deploy the application, the HelloWorld.war application will be created in <geronimo_home>/deploy/ directory.

To access the deployed sample the following url needs to be accessed. Refer 1.1.3 Web application: Context Root for further details.

1.1 Web application deployment plan overview

There is a specific internal structure for the Web application deployment plan for Geronimo as well.The Web application deployment plan follows a specific structure and order of elements.

1.1.1 Web application identity and Deployment path

The Deploy tool and the console refers the Web application by the name defined in the moduleID and the elements of the deployment plan configure its class path.

1.1.2 Web application:Deployment pathclasspath

The elements here are:

ModuleId : A moduleID uniquely identifies a specific module,including it's name ,version,etc.In fact,there are four components of a moduleID. The moduleID creates a unique name for the Web application. If moduleID is not provided, the Web application's name will be default/war-name/timestamp/war.

Dependencies : A list of dependencies for the module. Each dependency may be another module (such as an EJB module or database pool), or a third-party library located in the Geronimo repository dependency. It also holds the identifying information for a single dependency. Only the artifactID is required, but the dependency as a whole should be specific enough to identify a single JAR or module – you cannot leave out elements as a way of creating a wildcard name that matches multiple JARs.

GroupID: A name identifying a group of related modules. This may be a project name, a company name, etc.The important thing is that each artifactID should be unique within the group. If no group is specified when declaring the moduleID for a module or application, it will get the group ID default. If no group is specified for a moduleID used to identify a dependency,then it is treated as a wildcard and the group is not used to help identify the exact dependency.

ArtifactID: A name identifying the specific module within the group. For example, there may be one group ID for an application, with separate artifact IDs for the Web application and EJB modules that make up that application. Every moduleID must include an explicit artifactID. If no moduleID is specified when deploying a module, the artifactID details the file names of the module file.

Version : Each module has a version number. If the version number is specified when decaring the moduleID for a module or application, it will get the numeric timestamp as it's version number. Each time the module is redeployed it will get a new timestamp. If no version number is specified for a moduleID used to identify a dependency, then any available version will be used. If there are multiple versions, Geronimo favors any version that might already be loaded, or else typically the newest version will be used.

Type : A module's type is normally either CAR (for a system module) or the file extension for an application module (ear,war,jar,etc). If no type is specified, the type will be set appropriately by the deployer when the module is deployed.

Import : Used for dependencies. For a dependency that's a JAR, this is not useful and should just be omitted. For a dependency that's a separate Geronimo module, there are three possibilities. One, the class loader for the module should be added as a parent of the class loader for the Web application (this might be used if the module is just an aggregation of common JARs). For that behavior, set this value to classes. The second option is that the services defined in the module should be started before and available to this module (this might be used for a database pool where the classes are not needed but the pool must be started). For that behavior, set this value to services. If this element is not included, you get both (the module is on the class path and the services are started first). Under most circumstances this element should be omitted and the default behavior will be correct.

Hidden-classes : Lists packages or classes that may be in a parent class loader, but should not be exposed from there to the Web application. This is typically used when the Web application wants to use a different version of a library than that of it's parent configuration (or Geronimo itself) uses.

Non-overridable-classes : Lists packages or classes that the Web application should always load from a parent class loader, and never load from WEB-INF/lib or WEB-INF/classes. This might be used to force a Web application to share the same instance of a common library with other Web applications, even if they each include it in their own WAR.

filter classes or packages : The format is a list of packages seperated by commas or fully-qualified class names (for example: javax.servlet,javax.ejb).

inverse-classloading : Normally (if this element is omitted), the module's class loader will work normally – classes will be loaded from the parent class loader if available before checking the current class loader. If this element is added, that behavior is reversed and the current class loader will always be checked first before looking in the parent class loader. This is often enabled to give the JARs in WEB-INF/lib precedence over anything that might be in a parent class loader. This element does not take any content, it is simply present or absent.

Suppress-default-environment : This should not be used for Web applications.

1.1.3 Web application: context rootcontextroot

This element controls the URL that clients use to access the Web application.

Context-root :

The context root is the first segment of the URL used to access the Web application by the client. For example, if the context-root was hello, then a typical URL to the application would start with http://host:port/hello/ and a context-root value of / would be used to make this the default Web application for the server.

1.1.4 Web Application: Binding to Specific Portsports

A Web application is normally deployed to the default Web container instance, and uses the network ports for that Web container. But it's possible to set up an additional Web container with different network ports and other configuration settings. The web-container element can be used to associate this Web application with a specific Web container instance, which can have the effect of binding this Web application to a different set of ports, than other Web applications.A set of elements need to be set for such binding to specific ports.

web-container
This element indicates that this Web application should be deployed to the specified web container, instead of the default web container.Since there is only one Web container configured by default and it is not a must to have this element.

Pattern
If a simple name is not sufficient to distinguish the Web container, a full name pattern can be used to uniquely identify it. A pattern points to a resource located elsewhere in the server. Normally only the name is required, and between the name and the type of the reference, that's enough to identify the target. The groupID, artifactID, and version can be used to identify the module that holds the target resource, in case there is more than one matching resource in the dependencies of the current module.

gbean-link
Normally each Web container has a unique name, and only that name is needed to identify the target Web container. This element holds the name of the Web container that this Web application should be deployed to. The default Web container name is JettyWebContainer (for Jetty distributions) or TomcatWebContainer (for Tomcat distributions).

Back to Top

2.0 Work out deployment plans with samples

This section will cover the deployment of various Web applications which use different Geronimo server and external resources. This section starts with the Helloworld sample Web application which elaborates the basic requirements of deploying Web application in Geronimo. Then, it has extended to describe the use of it's elements, and how to implement more resource references in Web applications.This section covers the examples taken from the deployment plans of existing
sample applications section.

Assumptions

It is assumed that you have installed either Tomcat or Jetty version of Geronimo v1.1 successfully and it is working. Refer to the Installation section for further details.

2.1 Deployment plan for HelloWorld WAR module

This section covers how the deployment plan works for the Web application module. First, let's have a look at the simple "HelloWorld" example which creates a Web Application Archive (WAR) under the WEB-INF directory and has a geronimo-web.xml as the Apache Geronimo specific deployment plan.

The steps to understanding the deployment plan for the "HelloWorld" example are given below:

1. Create a folder in called <app_home> in your working directory.
2. Open up a new text file and save it as "HelloWorld.jsp" in side the app_home directory.
3. Copy and past the following code for the "HelloWorld.jsp" in it. javasolidHelloWorld.jsp <%@ page language="java" contentType="text/html; charset=ISO-8859-1" pageEncoding="ISO-8859-1"%> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <title>HelloWorld!</title> </head> <body bgcolor="#707DB8"> <h1> <font face="courier" color="white"> Hello world from GERONIMO v1.1! </font> </h1> <font face="courier" color="white"> ${datetime}</font> </html>
4. Create a new folder called"WEB-INF" inside the <app_home>.
5. Open up a new text file and save it as "geronimo-web.xml" and this is the Apache Geronimo v1.1 deployment plan for this sample module.
6. Copy and paste the following xml code in that file and save it inside the <app_home\WEB-INF> directory.

xmlsolidgeronimo-web.xml <?xml version="1.0" encoding="UTF-8"?> <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> <groupId>geronimo</groupId> <artifactId>HelloWorld</artifactId> <version>1.1</version> <type>war</type> </moduleId> </environment> <context-root>/hello</context-root> </web-app>

1. Open up a another new text file save it in <app_home\WEB_INF> directory and name it as "web.xml"
2. Copy and Paste the following xml code in it and save.

xmlsolidweb.xml <?xml version="1.0" encoding="UTF-8"?> <web-app version="2.4" 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"> <welcome-file-list> <welcome-file>HelloWorld.jsp</welcome-file> </welcome-file-list> </web-app>

NOTE This sample can be downloaded from here HelloWorld web Sample

2.2 Resolving references in Geronimo-web references

The resource-ref and resource-env-ref elements let you map resource references (typically JDBC, JMS, or JavaMail resources) to specific resources available in the server. In general, a resource-env-ref is used to reference an administered object deployed as part of a J2EE Connector, while a resource-ref is used to reference a JDBC connection pool, JMS connection factory, JavaMail session, or other type of resource.The web.xml file may declare several types of references.For the moment the following references are available:

1. EJB references
2. GBean references
3. DBPools
4. Resource references

The following resource reference will be discussed in the future :

1. Web services references
2. Message destination references

This section describes how the geronimo-web.xml file maps those references to specific items available in the server environment. When mapping references, the target reference must be in the same application, or in a module listed as a dependency of the current application. If a resource in a different module cannot be found, the first thing to do is make sure that module is listed as a dependency.

2.2.1 Common resource mapping elements

All of the resource types use common elements to refer to other resources running in the server. These elements are grouped together under a pattern element as shown in the diagram below.

2.2.2 Web application: common referencescommon

Common References are elements to a resource located elsewhere in the server. Normally only the name is required, and between the name and the type of the reference, that's enough to identify the target. The groupID, artifactID, and version can be used to identify the module that holds the target resource, in case there is more than one matching resource in the dependencies of the current module.

name : The name of the target resource (EJB, database pool, JMS connection manager, JMS destination, GBean, etc.). The element that contains the pattern identifies the type of the resource, and the type and name specified here are usually enough to uniquely identify a resource. If that's the case, none of the other elements are required. If there's a name collision, the other elements can be used to narrow it down to a single individual resource.

groupId : Identifies the group component of the ModuleID of the module that the target resource is in. This should be used if more than one dependency of the Web application contains a resource with the target name and type.

artifactId : Identifies the artifact component of the ModuleID of the module that the target resource is in. This should be used if more than one dependency of the Web application contains a resource with the target name and type.

version : Identifies the version component of the ModuleID of the module that the target resource is in. This should be used if more than one dependency of the web application contains a resource with the target name and type of the module.
Back to Top

2.3 Resolving GBean references

GBean references can be used to refer to services running in Geronimo other than the usual J2EE reference types. For an EJB, database pool, JMS resource, or Web service, other reference types work. But to create a reference to a Geronimo component such as the ServerInfo GBean, or a component distributed as part of a Geronimo plugin such as the QuartzScheduler GBean, a GBean reference is necessary. Geronimo plugins can be downloaded from here.

A GBean reference adds an entry to the applications private (java:comp/env/) JNDI space, like other references. However, there is no entry for a GBean reference in web.xml, all the data is configured in the Geronimo deployment plan.

2.3.1 GBean reference example

xmlsolidWEB-INF/geronimo-web.xml <web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.1"> <context-root>/gbean</context-root> <!--gbean-ref: Holds all the settings for a single GBean reference ref-name: Each reference must have a ref-name, which is used to determine the JNDI name where the reference can be accessed by the web application. The specific JNDI location is java:comp/env/ plus the value specified here. ref-type: The ref-type specifies the interface that will be used for the JNDI entry. The GBean must implement this interface, and declare it in its GBeanInfo. pattern: Identifies the specific GBean that this reference should point to. The pattern specified here must uniquely identify a single GBean, though normally only the name is required to do so.--> <gbean-ref xmlns="http://geronimo.apache.org/xml/ns/naming-1.1"> <ref-name>gbeans/ServerInfo</ref-name> <ref-type> org.apache.geronimo.system.serverinfo.ServerInfo </ref-type> <pattern> <name>ServerInfo</name> </pattern> </gbean-ref> </web-app>

2.3.2 Accessing the GBean from the Web application

javasolidGBeanInfo.jsp %@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8"%> <%@page import="org.apache.geronimo.system.serverinfo.ServerInfo"%> <%@page import="javax.naming.InitialContext"%> <%@page import="javax.naming.Context"%> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <title>GBean Refernce</title> </head> <body> <tr> <b>This Web Application refers a GBean</b> </tr> <tr> <td> <% //Accessing the GBean Details from the WebApp Context ctx =new InitialContext(); Object results =ctx.lookup("java:comp/env/gbeans/ServerInfo"); ServerInfo info =(ServerInfo)results; String str1 = info.getBaseDirectory(); String str2 = info.getVersion(); String str3 = info.getBuildDate(); String str4 = info.getBuildTime(); out.println("BaseDirectory :"+ str1+"\n"); out.println("Version:" +str2 + "\n"); out.println("Build Date:" + str3 +"\n"); out.println("Build Time:" + str4 + "\n"); %> </td> </tr> </body> </html>

2.4 Resolving EJB references

To map EJB references to specific EJBs outside of the current application, the ejb-ref and ejb-local-ref elements are used. The EJB reference with the current application does not use the above applications and the ejb-link element would do the needful once it used in the standard J2EE deployment descriptor and there is no necessity for a geronimo-specific configuration for it.

Since EJBs requiring mapping are usually in a different applications, that application must be listed as a dependency of the current Web application. In addition to making the EJBs available for mapping, this adds the EJB classes to the Web application's class path, so they do not need to be packaged separately into the WAR.
The ejb-ref element is used to connect to an EJB through its remote home and remote interfaces. The EJB need not necessarily be located in a different server or JVM; sometimes the semantics of the remote interface are simply preferable to those of the local interface .

There can be cases that EJB will be accessed by both local and remote clients.In such a situation, it should not be worry about arguments being copied in some cases and passed by reference in others.

2.4.1 EJB reference example

This section will describe with the use of an example, how to refer an EJB from geronimo-web.xml. The the completed sample can be downloaded hereBasically this a program written to test whether how two ear are referring each other in geronimo.But It provides you the proper understanding in how to handle i deployment plan more clearly.

xmlsolidWEB-INF/web.xml <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" > <display-name>Geronimo EJBRef Itest War</display-name> <servlet> <display-name>Manifest ClassPath itest servlet</display-name> <servlet-name>servlet</servlet-name> <servlet-class>org.apache.geronimo.itest.TestServlet</servlet-class> <load-on-startup>0</load-on-startup> </servlet> <servlet-mapping> <servlet-name>servlet</servlet-name> <url-pattern>/servlet</url-pattern> </servlet-mapping> <ejb-ref> <ejb-ref-name>TestSession</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <home>org.apache.geronimo.itest.TestSessionHome</home> <remote>org.apache.geronimo.itest.TestSession</remote> </ejb-ref> <ejb-ref> <ejb-ref-name>link-nonj2ee</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <home>org.apache.geronimo.itest.TestSessionHome</home> <remote>org.apache.geronimo.itest.TestSession</remote> <ejb-link>TestSession</ejb-link> </ejb-ref> <ejb-ref> <ejb-ref-name>link</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <home>org.apache.geronimo.itest.TestSessionHome</home> <remote>org.apache.geronimo.itest.TestSession</remote> </ejb-ref> <ejb-ref> <ejb-ref-name>noModuleId</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <home>org.apache.geronimo.itest.TestSessionHome</home> <remote>org.apache.geronimo.itest.TestSession</remote> </ejb-ref> <ejb-ref> <ejb-ref-name>moduleId</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <home>org.apache.geronimo.itest.TestSessionHome</home> <remote>org.apache.geronimo.itest.TestSession</remote> </ejb-ref> <ejb-ref> <ejb-ref-name>moduleId2</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <home>org.apache.geronimo.itest.TestSessionHome</home> <remote>org.apache.geronimo.itest.TestSession</remote> </ejb-ref> </web-app> xmlsolidWEB-INF/geronimo-web.xml <web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web/jetty-1.1"> <environment> <moduleId> <groupId>default</groupId> <artifactId>ejbref-war</artifactId> <version>1.0-SNAPSHOT</version> <type>car</type> </moduleId> <dependencies> <dependency> <groupId>default</groupId> <artifactId>ejbref-ejb-1.0-SNAPSHOT.jar</artifactId> <type>jar</type> </dependency> </dependencies> </environment> <ejb-ref> <ref-name>link</ref-name> <ejb-link>TestSession</ejb-link> </ejb-ref> <ejb-ref> <ref-name>noModuleId</ref-name> <pattern> <name>TestSession</name> </pattern> </ejb-ref> <ejb-ref> <ref-name>moduleId</ref-name> <pattern> <groupId>default</groupId> <artifactId>ejbref-ejb-1.0-SNAPSHOT.jar</artifactId> <name>TestSession</name> </pattern> </ejb-ref> <ejb-ref> <ref-name>moduleId2</ref-name> <pattern> <groupId>default</groupId> <artifactId>ejbref-ejb2-1.0-SNAPSHOT.jar</artifactId> <name>TestSession</name> </pattern> </ejb-ref> </web-app>

2.4.2 Accessing the EJB from the Web application

javatitlesolid public class TestServlet extends HttpServlet { public void init() { System.out.println("Test Servlet init"); try { InitialContext ctx = new InitialContext(); TestSessionHome home = (TestSessionHome)ctx.lookup("java:comp/env/TestSession"); home.create(); System.out.println("Test Servlet looked up java:comp/env/TestSession"); home = (TestSessionHome)ctx.lookup("java:comp/env/link-nonj2ee"); home.create(); System.out.println("Test Servlet looked up java:comp/env/link-nonj2ee"); home = (TestSessionHome)ctx.lookup("java:comp/env/link"); home.create(); System.out.println("Test Servlet looked up java:comp/env/link"); home = (TestSessionHome)ctx.lookup("java:comp/env/noModuleId"); home.create(); System.out.println("Test Servlet looked up java:comp/env/noModuleId"); home = (TestSessionHome)ctx.lookup("java:comp/env/moduleId"); home.create(); System.out.println("Test Servlet looked up java:comp/env/moduleId"); home = (TestSessionHome)ctx.lookup("java:comp/env/moduleId2"); home.create(); System.out.println("Test Servlet looked up java:comp/env/moduleId2 from unrelated jar"); } catch (NamingException e) { System.out.print("Exception:"); e.printStackTrace(); } catch (RemoteException e) { e.printStackTrace(); } } protected void service(HttpServletRequest httpServletRequest, HttpServletResponse httpServletResponse) throws ServletException, IOException { httpServletResponse.getWriter().print("TestServlet"); httpServletResponse.flushBuffer(); } }

2.5 Referring to JMS in Web applicationjms

This section will refer the application in JMS and MDB sample application. In the sample, Order Processing Web application sends messages to the Order Queue. OrderSenderServlet will handle the relevant order request generation and the sending. web.xml of the archive has the relevant configurations for the both queue connection factory and the queue, which is essential to refer resources in a local enviroment.This section is described how it has implemented in the geronimo-web.xml in xml code base.As stated earlier, the following deployment plans are taken from the JMS and MDB sample application

xmlsolidweb.xml <?xml version="1.0" encoding="UTF-8"?> <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"> <servlet> <display-name>OrderSenderServlet</display-name> <servlet-name>OrderSenderServlet</servlet-name> <servlet-class>org.apache.geronimo.samples.order.web.OrderSenderServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>OrderSenderServlet</servlet-name> <url-pattern>/order</url-pattern> </servlet-mapping> <resource-ref> <res-ref-name>jms/CommonConnectionFactory</res-ref-name> <res-type>javax.jms.QueueConnectionFactory</res-type> <res-auth>Container</res-auth> <res-sharing-scope>Shareable</res-sharing-scope> </resource-ref> <message-destination-ref> <message-destination-ref-name>jms/OrderQueue</message-destination-ref-name> <message-destination-type>javax.jms.Queue</message-destination-type> <message-destination-usage>Produces</message-destination-usage> <message-destination-link>OrderQueue</message-destination-link> </message-destination-ref> <welcome-file-list> <welcome-file>/jsp/index.jsp</welcome-file> </welcome-file-list> </web-app>

In the web.xml there are several XML elements to be set to access a JMS resource. In this case the jms/CommonConnectionFactory is the JMS resource band, it also sets values to the child element of it within the resource-ref segment <recoure-ref>..</resource-ref>
The message-destination element declares the Queue, and the message-destination-ref declares a reference to it. This works automatically in Geronimo if the message-destination-name specified above matches the adminobject/message-destination-name in the Geronimo deployment plan for the JMS destination (though the message destination should have been deployed already). In this case there's no need for any more configuration in the WAR – in particular, the only setting needed in the geronimo-web.xml deployment plan is a dependency on the JMS resource group including that destination.
For reference, here's a snippet from a JMS connector deployment plan that matches the WAR configuration, geronimo-web.xml will act as a mediator between defined JMS resources in the application server and the web.xml.

xmlsolidCode snippet from JMS connector deployment plan <web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.1" xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.1"> <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1"> <dep:moduleId> <dep:groupId>samples</dep:groupId> <dep:artifactId>OrderWeb</dep:artifactId> <dep:version>1.0</dep:version> <dep:type>car</dep:type> </dep:moduleId> <dep:dependencies> <dep:dependency> <dep:groupId>geronimo</dep:groupId> <dep:artifactId>activemq-broker</dep:artifactId> <dep:type>car</dep:type> </dep:dependency> <dep:dependency> <dep:groupId>samples</dep:groupId> <dep:artifactId>jms-resources</dep:artifactId> <dep:version>1.0</dep:version> <dep:type>rar</dep:type> </dep:dependency> </dep:dependencies> <dep:hidden-classes/> <dep:non-overridable-classes/> </dep:environment> <context-root>/Order</context-root> <resource-ref> <ref-name>jms/CommonConnectionFactory</ref-name> <resource-link>CommonConnectionFactory</resource-link> </resource-ref> <resource-env-ref> <ref-name>jms/OrderQueue</ref-name> <admin-object-link>OrderQueue</admin-object-link> </resource-env-ref> </web-app>

Considering the geronimo-web.xml deployment plan, there are few settings that have to be done to refer this JMS resource. The JMS supporting resource of the Geronimo server is required to be avaliable in the deployment plan itself. Therefore, the dependencies are set as follows which makes the resource available to the application.Let's take look at the following code segment

xmlsolid <dep:dependencies> <dep:dependency> <dep:groupId>geronimo</dep:groupId> <dep:artifactId>activemq-broker</dep:artifactId> <dep:type>car</dep:type> </dep:dependency> ...... </dep:dependencies>

As shown in the above code excerpt of the deployment plan, this dependency is physically located in <geronimo-home>/repositories/geronimo/activemq-broker/1.1.1/activemq-broker-1.1.1.car
Furthermore, the following piece of code is presented in the way that resource references are set.
Jms/CommonConnectionFactory is the JMS resource Type we have used to create the JMS Queue. It has been defined in the <resource-ref> and the <resource -env-ref> segments, and are carrying the name of the resource created in the Geronimo server. Therefore, OrderQueue is the Queue created and deployed in the server.

xmlsolid <resource-ref> <ref-name>jms/CommonConnectionFactory</ref-name> <resource-link>CommonConnectionFactory</resource-link> </resource-ref> <resource-env-ref> <ref-name>jms/OrderQueue</ref-name> <admin-object-link>OrderQueue</admin-object-link> </resource-env-ref>

2.6 Referring to database connection pools from Web applications

This section will describe how to refer Database pools in Web applications. This is describing using Simple database access sample application and it's database pool deployment plan. Application defines a datasource with the help of geronimo-web.xml and web.xml files. geronimo-web.xml adds a link between the database pool already deployed in the server. It refers to the database pool via it's artifactID. According to the given geronimo-web.xml deployment plan, the artifactID is given as InventoryApp, which is the name of the database pool connection which has created for this sample application. Furthermore, the dependencies are set to console.dbpool as the groupID and InventoryPool as the artifactID of it. InventoryPool is the name of the Database connection plan. All of the work mentioned earlier is not enough to give a reference to a Database connection and it should be followed by the resource reference tags in the geronimo-web.xml as well as in web.xml.

xmlsolidgeronimo-web.xml <?xml version="1.0" encoding="UTF-8"?> <web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.1"> <environment> <moduleId> <artifactId>InventoryApp</artifactId> </moduleId> <dependencies> <dependency> <groupId>console.dbpool</groupId> <artifactId>InventoryPool</artifactId> </dependency> </dependencies> </environment> <context-root>/inventory</context-root> <!-- define a reference name to the db pool--> <resource-ref> <ref-name>jdbc/InventoryDS</ref-name> <resource-link>InventoryPool</resource-link> </resource-ref> </web-app>

The following is the web.xml of the Inventory application. It uses the same name as in geronimo-web.xml, which is used to create the datasource. In the web.xml the Data connection pool has been exposed as a datasource in a <resource-ref> and had set the value to jdbc/InventoryDS.

xmlsolidweb.xml <?xml version="1.0" encoding="UTF-8"?> <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"> <welcome-file-list> <welcome-file>welcome.jsp</welcome-file> </welcome-file-list> <servlet> <display-name>AddItemServlet</display-name> <servlet-name>AddItemServlet</servlet-name> <servlet-class>org.apache.geronimo.samples.inventory.web.AddItemServlet</servlet-class> </servlet> <servlet> <display-name>IssueingServlet</display-name> <servlet-name>IssueingServlet</servlet-name> <servlet-class>org.apache.geronimo.samples.inventory.web.IssueingServlet</servlet-class> </servlet> <servlet> <display-name>RecievingServlet</display-name> <servlet-name>RecievingServlet</servlet-name> <servlet-class>org.apache.geronimo.samples.inventory.web.RecievingServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>AddItemServlet</servlet-name> <url-pattern>/add_item</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>IssueingServlet</servlet-name> <url-pattern>/issue</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>RecievingServlet</servlet-name> <url-pattern>/recv</url-pattern> </servlet-mapping> <!-- reference name exposed as a datasource --> <resource-ref> <res-ref-name>jdbc/InventoryDS</res-ref-name> <res-type>javax.sql.DataSource</res-type> <res-auth>Container</res-auth> <res-sharing-scope>Shareable</res-sharing-scope> </resource-ref> </web-app>

The application server going to access InventoryDB through a connection pool. In the sample the steps to create the connection pool(Simple database access sample application).When it comes to this level, we have already discussed deployment plans and now the Database connection pool plan is going to be discussed further. This plan can be created using the Geronimo web console.

xmlsolidInventoryPool.xml <?xml version="1.0" encoding="UTF-8"?> <connector xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.1"> <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1"> <dep:moduleId> <dep:groupId>console.dbpool</dep:groupId> <dep:artifactId>InventoryPool</dep:artifactId> <dep:version>1.0</dep:version> <dep:type>rar</dep:type> </dep:moduleId> <dep:dependencies> <dep:dependency> <dep:groupId>geronimo</dep:groupId> <dep:artifactId>system-database</dep:artifactId> <dep:type>car</dep:type> </dep:dependency> </dep:dependencies> </dep:environment> <resourceadapter> <outbound-resourceadapter> <connection-definition> <connectionfactory-interface>javax.sql.DataSource</connectionfactory-interface> <connectiondefinition-instance> <name>InventoryPool</name> <config-property-setting name="Driver">org.apache.derby.jdbc.EmbeddedDriver</config-property-setting> <config-property-setting name="UserName">app</config-property-setting> <config-property-setting name="ConnectionURL">jdbc:derby:InventoryDB</config-property-setting> <connectionmanager> <local-transaction/> <single-pool> <max-size>10</max-size> <min-size>0</min-size> <match-one/> </single-pool> </connectionmanager> </connectiondefinition-instance> </connection-definition> </outbound-resourceadapter> </resourceadapter> </connector>

Let's consider the following code segment which starts with <enviornment> segment.

xmlsolid <connector xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.1"> <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1"> <dep:moduleId> <dep:groupId>console.dbpool</dep:groupId> <dep:artifactId>InventoryPool</dep:artifactId> <dep:version>1.0</dep:version> <dep:type>rar</dep:type> </dep:moduleId> <dep:dependencies> <dep:dependency> <dep:groupId>geronimo</dep:groupId> <dep:artifactId>system-database</dep:artifactId> <dep:type>car</dep:type> </dep:dependency> </dep:dependencies> </dep:environment>

The above piece of code is an excerpt from the InventoryPool.xml plan. Note that the <environment> root tag's under the comment references the groupID is set to console.dbpool and the artifactID is set to the "InventoryPool" which are the reference used by geronimo-web and web.xml to expose this connection pool as a datasource to the application.Note that each tag includes the "dep:"prefix which can replace with any meaningful prefix or just omit the prefix.

2.7 Security settings

The security element maps security roles declared in the web.xml deployment descriptor to specific users or groups in the security realms configured in Geronimo. The user can specify a default user or group to be used when the end user has not yet logged in.

2.7.1 Security realm sample

There is a Web application security sample already under sample applications.Considering the implementation of the security of geronimo-web.xml, this describes how to add a security setting in a web app.

xmlsolidWEB-INF/web.xml <?xml version="1.0" encoding="UTF-8"?> <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"> <welcome-file-list> <welcome-file>index.jsp</welcome-file> </welcome-file-list> <security-constraint> <web-resource-collection> <web-resource-name>employee</web-resource-name> <url-pattern>/employee/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>employee</role-name> </auth-constraint> </security-constraint> <security-constraint> <web-resource-collection> <web-resource-name>manager</web-resource-name> <url-pattern>/manager/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>manager</role-name> </auth-constraint> </security-constraint> <login-config> <auth-method>FORM</auth-method> <realm-name>TimeReportRealm</realm-name> <form-login-config> <form-login-page>/login/login.jsp</form-login-page> <form-error-page>/login/login_error.jsp</form-error-page> </form-login-config> </login-config> <security-role> <role-name>employee</role-name> </security-role> <security-role> <role-name>manager</role-name> </security-role> <servlet> <display-name>AddTimeRecordServlet</display-name> <servlet-name>AddTimeRecordServlet</servlet-name> <servlet-class>org.timereport.web.employee.AddTimeRecordServlet</servlet-class> </servlet> <servlet> <display-name>AddEmployeeServlet</display-name> <servlet-name>AddEmployeeServlet</servlet-name> <servlet-class>org.timereport.web.manager.AddEmployeeServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>AddTimeRecordServlet</servlet-name> <url-pattern>/employee/add_timerecord</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>AddEmployeeServlet</servlet-name> <url-pattern>/manager/add_employee</url-pattern> </servlet-mapping> </web-app> xmlsolidgeronimo-web.xml <?xml version="1.0" encoding="UTF-8"?> <web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.1"> <environment> <moduleId> <artifactId>TimeReportApp</artifactId> </moduleId> </environment> <context-root>/timereport</context-root> <security-realm-name>TimeReportRealm</security-realm-name> <security> <default-principal realm-name="TimeReportRealm"> <principal name="anonymous" class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal" /> </default-principal> <role-mappings> <role role-name="employee"> <realm realm-name="TimeReportRealm"> <principal name="EmployeeGroup" class="org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal" /> </realm> <realm realm-name="TimeReportRealm"> <principal name="ManagerGroup" class="org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal" /> </realm> </role> <role role-name="manager"> <realm realm-name="TimeReportRealm"> <principal name="ManagerGroup" class="org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal" /> </realm> </role> </role-mappings> </security> </web-app>

In geronimo-web.xml the security realm has implemented starting from the security-realm-name segment. Each element is describe below with an explanation of what each element does.

security-realm-name: The name of the Geronimo security realm that will authenticate user logins. This should match the name specified for the security realm GBean and in this example it's value is "TimeReportRealm"

security: Groups the security role mapping settings for the Web application.

security:doas-current-caller: This can be true or false. If set to true, any work done by the Web application will be performed as the calling Subject, instead of "as the application server". This can be used to hook into the Java JVM security sandbox (for example, to only allow trusted users to access the server filesystem). It is not usually necessary, as the application-level security features are typically sufficient. When it is enabled, you may want to adjust the security policy used for the server to control certain permissions by subject. This element is optional and the default is false.

security:use-context-handler: May be true or false. The default is false, but advanced JACC users may enable it to insert their own code in the JACC processing chain.

security:default-role: This attribute is not applicable to Web applications.

default-principal: This element holds a principal which will be used any time an unauthenticated user accesses an unsecured page. Normally this would result in no principal being used, but you can specify a default here.

role-mappings: This element holds the information mapping roles declared in the web.xml deployment descriptor to specific principals present in the security realms available to Geronimo.

role: This element holds the set of principals that map to a single role from web.xml.

NOTE
This document has covered many areas in deploying web applications in geronimo.But there are plenty of areas need to be covered and improved.Comments,thoughts and contributions are always welcome to improve this documentation.