Table of Contents for Deployment plans for Geronimo V1.1
This article is organized into the following sections : -
- #Introduction
- #Apache Geronimo v1.1 deployment plans
- Work out Deployment Plan with Samples (I will include the completed samples here)
- Deploying and Undeploying Simple HelloWorld (war module,web.xml,geronimo-web.xml)
- Deploying and Undeploying AddressBook(JAR containing EJB ,ejb-jar.xml,openejb.xml)
Introduction
Every service, application or resource in Geronimo is configured with an xml deployment plan. Deployment plans are the Geronimo version of the J2EE deployment descriptors. They are still XML files based on XML schemas and containing the configuration details for a specific application module. Via the deployment plans you can not only deploy application modules but also other configurations such as a security realm, see the Deploying secure applications and Deploy the LDAP realm sections for further details and examples.
Apache Geronimo v1.1 deployment plans
The following table illustrates the deployment descriptors name and file location for both standard J2EE and Apache Geronimo specific.
File |
Standard Deployment Descriptors in the J2EE specification |
Apache Geronimo specific Deployment plan |
|---|---|---|
Web Application Archive (WAR) |
web.xml under the WEB-INF directory |
geronimo-web.xml |
Enterprise Web application archive (EAR) |
application.xml |
geronimo-application.xml |
J2EE Connector resources archive (RAR) |
ra.xml |
geronimo-ra.xml |
J2EE client application archive (JAR) |
client.xml |
geronimo-application-client.xml |
JAR containing EJBs |
ejb-jar.xml under the META-INF directory |
openejb-jar.xml |
Work Out Deployment Plans with Sample
Assumptions
It's assumed that you have installed either tomcat or jetty version of Geronimo V1.1 successfully and it is working. Please find the further details to get the software and install it in user guide.(need to direct the link to Installation Guide and the User Guide)
Deployment plan for WAR Module
This is a simple "HelloWorld" JSP sample application which prints hello world.Also this section will cover 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.
Here are the steps to understand the deployment plan for the "HelloWorld" Example:
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.
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>
4.Create a new folder called"WEB-INF" inside the app-home.
5.Open up new text file and save it as "geronimo-web.xml"(use simple letters)and this is the apache geronimo1.1deployment 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> directcory.
<?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>
7.Open up a another new text file save it in <app_home\WEB_INF> directory and name it as "web.xml"
8.Copy and Paste the following xml code in it and save.
web.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>
Describing the Geronimo deployment plan
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)
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.
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's Tomcat then, http://geronimo.apache.org/xml/ns/j2ee/tomcat-1.1.Therefor 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 module IS for itself using moduleID element and can delcare dependencies using the dependency element.
<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>
In this simple example once you deployed the application the
HelloWorld.war application will be created in <geronimo_home>/deploy/
<context-root>/hello</context-root>
To access the deployed sample it's required to access the following
url. This url means the context root value to access the application.
Web Application Deployment Plan Overview
As usual there is an specific internal structure of the web application deployment plan for geronimo as well.In the web application Deployment Plans follows a specific structure and order of elements.
1.2.1 Web Application Identity and Class Path
The Deploy tool and the console refers the web application by the name of the name defined in the moduleID and the elements of the deployment plan configure its class path.
Figure 1.2.2 Web Application: Class Path Settings
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 module ID.The moduleId creates a unique name for the web application. If no module ID is 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
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 can't 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 artifact ID should be unique with in the group.If no group is specified
when declaring the module ID for a module or application,it will get the group ID defualt.If no group is specified for a moduleID used to identify a dependency,It's 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 a single group ID for an application,with separate artifact IDs for the web application and EJB modules that make up that application.Every module ID must include and explicit artifact ID.If no module ID at all is specified when deploying a module,the artifact ID Details to the files name of the module file.
Version : Each module has a version number.If version number is specified when decaring the module ID 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 module ID used to identify a dependency,it means that any available version will be used.If there 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 deplorer 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 is that 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 that one of its parent configurations (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 comma-separated list of packages 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.2.3 Web Application Context Root
This element controls the URL that clients use to access the web application:
Figure 11.3. Web Application: Context Root
context-root
The context root is the first segment of the URL used to access the web application. 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.
Deployment plan for geronimo-application.xml and openejb-jar.xml
The following sample is an Email address book which covers how to deploy the J2EE Applications on computer running Apache Geronimo V1.1.AddressBook samples has used JSP,Struts EJB and mysql as the data base.Here It's assumed that you have the basic knowledge and experience of playing with EBJ a,JSP and servlets with other application servers.
AddresBook samples use JSP primarily for presentation logic and the HTML code.Servlets form the controller layer of a typical Model-View-Controller(MVC)architecture serve as an interface between the presentation and the model layers.
The three tire architecture and layers are shown in the picture.
Following diagram shows how the code is organized in the application
AddressBook
|_org.apache.geronimo.sample.addressbook.ejb
| |_AddressBookEntryBean.java
| |_AddressBookSessionBean.java
|_org.apache.geronimo.sample.addressbook.struts
| |_AddressBookEntryForm.java
| |_CreateEntry.java
| |_EditEntry.java
| |_ListAddress.java
| |_SaveEntry.java
|_org.apache.geronimo.sample.addressbook.pages
| |_EditAddressBook.jsp
| |_footer.jsp
| |_ListAddressBookPage.jsp
| |_navigation.jsp
| |_site-template.jsp
|
|_resource
|_ear
| |_META_INF
| | |_application.xml
| | |_geronimo-application.xml
| |_mysql-plan.xml
| |_tranql-connector-1.0-SNAPSHOT.rar
|
|_ejb
| |_META_INF
| |_openejb-jar.xml
|_merge
| |_README.txt
| |_servlets.xml
| |_servlets-mappings.xml
| |_struts-controller.xml
| |_strust-data-sources.xml
| |_struts-forms.xml
| |_struts-plugins.xml
| |_taglibs.xml
|
|_webapp
|_images
|_pages
|_style
|
|_WEB_INF
| |_classes
| | |_resources
| | |_application.properties
| |_conf
| | |_struts-config.xml
| | |_validation.xml
| |
| |_tld
| |_geronimo-jetty.xml
| |_tiles-defs.xml
| |_validator-rules.xml
|_index.jsp
JSP and Struts
The Struts action classes are in the AddressBook/src/org/apache/geronimo/sample/addressbook/struts directory. The JSPs are in the AddressBook/src/webapp/pages directory.
EJB
Apache Geronimo uses OpenEJB as the EJB container system. The example contains two EJBs:
Container-managed entity EJB
Stateless session EJB
Deploying an Application-Scoped Connection Pool
An Application scoped connection pool is visible only to the application that deployed it.To deploy an application-scoped connection pool,you need to follow these steps.
1.Specify the connector module in the application deployment descriptor.
2.Specify the connector deployment plan in the geronimo-Specfic application deployment descriptor.
3.Package the application EAR.
Specify the the Connector Module in the Application Deployment Descriptor
The Application deployment descriptor(AddressBook/resources/ear/META-INF/application.xml)should define the TranQL connector module,as shown here.
<application
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/application_1_4.xsd"
version="1.4">
<module>
<ejb>addressbook-ejb.jar</ejb>
</module>
<module>
<web>
<web-uri>addressbook.war</web-uri>
<context-root>/addressbook</context-root>
</web>
</module>
<module>
<connector>tranql-connector-1.1.rar</connector>
</module>
</application>
NOTE : It's a must to package the connector RAR file along with the application EAR file.
Specify the Connector Deployment Plan in the Geronimo Application Deployment Descriptor
Specify the connector deployment plan file in the Geronimo application deployment Descriptor(AddressBook/resources/ear/ear/META-INF/geronimo-application.xml)as shown here.