Setting up Tomcat with OpenEJB -- Leveraging J2EE JNDI principles

|  |  |  | OpenEJB OpenJMS OpenORB Castor Tyrex |

Main
Welcome!
Download
Mailing Lists
The Team

Users
Quickstart
Hello World!
CMP Example
CMP Guide
Deploy
Startup
Validation
Configuration
Support
Request Feature
FAQ

Servers
Local Server
Remote Server
Tomcat

Integrators
Why OpenEJB
Overview
Design
Specification
Presentation

Developers
Custom Services
Release Plan
Source Code
SourceForge

Setting up Tomcat with OpenEJB Leveraging J2EE JNDI principles

Abstract
Before we start
Referencing EJBs in web application
Installing OpenEJB's EJB factory in Tomcat
Example application

## Abstract

Java 2 Enterprise Edition (J2EE) provides several technologies that lets build J2EE-compliant applications that can be run in any J2EE-compliant application server. One of the several technologies is Java Naming and Directory Interface (JNDI). JNDI is a technology that provides a unified access to different naming and directory services. Regardless of the underlaying service, if it supports JNDI a client doesn't have to know what exactly application it's to talk to other than it adheres to JNDI concepts and interfaces.

OpenEJB and Tomcat can complement each other in fullfiling J2EE principles. OpenEJB is an EJB container whereas Tomcat is a servlet container. Although they serve different clients, both products use JNDI extensively. Obviously, either container provides different JNDI "views" of its managed components. The question pertaining to the integration is how to tie the different naming systems so that when a client requests an object from Tomcat naming space, Tomcat will know that it needs to pass the request along to OpenEJB naming space. That's what the object factory is to solve out.

While reading JNDI specification you can come across the interface: javax.naming.spi.ObjectFactory. The javadoc of the interface reads:

This interface represents a factory for creating an object.
The JNDI framework allows for object implementations to be loaded in dynamically via object factories. For example, when looking up a printer bound in the name space, if the print service binds printer names to References, the printer Reference could be used to create a printer object, so that the caller of lookup can directly operate on the printer object after the lookup.

Theorically, it seems to be possible to create a web application that makes use of EJBs, deploy these EJBs in OpenEJB, and the web application in Tomcat, set up an object factory and finally boot it up. The following sections are to outline what exactly the steps are in OpenEJB and Tomcat with description of why they are required at all.

## Before we start

Before we start, ensure that OpenEJB and Tomcat are in appropriate releases.

NOTE

What follows should be doable on any Tomcat 4.x release. The author tested it under Jakarta Tomcat 4.1.18 (the most recent public release at that time).

NOTE

It's assumed that Tomcat and OpenEJB are already installed and running properly as a separate products.

## Referencing EJBs in web application

J2EE 1.3 specification says (page 57):

The Application Component Provider must declare all the EJB references using the ejb-ref elements of the deployment descriptor. This allows the consumer of the application component's jar file (the Application Assembler or Deployer) to discover all the EJB references used by the application component.

It means that each time a web application needs to reference a bean, the bean has to be declared in the web application's deployment descriptor ( /WEB-INF/web.xml file). The element which does so is ejb-ref. Although most containers don't enforce that approach, it's always better to describe dependencies in a standard, J2EE-compliant way, in the deployment descriptor of the corresponding components.

NOTE

Tomcat won't refuse to activate the components even if they reference EJBs with no declaration in the deployment descriptors.

Our example's web application declares the referenced bean in the deployment descriptor ( /WEB-INF/web.xml) as follows:

    <ejb-ref>
        <description>
            EJB Reference to the bean deployed to OpenEJB
        </description>
        <ejb-ref-name>ejb/hello</ejb-ref-name>
        <ejb-ref-type>Session</ejb-ref-type>
        <home>org.acme.HelloHome</home>
        <remote>org.acme.Hello</remote>
    </ejb-ref>

Here goes a JSP that uses the ejb-ref-name to get a reference to the declared bean.

