![Close [x]](http://dw1.s81c.com/i/c.gif){kind=small}
Apache Jakarta Tomcat has long been the reference container implementation for the latest servlets and JSP specifications. Throughout its illustrious open-source tenure, it has also been adopted by users worldwide as a production-grade, Web-tier engine, working in conjunction with industry-standard Web servers, such as the Apache Web server or the Microsoft® IIS. The great news is that the latest version of the Tomcat 5 engine is bundled standard with Geronimo, ready for activation.
Although it's an integrated part of Geronimo, the current architecture doesn't allow both Jetty and Tomcat to handle the Web tier concurrently. Instead, Jetty is the default JSP and servlet engine, and you need to make configuration changes to activate Tomcat in place of Jetty.
This article shows you how to enable and configure the Tomcat server inside Geronimo. You'll see how Geronimo's componentized architecture simplifies Tomcat's integration, and get some hands-on experience deploying the sample Web application to Tomcat. Last, but not least, you'll learn how to leverage the Geronimo/Tomcat integration to add a Tomcat Java™ Authentication and Authorization Service (JAAS) security realm to the sample applications that use Geronimo's container-based JAAS support.
Geronimo's architecture revisited
Tomcat is integrated into Geronimo as an alternate Web-tier container. To understand how Tomcat integrates with Geronimo, you should briefly revisit Geronimo's GBeans-based architecture. Get a background on this architecture in the article, "Geronimo! Part I: The J2EE 1.4 engine that could" (developerWorks, May 2005).
The Geronimo container assists in managing the lifecycle and run time interactions of software components called GBeans. At run time, the Geronimo kernel brings to life prefabricated groups of GBeans, known as configurations (see sidebar Geronimo GBeans and configurations). Configurations are fabricated during the deployment process. Conceptually, the deployer takes binary code for the GBeans (in the form of code modules) and metadata information (in the form of XML deployment plans), and then processes them to create a serialized image of the configuration. This configuration image is then persisted to a configuration store. The kernel deserializes the image when the configuration is started.
Figure 1 illustrates how Geronimo configurations are created at deployment time and started by the kernel at run time.
Figure 1. Deployment and execution of Geronimo configurations
In Figure 1, you can see that the deployer works by calling specialized builder components. The primary role of a specialized builder is to encapsulate the knowledge of how to create a working Geronimo configuration from the metadata for a specific type of code module. (For example, a J2EE EAR builder will know how to create a Geronimo configuration from code modules and metadata contained within an enterprise application EAR file).
Figure 2 provides a close-up view of a Geronimo specialized builder in action.
Figure 2. Operation of a specialized builder
In Figure 2, the specialized builder processes incoming metadata (deployment plans) and configures the GBeans (code modules), creating as output a configuration that can be started by the kernel without further processing or configuration.
Depending on the type of code modules being deployed, the deployer calls on different specialized builders. For example, the deployer calls a Web module builder to process an incoming Web Applications aRchive (WAR) file. Figure 1 shows that a builder might require additional metadata (deployment plans) during its operation.
Looking at Figure 1, you can observe and deduce that:
- The Geronimo kernel/container is not J2EE specific; it works fundamentally with GBeans and configurations (see sidebar Geronimo GBeans and configurations).
- The Geronimo J2EE server is simply an assembly of specialized service configurations (Web tier, business tier, eis tier) and their associated specialized builders.
- You can add new configurations to Geronimo by creating the GBean code modules, the specialized builder(s), and the associated deployment plans.
It is the final point above that makes the integration of Tomcat into Geronimo straightforward.
Integrating the Tomcat Web module builder
When a WAR file is deployed with the Geronimo deployer, the deployer looks for a specialized Web module
builder to create the configuration. The default Geronimo deployer configuration has the JettyModuleBuilder
hard-wired for this purpose. One main task that you must perform to activate Tomcat
is to rewire the deployer to use TomcatModuleBuilder instead.
Figure 3 shows this situation.
Figure 3. Rewiring the deployer to use
TomcatModuleBuilder instead of the default JettyModuleBuilder
In Figure 3, the configuration created by TomcatModuleBuilder contains an embedded TomcatWebAppContext. This context will be used by the TomcatContainer to start the Web application during run time.
The Geronimo deployer(s) are configured by two deployment plans:
- j2ee-deployer-plan.xml
- j2ee-runtime-deployer-plan.xml
These deployment plans are stored in the modules/assembly/target/plans directory of the Geronimo source tree. If you look inside these deployment plans, there are extensive comments showing the Jetty references and dependencies that you need to comment out, as well as the Tomcat references and dependencies that you must uncomment. Follow these instructions carefully to replace Jetty with Tomcat. Note that you need to check out the source code of Geronimo to modify these plans. See Server configuration change requires rebuild for a discussion of the server rebuild procedure.
Configuring the Tomcat container
The server configuration file in classic Tomcat is called server.xml. It is typically found under the $CATALINA_HOME/ conf directory, where $CATALINA_HOME is the Tomcat installation directory. This configuration file describes a nesting of components that comprise the Tomcat server. See Listing 1 for a simple server.xml.
Listing 1. A simple server.xml Tomcat configuration file
<Server port="8005" shutdown="SHUTDOWN">
<Service name="MyService">
<Connector port="8090"/>
<Engine name="MyEngine" defaultHost="localhost">
<Host name="localhost" appBase="webapps"/>
</Engine>
</Service>
</Server>
|
In Listing 1, a single Host nested component is configured inside an Engine container component. The top-level Service component is configured with the Engine and an HTTP Connector component listening for incoming requests at port 8090. This is a typical minimal Tomcat configuration.
Translating server.xml to j2ee-server-tomcat.xml
Geronimo's Tomcat integration module creates wrapper GBeans for most Tomcat components. As a result, the server.xml (above) can be translated into a deployment plan that gives instructions on how to connect the GBean-based components together. This is done as part of the j2ee-server-tomcat.xml server deployment plan, shown in Listing 2.
Listing 2. Configuration of Tomcat container in j2ee-server-tomcat.xml
<gbean name="MyTomcatContainer" class="org.apache.geronimo.tomcat.TomcatContainer">
<attribute name="catalinaHome">var/catalina</attribute>
<reference name="engineGBean">
<name>TomcatEngine</name>
</reference>
<reference name="ServerInfo">
<module>org/apache/geronimo/System</module>
<name>ServerInfo</name>
</reference>
</gbean>
<gbean name="TomcatWebConnector" class="org.apache.geronimo.tomcat.ConnectorGBean">
<attribute name="initParams">
port=8090
</attribute>
<reference name="TomcatContainer">
<name>MyTomcatContainer</name>
</reference>
</gbean>
<gbean name="TomcatEngine" class="org.apache.geronimo.tomcat.EngineGBean">
<attribute name="className">org.apache.geronimo.tomcat.TomcatEngine</attribute>
<attribute name="initParams">
name=MyEngine
defaultHost=localhost
</attribute>
</gbean>
<gbean name="TomcatHost" class="org.apache.geronimo.tomcat.HostGBean">
<attribute name="className">org.apache.catalina.core.StandardHost</attribute>
<attribute name="initParams">
name=localhost
appBase=
workDir=work
</attribute>
<reference name="engineGBean">
<name>TomcatEngine</name>
</reference>
</gbean>
|
You can examine the j2ee-server-tomcat.xml file and see the default Tomcat server configuration. This plan is located in the modules/assembly/target/plans directory of the Geronimo source tree.
Other Tomcat-nested components (such as realms and valves) often appear in server.xml files. These components can be wired in the deployment plan in the same manner. The example in the Securing the Really Big Pet Store through the Geronimo JAAS realm section will show how to add a JAAS realm to the engine.
Run time wiring of Tomcat server component hierarchy
Figure 4 shows how the j2ee-server-tomcat.xml deployment plan is used to build the
TomcatContainer configuration that runs as part of the J2EE server assembly.
Figure 4. Configuration and deployment of a Tomcat container
In Figure 4, the GBeans wiring instructions (similar to Listing 2) are used to create the Tomcat server (org/apache/geronimo/Tomcat) configuration. This configuration results in the construction of the Tomcat components hierarchy, shown on the right side of the figure, by the Geronimo kernel during run time.
In summary, you must perform the following steps to enable Tomcat in place of Jetty:
- Download and install the Geronimo source code.
- Install Maven and Subversion; these tools are required to build the source code (see Resources).
- Modify the j2ee-deployer-plan.xml, j2ee-runtime-deployer-plan.xml, and j2ee-server-tomcat.xml files as detailed above.
- Build the custom Tomcat assembly using Maven; this can be done by invoking Maven in the modules/assembly directory of the Geronimo source tree.
- Start the server, making sure that you set the java.endorsed.dir system property (that is,
java -Djava.endorsed.dir=lib/endorsed -jar bin/server.jar). This is necessary because the current Geronimo release requires a JDK 1.4 JVM, and the XML processing libraries required by Tomcat is not included by default. - Start the Tomcat server configuration using the run time deployer if it's not started already (that is,
java -jar bin/deployer.jar deploy org/apache/geronimo/Tomcat).
See Server configuration change requires rebuild for the potential of having a preconfigured Tomcat assembly, delivered with a Geronimo release, in the future.
Tomcat application deployment descriptor and deployment plan
Once you have started Geronimo with Tomcat activated, you can start to deploy EAR and WAR files and have the Web-tier application components (such as JSPs and servlets) hosted by Tomcat.
Figure 5 shows the deployment descriptor and deployment plan for Web applications deployed to Tomcat.
Figure 5. Tomcat deployment descriptor and deployment plan
In Figure 5, the web.xml standard J2EE deployment descriptor is placed inside the deployed WAR file.
TomcatModuleBuilder processes this descriptor during the creation of the Web module configuration.
The geronimo-tomcat.xml file is a Geronimo-specific deployment plan,
and may be included in the
WAR file or supplied during deployment as shown in Figure 5.
This deployment plan is processed by the TomcatModuleBuilder
to create the context for the Web application.
Unlike the classic version of Tomcat, there is no default webapps directory
to hold all the applications. Each Web application runs in its own independent context. You will see a
geronimo-tomcat.xml plan later in the example.
Table 1 summarizes the deployment descriptor and deployment plans for Tomcat in Geronimo.
Table 1. Deployment descriptors and plans for Tomcat in Geronimo
| File name | Type | Equivalent Tomcat Configuration File | Description |
| web.xml | Standard J2EE deployment descriptor | web.xml | Standard descriptor for Web applications. This must be stored as part of the WAR file under the WEB-INF subdirectory. |
| geronimo-tomcat.xml | Geronimo-specific deployment plan | context.xml | Can be stored within the WAR file or supplied as input during deployment. This plan is optional; the Tomcat module will use a default plan if it is not supplied. |
| j2ee-server-tomcat-plan.xml | Geronimo-specific deployment plan for the Tomcat container itself | server.xml | This plan configures the Tomcat server instance within Geronimo. The plan has server-wide scope and applies to all hosts and applications running on the server. |
In Table 1, if you do not include a geronimo-tomcat.xml deployment plan when deploying a Web application, Geronimo uses a default plan. This default plan creates a Tomcat root context with the application name specified in web.xml or the base name of the WAR file (if the application name is not specified in web.xml).
Deploying an example application
The example uses code from the article, "Geronimo! Part 2: Tame this J2EE 1.4 bronco" (developerWorks, May 2005). The reallybigpet.war, located in the war_only/dist directory, is a Web application that contains:
- JSPs
- Servlets
- JSTL libraries
- A custom tag library
To deploy this Web application to Tomcat, first make sure the Tomcat configuration is started:
java -jar bin/deployer.jar start org/apache/geronimo/Tomcat |
Use system for user name and manager
for password when prompted. Then deploy the reallybigpet.war file:
java -jar bin/deployer.jar deploy reallybigpet.war |
This WAR file contains a web.xml deployment descriptor
inside. It's deployed without a custom geronimo-tomcat.xml deployment plan. The default one created by the TomcatModuleBuilder is
sufficient.
To test out the deployed Really Big Pet Store application, use a browser to access the URL http://localhost:8090/reallybigpet/store.cgi.
The builder created a default deployment plan with a context named reallybigpet. This context name is based on
the name of the WAR file.
Securing the Really Big Pet Store through the Geronimo JAAS realm
Inside Geronimo, Tomcat can take advantage of Geronimo's container-based JAAS support to implement a security realm. If you look into the default j2ee-tomcat-server.xml configuration file, you'll see that a Tomcat JAAS realm has been configured at the engine level, as shown in Listing 3. The engine reference to the JAAS realm is shown in bold.
Listing 3. Fragment of the default j2ee-tomcat-server.xml, showing the JAAS realm configured at the engine level
<gbean name="TomcatEngine" class="org.apache.geronimo.tomcat.EngineGBean">
<attribute name="className">org.apache.geronimo.tomcat.TomcatEngine</attribute>
<attribute name="initParams">
name=Geronimo
defaultHost=localhost
</attribute>
<reference name="realmGBean">
<name>TomcatJAASRealm</name>
</reference>
</gbean>
<gbean name="TomcatJAASRealm" class="org.apache.geronimo.tomcat.RealmGBean">
<attribute name="className">
org.apache.geronimo.tomcat.realm.TomcatJAASRealm</attribute>
<attribute name="initParams">
userClassNames=org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal
roleClassNames=org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal
</attribute>
</gbean>
|
To secure the Really Big Pet Store using this realm, you need to add a <security-constraint> element
to the web.xml. In the war_realm/dd directory of the sample code, you'll find the web.xml that contains
the security code. This web.xml file is shown in Listing 4. The security code is highlighted.
Listing 4. Deployment descriptor - web.xml using a JAAS realm to authenticate users
<?xml version="1.0" encoding="ISO-8859-1"?>
<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">
<description>
developerWorks Really Big Pet Store Example - for Geronimo
</description>
<display-name>IBM developerWorks Really Big Pet Store Example for Geronimo</display-name>
<servlet>
<servlet-name>ReallyBigPetStore</servlet-name>
<servlet-class>com.ibm.dw.reallybigpet.StoreController</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>ReallyBigPetStore</servlet-name>
<url-pattern>/store.cgi</url-pattern>
</servlet-mapping>
<security-constraint>
<display-name>Pet Store Security Constraint</display-name>
<web-resource-collection>
<web-resource-name>Entire store</web-resource-name>
<url-pattern>/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>admin</role-name>
</auth-constraint>
</security-constraint>
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>Pet Store Login</realm-name>
</login-config>
<security-role>
<role-name>admin</role-name>
</security-role>
</web-app>
|
The highlighted code in Listing 4 authenticates the user against the Geronimo container's default
JAAS provider before allowing access to the Web application. The authenticated user must be in the role/group
called admin. This default provider uses a set of properties files
located under the var/security directory. Only one group called admin is defined by default. This group
has only one user, with system as username and manager as password.
You can find this secured version of the Web application in the war_realm/dist directory, called petsecure.war. Deploy this to Tomcat using:
java -jar bin/deployer.jar deploy petsecure.war |
You can access the Web application using the URL: http://localhost:8090/petsecure/store.cgi
This time, a login dialog will be displayed for authentication. Access the store using system for user name and manager for password.
Deploying Web application to Tomcat with a custom deployment plan
Thus far, both of our Web applications have been deployed without a custom geronimo-tomcat.xml deployment plan. In this last example, you will deploy the reallybigstore.war with a custom plan.
The custom deployment plan is located in the custom_plan directory of the downloadable source (see Resources).
This plan, called custplan.xml, sets the configuration name to org/apache/geronimo/BigPetStore and sets the context
name for the application to /Shopping.:
Listing 5. A customized Geronimo-specific Tomcat deployment plan, custplan.xml
<web-app
xmlns="http://geronimo.apache.org/xml/ns/web/tomcat"
xmlns:sec="http://geronimo.apache.org/xml/ns/security"
configId="org/apache/geronimo/BigPetStore">
<context-root>/Shopping</context-root>
<context-priority-classloader>false</context-priority-classloader>
</web-app>
|
Before you deploy the application again, make sure you have undeployed the previous examples.
Deploy the Web application with the custom plan:
java -jar bin/deployer.jar deploy reallybigpet.war custplan.xml |
After deployment, you can access the application at its new context, via URL: http://localhost:8090/Shopping/store.cgi
If you use the deployer's list-modules command, you will see the deployed org/apache/geronimo/BigPetStore configuration.
Listing 6. Output of a deployer's list-modules command, after deployment with custplan.xml
java -jar bin/deployer.jar list-modules
Found 19 modules
org/apache/geronimo/Tomcat
org/apache/geronimo/ActiveMQServer
org/apache/geronimo/J2EEDeployer
org/apache/geronimo/DefaultDatabase
org/apache/geronimo/SpringDeployer
org/apache/geronimo/Secure
org/apache/geronimo/DebugConsole
org/apache/geronimo/Server
org/apache/geronimo/DeployerSystem
org/apache/geronimo/ClientSystem
org/apache/geronimo/SystemDatabase
org/apache/geronimo/Client
org/apache/geronimo/SpringRuntime
org/apache/geronimo/SystemJMS
org/apache/geronimo/RuntimeDeployer
geronimo-demo-1.0-SNAPSHOT
org/apache/geronimo/System
org/apache/geronimo/BigPetStore
org/apache/geronimo/RemoteClassLoadingDeployer
|
The Tomcat engine is included in the current Geronimo build, but requires manual editing of configuration files and rebuilding of the assembly to activate. Web applications containing JSPs, servlets, filters, and tag libraries can be deployed and executed against the Tomcat container. Tomcat-specific features, such as virtual hosts, realms, and valves, are available, while Geronimo services, such as JAAS, transaction, and Java Naming and Directory Interface (JNDI), are fully integrated. Using Tomcat with Geronimo gives you the best of two worlds -- combining the latest innovations of a manageable and scalable open source J2EE server with the robustness of a feature-rich, mature Web-tier container.
My sincere thanks to Jeff Genender, lead developer for Tomcat integration in the Geronimo team, for his valuable comments on drafts of this manuscript.
| Description | Name | Size | Download method |
|---|---|---|---|
| Web application deployable on Tomcat (or Jetty) | os-ag-tomcat_code.zip | 128 KB | HTTP |
Information about download methods
- Participate in the discussion forum.
- Read the two-part series on Geronimo. Part 1, "The J2EE 1.4 engine that could" is an introduction and conceptual overview to Geronimo, while Part 2, "Tame this J2EE 1.4 bronco" covers Geronimo configuration, deployment, management, and provides hands-on examples of deploying Web applications and EJBs. (developerWorks, May 2005).
- Download Gluecode Standard Edition, an open source application server based on Apache Geronimo.
- See the Geronimo wiki for the latest up-to-date information on Tomcat integration and deployment instructions.
- The official Apache Jakarta Tomcat Web site contains information on the latest available release of the Tomcat 5 server. Detailed configuration documentation is also available at this site. User support is available through the associated mailing lists.
- The official site for the Geronimo project has the latest source code and binaries and an active community on the mailing lists and wiki.
- Jetty is the default servlet and JSP container integrated with Geronimo. Visit the official Jetty site for more information.
- Geronimo uses Apache Maven to manage multiproject code builds and Apache Ant for individual project builds. Version control for most projects is managed using Subversion, and several projects are still on CVS.
- Get involved in the developerWorks community by participating in
developerWorks
blogs.
- Browse all the Apache articles and free Apache tutorials available in the developerWorks Open source area.
- Browse for books on these and other technical topics.
-
See the Geronimo project area for a complete listing of free open source resources from developerWorks.
Sing is a consultant and an active author with over two decades of industry experience. He has contributed to Beginning JavaServer Pages, Professional Apache Tomcat 5, Pro JSP - Third Edition, Early Adopter JXTA, Professional Jini, Beginning J2ME: From Novice to Professional, Third Edition, and numerous other books. Sing also writes for technical magazines and participates in open source communities. He is an evangelist of the open source, VOIP and P2P movements. You can reached Sing at westmakaha@yahoo.com.
Table of contents
Next steps from IBM
With the WebSphere Application Server you can benefit from the simplified EJB 3.0 development experience, new persistence model, and interceptors.
- Try: Download a free trial version of WebSphere Application Server Community Edition, the lightweight Java 5 application server with robust EJB 3.0 funtionality.
- Article: Learn how call patterns and components involved in making calls to EJB components deployed in the EJB container operate in WebSphere Application Server.
- Tutorial: This tutorials shows you how to create an enterprise J2EE application that implements both Plain Old Java Object (POJO) and EJB Web services endpoints.
- Demo: Watch this demo and learn how to configure and use the WebSphere Application Server and the Eclipse IDE with the Web Tool Project Platform.
- Buy: WebSphere Application Server
Tags
Use the slider bar to see more or fewer tags.
For articles in technology zones (such as Java technology, Linux, Open source, XML), Popular tags shows the top tags for all technology zones. For articles in product zones (such as Info Mgmt, Rational, WebSphere), Popular tags shows the top tags for just that product zone.
For articles in technology zones (such as Java technology, Linux, Open source, XML), My tags shows your tags for all technology zones. For articles in product zones (such as Info Mgmt, Rational, WebSphere), My tags shows your tags for just that product zone.
Popular article tags |
My article tagsSkip to tags list
Popular article tags |
My article tags
