This article will be an introduction to understand the geronimo deployment plan to the uer in different web application development areas.Though geronimo deployment plan for web application is a wide broad topic to discuss,this article has set the following scope to the document at this level while tuning to cover more topics in the future.
This article is organized into the following sections : -
- #Describing the geronimo-web deployment plan
- #Work out Deployment Plans with Sample
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 :
<?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 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
- Module ID 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.
Excerpt from the sample application below
<dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1"> <dep:moduleId> <dep:groupId>geronimo</dep:groupId> <dep:artifactId>HelloWorld</dep:artifactId> <dep:version>1.1</dep:version> <dep:type>war</dep:type> </dep:moduleId> </dep:environment>
Once you deploy the application, the HelloWorld.war application will be created in <geronimo_home>/deploy/ directory.
<context-root>/hello</context-root>
To access the deployed sample the following url needs to be accessed. This url means the context root value to access the application.
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.
Web application identity and class 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.
Web application:Deployment path
The elements here are:
ModuleId : A moduleID uniquely indentifies 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. 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.
Web application: context root
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.
Web Application: Binding to Specific Ports
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.There are set of elements need to be set for such binding to specific ports.
web-container
When using this element then it indicates that this web application should be deployed to the specified web container, instead of to the default web container.Since there is only one web container configured by default and it's 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)
Work out deployment plans with sample
This section will cover how to deploy various web applications which use different Geronimo server resources and external resources.This section is started wilth the Helloworld sample web application which eleborates the basic requirments 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.Under this it has taken the examples from the deployment plans of existing samples in the sample applications section and widely discussed.
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.
Deployment plan for HelloWorld WAR module
This section covers how the deployment plan works for 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:
- Create a folder in called <app_home> in your working directory.
- Open up a new text file and save it as "HelloWorld.jsp" in side the app_home directory.
- Copy and past the following code for the "HelloWorld.jsp" in it.
HelloWorld.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> - Create a new folder called"WEB-INF" inside the <app_home>.
- 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.
- Copy and paste the following xml code in that file and save it inside the <app_home\WEB-INF> directory.
geronimo-web.xml
<?xml version="1.0" encoding="UTF-8"?> <web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.1"> <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1"> <dep:moduleId> <dep:groupId>geronimo</dep:groupId> <dep:artifactId>HelloWorld</dep:artifactId> <dep:version>1.1</dep:version> <dep:type>war</dep:type> </dep:moduleId> </dep:environment> <context-root>/hello</context-root> </web-app> - Open up a another new text file save it in <app_home\WEB_INF> directory and name it as "web.xml"
- Copy and Paste the following xml code in it and save.
<?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>
Resolving references in Geronimo-web
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 following references are available:
- EJB references
- GBean references
- DBPools
- Resource references
- Message destination references
The following resource reference will be discussed in the future :
- Web services 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.
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.
Web Application: Common References
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
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.
GBean reference example
<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>
Accessing the GBean from the Web application
%@ 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>
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 .For the EJB reference with the current application dose not use the above applications and only ejb-link element would do the needful once it used in the standard J2EE deployment descriptor and there is no necessary of geronimo-specific configuration for it.
Since EJBs requiring mapping are usually in a different application, 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 shouldn't be worry about arguments being copied in some cases and passed by reference in others
EJB reference example
This section will describe an example how to refer an EJB from geronimo-web.xml. The the completed sample can be downloaded here.
<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>
<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>
Accessing the EJB from the Web application
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();
}
}
Referring JMS in Web Application
This section will refer the sample application in MDB and JMS implementation sample(place the link for the JMS and MDB sample.In the sample itself 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
<?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 also it's set values to the child element of it with in 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
<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 has been done to refer this JMS resource.It's required to be avaliable the JMS supporting resource of the geronimo server in the deployment plan itself.Therefore the dependencies are set as follows which makes the resource available to the application.
<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 excerption of the deployme plan this dependency physcially located in <geronimo-home>/repositories/geronimo/activemq-broker/1.1.1/activemq-broker-1.1.1.car
Also the following piece of code excerption present 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 are carrying the name of the resource created in the Geronimo server.Therefore OrderQueue is the Queue created and deployed in the server.
<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>
Referring Database connection pools from Web Applications
This section will describe how to refer Data base pools in web applications. This is describing using "Simple database access sample application" and it's data base pool deployment plan.Application defines a datasource with the help of geronimo-web.xml and web.xml files. geronimo-web.xml add a link between the database pool already deployed in the server. It refers 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 Data base pool connection which has created for this sample application.Also the dependencies are set to console.dbpool as the groupId and InventoryPool as the artifacId of it.InventoryPool is the name of the Database connection plan.All of the work mentioned earlier is not enough to give and reference to a Data base and it shouled be followed by the resource reference tags in the geronimo-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>
Following is the web.xml of the Inventory application. It uses same name as in the geronimo-web.xml, which is used to create the datasource.
<?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 it has described the steps to create the connection pool.
<?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>
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.
Security realm sample
There is a Web app security sample already under sample applications.Considering the implementation of the security of geronimo-web.xml, it has been described how to add a security setting in a web app(K-Please link this with sample application web app security)
<?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>
<?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 bellow in the sense 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.