openejb.jsp

    <%@ page import="org.acme.HelloObject,
                     org.acme.HelloHome,
                     javax.naming.InitialContext,
                     javax.naming.Context"%>

    <html>
    <head>
    	<title>OpenEJB -- EJB for Tomcat</title>
    </head>

    <body>
    <%
        Context initCtx = new InitialContext();

        Object object = initCtx.lookup("java:comp/env/ejb/hello");
        HelloHome helloHome = (HelloHome)
                javax.rmi.PortableRemoteObject.narrow(object, HelloHome.class);
        HelloObject bean = helloHome.create();
    %>
    <%= bean.sayHello() %>
    </body>
    </html>

As it's shown in the sample JSP above, there is no direct reference to the EJB container to be used. The application component provider doesn't have to know what container the EJB is to be deployed to. What it does have to ascertain is that the name the JSP uses is actually an ejb reference. Moreover, the reference should be the one to HelloHome home interface or otherwise the application will fail.

## Installing OpenEJB's EJB factory in Tomcat

NOTE

CATALINA_HOME environment variable points to the directory where Jakarta Tomcat 4.x has been installed.

The J2EE 1.3 specification says (page 56):

The Deployer binds the EJB references to the enterprise bean's homes in the target operational environment.

It means that after an Application Component Provider (in the document, it's you) has created a web application and specified an EJB reference in the deployment descriptor, a deployer (you, too) has to bind the reference in Tomcat. The task boils down to put appropriate entry in Tomcat's configuration file.

Tomcat's default configuration file is server.xml in $CATALINA_HOME/conf directory. According to server.xml's documentation it's possible to create an appropriate definition of a factory and let the factory to handle requests for the objects it is registered to handle. That's what OpenEJB's EJB factory does. It intercepts messages for EJBs, passes it along to OpenEJB and returns requested bean.

Tomcat registers resource factories in GlobalNamingResources or Context elements which demarcate the name space of different web applications.

NOTE

It's recommended to place resource definitions within Context elements, which prevents name clashes to occur when the same names are to point to different resources (e.g. EJBs).

The following snippet shows the elements necessary to register the EJB reference, which has been defined in the web application's deployment descriptor. The document doesn't describe the particular elements of server.xml file other than ResourceParams parameters. The reader shall read the Tomcat documentation to get acquainted with the file's structure.

$CATALINA_HOME/conf/server.xml

    <Server>
        ...
        <Context path=...>
            ...
            <Ejb name="ejb/hello"
                 type="Session"
                 home="org.acme.HelloHome"
                 remote="org.acme.Hello"/>
            <ResourceParams name="ejb/hello">
                <parameter>
                    <name>factory</name>
                    <value>org.openejb.client.TomcatEjbFactory</value>
                </parameter>
                <parameter>
                    <name>openejb.naming.factory.initial</name>
                    <value>org.openejb.client.LocalInitialContextFactory</value>
                </parameter>
                <parameter>
                    <name>openejb.naming.security.principal</name>
                    <value>username</value>
                </parameter>
                <parameter>
                    <name>openejb.naming.security.credentials</name>
                    <value>password</value>
                </parameter>
                <parameter>
                    <name>openejb.naming.provider.url</name>
                    <value>localhost:4201</value>
                </parameter>
                <parameter>
                    <name>openejb.ejb-link</name>
                    <value>Hello</value>
                </parameter>
            </ResourceParams>
        </Context>
        ...
    </Server>

ResourceParams parameters consitute a bean reference. They inform Tomcat about who will know how to handle requests for the bean.

| factory - (mandatory) the class instantiated by Tomcat when a request for a bean has arrived; it must be org.openejb.client.TomcatEjbFactory if the request ought to be handed over to OpenEJB.

openejb.naming.factory.initial - (mandatory) OpenEJB JNDI InitialContext implementation; the parameter may be assigned to one of the two values:

| org.openejb.client.LocalInitialContextFactory - OpenEJB is started in the same JVM as Tomcat; it boosts performance drastically as the beans are in the same JVM as a client (e.g. a web application); it boots up OpenEJB in the local mode - an Local (aka IntraVM) Server instance
| org.openejb.client.RemoteInitialContextFactory - OpenEJB is started outside of the current JVM; all calls are forwarded to a OpenEJB Remote Server instance

| openejb.ejb-link - (mandatory) the bean's name to be looked up in OpenEJB; the name doesn't have to be the same as the reference's name in Tomcat; it's the name the bean may be found in OpenEJB JNDI name space.

The following parameters are only required when openejb.naming.factory.initial is set to org.openejb.client.RemoteInitialContextFactory.

| openejb.naming.security.principal - the name of the user who is allowed to access the JNDI context
| openejb.naming.security.credentials - the password of the user who is set up in openejb.naming.security.principal parameter
| openejb.naming.provider.url - the server and port OpenEJB handles remote requests

The factory parameter indicates the class which passes a request for a bean to OpenEJB instance. In order for the class to be instantiated by Tomcat, OpenEJB Loader has to be installed. The Loader takes care of loading necessary classes from OpenEJB directory. It finds the directory relying upon OPENEJB_HOME environament variable.

Create a file named setenv.sh (or setenv.bat on MS Windows) in $CATALINA_HOME/bin directory with the following content:

$CATALINA_HOME/bin/setenv.sh

    export CATALINA_OPTS="-Dopenejb.home=$OPENEJB_HOME"

Finally, add the OpenEJB Loader to Tomcat.

    $ cp $OPENEJB_HOME/dist/openejb_loader-0.9.0.war webapps/

That's it. Tomcat is now fully configured to work with OpenEJB. Don't forget to start up OpenEJB instance if the factory's been configured with RemoteInitialContextFactory.

## Example application

You can use the OpenEJB Hello World as an example EJB to test things out. You won't need to do anything differently. Deploy the myHelloEjb.jar just as described in http://openejb.sourceforge.net/hello-world.html

Register the factory in Tomcat by editing server.xml, i.e. add the above Ejb element declaration between Context's tags of Tomcat's default example web application. Place the JSP - openejb.jsp - in $CATALINA_HOME/webapps/examples directory.

Start up Tomcat and enter http://localhost:8080/examples/openejb.jsp. As a result, you should see "Hello World!!!!!" on the screen.

Tomcat should print out the following on its console (note OpenEJB messages about its startup):

    Using CATALINA_BASE:   C:\_Jacek\apps\jakarta-tomcat-4.1.18
    Using CATALINA_HOME:   C:\_Jacek\apps\jakarta-tomcat-4.1.18
    Using CATALINA_TMPDIR: C:\_Jacek\apps\jakarta-tomcat-4.1.18\temp
    Using JAVA_HOME:       C:\_JACEK\APPS\JDK1.3.1
    [INFO] Registry - -Loading registry information
    [INFO] Registry - -Creating new Registry instance
    [INFO] Registry - -Creating MBeanServer
    [INFO] Http11Protocol - -Initializing Coyote HTTP/1.1 on port 8080
    Starting service Tomcat-Standalone
    Apache Tomcat/4.1.18
    OpenEJB 0.9.0    build: 20030118-2205
    http://openejb.sf.net
    [INFO] Http11Protocol - -Starting Coyote HTTP/1.1 on port 8080
    [INFO] ChannelSocket - -JK2: ajp13 listening on 0.0.0.0/0.0.0.0:8009
    [INFO] JkMain - -Jk running ID=0 time=30/241
        config=C:\_Jacek\apps\jakarta-tomcat-4.1.18\conf\jk2.properties

Java, EJB, JDBC, JNDI, JTA, Sun, Sun Microsystems are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and in other countries. XML, XML Schema, XSLT and related standards are trademarks or registered trademarks of MIT, INRIA, Keio or others, and a product of the World Wide Web Consortium. All other product names mentioned herein are trademarks of their respective owners.