Using OpenEJB 1.0 with Tomcat on Linux

This FlashGuideTM will get you started with OpenEJB 1.0. OpenEJB is developed by the OpenEJB Group and implements the 1.x J2EE specification. Its home page is http://openejb.org.

This FlashGuideTM covers three ways of accessing OpenEJB 1.0 from a web application:

  1. OpenEJB running as an external service
  2. OpenEJB embedded in Tomcat instance
  3. OpenEJB embedded in Tomcat web application ("per webapp implementation")

Follow Step 1 to install Tomcat 4 or Step 2 to install Tomcat 5.


1. Installing Tomcat 4 on Linux

  1. Download the latest Tomcat binary from the Tomcat 4 section of http://jakarta.apache.org/site/binindex.cgi. Currently, Tomcat 4.1.31 is the latest.
  2. Install Tomcat by unzipping/untaring the download file and placing in the desired directory (I used /usr/local) 
    cd /usr/local
tar zxf ./jakarta-tomcat-4.1.31.tar.gz
  3. Note the location of your Tomcat installation - we will refer to this as $CATALINA_HOME
  4. Optionally, save time on typing by creating a symbolic link like this: 
    ln -s jakarta-tomcat-4.1.31 tomcat4

2. Installing Tomcat 5 on Linux

  1. Download the latest Tomcat binary from the Tomcat 5 section of http://jakarta.apache.org/site/binindex.cgi. Currently, Tomcat 5.0.28 is the latest.
  2. Install Tomcat by unzipping/untaring the download file and placing in the desired directory (I used /usr/local) 
    cd /usr/local
tar zxf ./jakarta-tomcat-5.0.28.tar.gz
  3. Note the location of your Tomcat installation - we will refer to this as $CATALINA_HOME
  4. Optionally, save time on typing by creating a symbolic link like this: 
    ln -s jakarta-tomcat-5.0.28 tomcat5

3. Building OpenEJB on UNIX

Currently (as of 2/21/05), OpenEJB 1.0 is not yet available as a binary distribution. This should change shortly.

  1. Check your prerequisites:
    1. Make sure you have a Java Development Kit (JDK) installed, and the environment variable $JAVA_HOME set to the JDK installation directory. You should also have the $JAVA_HOME/bin directory in your $PATH. (For Windows users, make sure you have %JAVA_HOME set and %JAVA_HOME\bin in your %PATH
    2. Make sure you downloaded and installed Apache Maven from http://maven.apache.org per the installation instructions. Specifically, make sure you have the $MAVEN_HOME environment variable set.
  2. Find a directory where you want to download the OpenEJB 1.0 source code
  3. Download the source code with CVS: 
    cvs -d:pserver:anon@cvs.openejb.codehaus.org:/scm/openejb login
cvs -d:pserver:anon@cvs.openejb.codehaus.org:/scm/openejb co openejb1

    This will create a directory called "openejb1" with all the sources inside.

  4. Cd into the source distribution directory: 
    cd openejb1
  5. Now, run the build: 
    maven
  6. Once the build completes, the binary will be available in the target/openejb-1.0-SNAPSHOT/ directory. You might want to move it to a place with a shorter name: I moved mine to /usr/local/share/openejb1.
  7. Whether you leave the binary in place or move it, from now on we'll refer to its location as $OPENEJB_HOME. It won't hurt to set that as well.

4. Building OpenEJB Test Files

  1. Check your prerequisites:
    1. Make sure you have a Java Development Kit (JDK) installed, and the environment variable $JAVA_HOME set to the JDK installation directory. You should also have the $JAVA_HOME/bin directory in your $PATH. (For Windows users, make sure you have %JAVA_HOME set and %JAVA_HOME\bin in your %PATH
    1. Make sure you have Ant 1.5.1 or greater installed and $ANT_HOME set. If not, follow these steps:
      • Download the latest Ant (currently 1.6.2) from http://ant.apache.org/bindownload.cgi
      • Unpack the distribution in the desired directory (I used /usr/local)
      • Optionally, save time on typing by creating a symbolic link like this: 
        ln -s apache-ant-1.6.2 ant
      • Set $ANT_HOME in your environment (or in /etc/profile so you don't forget it next time) to point to the ant installation
      • Make sure $ANT_HOME/bin is in your $PATH
  2. Set up a build environment for the test. We will be creating three source files, one configuration file and one shell script. We'll call the development directory that contains all our files $DEVEL_HOME.
  3. Create the following, in some build area: 
    cd ~
mkdir openejbtest
export DEVEL_HOME=~/openejbtest
cd openejbtest
mkdir classes etc lib src
  4. Create an Ant buildfile a $DEVEL_HOME/build.xml: 
    <project default="build" basedir=".">
  <property name="openejb_home" value="/usr/local/share/openejb1"/>

  <path id="cp">
    <fileset dir="${openejb_home}/lib">
      <include name="*.jar"/>
    </fileset>
    <pathelement path="${java.class.path}"/>
  </path>

  <target name="prepare">
    <mkdir dir="classes"/>
    <mkdir dir="lib"/>

    <delete>
     <fileset dir="classes" 
       includes="**/*.class"/>
    </delete>

  </target>

  <target name="compile" depends="prepare">
    <javac srcdir="src" destdir="classes"
           debug="on" optimize="off" deprecation="off">
      <classpath refid="cp"/>
    </javac>
  </target>

  <target name="build" depends="compile">
    <jar jarfile="lib/simpletest.jar">
     <fileset dir="classes" 
       includes="**/*.class"/>
     <metainf dir="etc" includes="ejb-jar.xml"/>
    </jar>
  </target>

</project>

    You may have to change the location of the "openjms_home" property.

  5. Create the test EJB home interface class as $DEVEL_HOME/src/SimpleTestHome.java: 
    package test.j2ee;

public interface SimpleTestHome extends javax.ejb.EJBHome {
	
    SimpleTest create() throws java.rmi.RemoteException,
        javax.ejb.CreateException;
        
}
  6. Create the test EJB remote interface class as $DEVEL_HOME/src/SimpleTest.java: 
    package test.j2ee;

public interface SimpleTest extends javax.ejb.EJBObject {
  public String getDate() throws java.rmi.RemoteException;
}
  7. Create the test EJB class as $DEVEL_HOME/src/SimpleTestBean.java: 
    package test.j2ee;

import java.util.Date;
import javax.ejb.SessionContext;

public class SimpleTestBean implements javax.ejb.SessionBean {

    public void ejbCreate() {
    }

    public void ejbRemove() {
    }

    public void ejbActivate() {
    }

    public void ejbPassivate() {
    }

    public void setSessionContext(SessionContext ctx) {
    }

    public String getDate() {
        return new Date().toString();
    }
    
}
  8. Create the EJB descriptor file as $DEVEL_HOME/etc/ejb-jar.xml: 
    <?xml version="1.0"?>

<ejb-jar>

 <description>Test<description>

 <enterprise-beans>
  <session>
   <ejb-name>SimpleTest</ejb-name>
   <home>test.j2ee.SimpleTestHome</home>
   <remote>test.j2ee.SimpleTest</remote>
   <ejb-class>test.j2ee.SimpleTestBean</ejb-class>
   <session-type>Stateless</session-type>
   <transaction-type>Container</transaction-type>
  <session>
 <enterprise-beans>

</ejb-jar>
  9. Compile the sources. This will create the file $DEVEL_HOME/lib/simpletest.jar: 
    $ cd $DEVEL_HOME
$ ant
  10. Deploy the bean in OpenEJB 1.0: 
    $ cd $OPENEJB_HOME
$ bin/openejb deploy -a -m $DEVEL_HOME/lib/simpletest.jar

    This step will deploy the jar into OpenEJB. You'll find the jar in $OPENEJB_HOME/beans now.


5. Using an external OpenEJB from Tomcat

  1. Follow this step to access an external OpenEJB.
  2. Create a test JSP and place it under the appropriate directory in $CATALINA_HOME/webapps. To use the default "ROOT" Context, put your JSP in the $CATALINA_HOME/webapps/ROOT directory. Save the following as openejb.jsp: 
    <%@ page language="java" import="java.util.Properties, javax.naming.*,
 javax.ejb.CreateException,
 javax.ejb.RemoveException,
 java.rmi.RemoteException,
 javax.naming.NamingException,
 test.j2ee.*
"%>
 
<html>
 <head>
  <title>EJB Test</title>
 </head>

 <body>
  <br/> 
  <br/> 

  <center><h3>Test of the SimpleTestBean</h3><br/>

<%
   String output = "";

   try {
	Properties p = new Properties();
        p.put("java.naming.factory.initial", 
           "org.openejb.client.RemoteInitialContextFactory");
        p.put("java.naming.provider.url", "127.0.0.1:4201");

	javax.naming.InitialContext ctx = new javax.naming.InitialContext(p);
	Object obj = ctx.lookup("/SimpleTest");

	SimpleTestHome home = 
	   (SimpleTestHome)javax.rmi.PortableRemoteObject.narrow(obj, 
           SimpleTestHome.class);
	SimpleTest st = home.create();
	output = st.getDate();
	st.remove();
   } catch (NamingException e) {
        System.err.println("Naming exception occured during initialization"+ e);
           e.printStackTrace();
   }
%>

   <p>The SimpleTestBean said: <%= output %></p>

 </body>
</html>
  3. Copy two OpenEJB jars to the Tomcat common/lib directory: 
    $ cp $OPENEJB_HOME/lib/geronimo-spec-j2ee-1.4-rc3.jar $CATALINA_HOME/common/lib
$ cp $OPENEJB_HOME/lib/openejb-core-1.0-SNAPSHOT.jar $CATALINA_HOME/common/lib
  4. Copy the jar with our tests to the Tomcat common/lib directory: 
    $ cp $OPENEJB_HOME/beans/simpletest.jar $CATALINA_HOME/common/lib

    DO NOT put this jar file or its classes in the WEB-INF directory of your web application!! It will conflict with the copy in $CATALINA_HOME/common/lib and you will get the dreaded ClassCastException on the PortableRemoteObject.narrow method.

  5. Start OpenEJB: 
    $ cd $OPENEJB_HOME
$ bin/openejb start
  6. Start Tomcat: 
    cd $CATALINA_HOME/bin
./catalina.sh start
  7. Point your browser to http://[hostname]:[port]/[jspname], where "[hostname]" refers to the machine Tomcat is running on, "[port]" refers to the Tomcat HTTP port (8080 is the default), and "[jspname]" refers to the name (and application prefix, if necessary), of your test JSP. In my case, for example, I simply type in: http://localhost:8080/openejb.jsp.

6. Using OpenEJB embedded (intraVM) in Tomcat

  1. Follow this step to access OpenEJB embedded in a Tomcat instance.
  2. Stop Tomcat if its running: 
    cd $CATALINA_HOME/bin
./catalina.sh stop
  3. If you followed step 5, remove the OpenEJB jar from the Tomcat common/lib directory: 
    $ rm $CATALINA_HOME/common/lib/openejb-core-1.0-SNAPSHOT.jar
  4. If you followed step 5, it is best to remove the work directory for the web application you were using: I just removed the whole Tomcat work directory: 
    $ rm -Rf $CATALINA_HOME/work/Standalone
  5. If you did not already, copy the jar with our tests to the Tomcat common/lib directory: 
    $ cp $OPENEJB_HOME/beans/simpletest.jar $CATALINA_HOME/common/lib

    DO NOT put this jar file or its classes in the WEB-INF directory of your web application!! It will conflict with the copy in $CATALINA_HOME/common/lib and you will get the dreaded ClassCastException on the PortableRemoteObject.narrow method.

  6. Create a test JSP (or modify the one above) and place it under the appropriate directory in $CATALINA_HOME/webapps. To use the default "ROOT" Context, put your JSP in the $CATALINA_HOME/webapps/ROOT directory. Save the following as openejb.jsp: 
    <%@ page language="java" import="java.util.Properties, javax.naming.*,
 javax.ejb.CreateException,
 javax.ejb.RemoveException,
 java.rmi.RemoteException,
 javax.naming.NamingException,
 test.j2ee.*
"%>
 
<html>
 <head>
  <title>EJB Test</title>
 </head>

 <body>
  <br/> 
  <br/> 

  <center><h3>Test of the SimpleTestBean</h3><br/>

<%
   String output = "";

   try {
	Properties p = new Properties();
	p.put("java.naming.factory.initial", 
           "org.openejb.client.LocalInitialContextFactory");

	javax.naming.InitialContext ctx = new javax.naming.InitialContext(p);
	Object obj = ctx.lookup("/SimpleTest");

	SimpleTestHome home = 
	   (SimpleTestHome)javax.rmi.PortableRemoteObject.narrow(obj, 
           SimpleTestHome.class);
	SimpleTest st = home.create();
	output = st.getDate();
	st.remove();
   } catch (NamingException e) {
        System.err.println("Naming exception occured during initialization"+ e);
           e.printStackTrace();
   }
%>

   <p>The SimpleTestBean said: <%= output %></p>

 </body>
</html>
  7. Make a directory for the OpenEJB Loader web application in the Tomcat directory structure: 
    cd $CATALINA_HOME/webapps
mkdir openejb-loader

    You can actually call it anything you want.

  8. Unpack the OpenEJB Loader web application in the directory you just created: 
    cd $CATALINA_HOME/webapps/openejb-loader
jar xvf $OPENEJB_HOME/war/openejb-loader-1.0-SNAPSHOT.war
  9. Edit $CATALINA_HOME/webapps/openejb-loader/WEB-INF/web.xml and set the "openejb.home" parameter to point to your $OPENEJB_HOME. In my case, I have: 
        <init-param>
      <param-name>openejb.home<param-name>
      <param-value>usr/local/share/openejb1<param-value>
    <init-param>
  10. Start Tomcat: 
    cd $CATALINA_HOME/bin
./catalina.sh start

    OpenEJB will now be started by Tomcat as an embedded (intravm) service. You don't have to start OpenEJB from the $OPENEJB_HOME directory.

  11. Point your browser to http://[hostname]:[port]/[jspname], where "[hostname]" refers to the machine Tomcat is running on, "[port]" refers to the Tomcat HTTP port (8080 is the default), and "[jspname]" refers to the name (and application prefix, if necessary), of your test JSP. In my case, for example, I simply type in: http://localhost:8080/openejb.jsp.

7. Using OpenEJB embedded in one Tomcat web application

  1. Follow this step to access OpenEJB embedded in a web application.
  2. Stop Tomcat if its running: 
    cd $CATALINA_HOME/bin
./catalina.sh stop
  3. If you followed step 5, remove the OpenEJB jar from the Tomcat common/lib directory: 
    $ rm $CATALINA_HOME/common/lib/openejb-core-1.0-SNAPSHOT.jar
  4. If you followed step 6, remove the openejb-loader web application: 
    $ rm $CATALINA_HOME/webapps/openejb-loader
  5. If you followed step 5 or 6, remove the simpletest.jar: 
    $ rm $CATALINA_HOME/common/lib/simpletest.jar
  6. If you followed step 5 or 6, it is best to remove the work directory for the web application you were using: I just removed the whole Tomcat work directory: 
    $ rm -Rf $CATALINA_HOME/work/Standalone
  7. Create a test JSP (or modify the one above) and place it under the appropriate directory in $CATALINA_HOME/webapps. To use the default "ROOT" Context, put your JSP in the $CATALINA_HOME/webapps/ROOT directory. Save the following as openejb.jsp: 
    <%@ page language="java" import="java.util.Properties, javax.naming.*,
 javax.ejb.CreateException,
 javax.ejb.RemoveException,
 java.rmi.RemoteException,
 javax.naming.NamingException,
 test.j2ee.*
"%>
 
<html>
 <head>
  <title>EJB Test</title>
 </head>

 <body>
  <br/> 
  <br/> 

  <center><h3>Test of the SimpleTestBean</h3><br/>

<%
   String output = "";

   try {
	Properties p = new Properties();
	p.put("java.naming.factory.initial", 
           "org.openejb.client.LocalInitialContextFactory");

	javax.naming.InitialContext ctx = new javax.naming.InitialContext(p);
	Object obj = ctx.lookup("/SimpleTest");

	SimpleTestHome home = 
	   (SimpleTestHome)javax.rmi.PortableRemoteObject.narrow(obj, 
           SimpleTestHome.class);
	SimpleTest st = home.create();
	output = st.getDate();
	st.remove();
   } catch (NamingException e) {
        System.err.println("Naming exception occured during initialization"+ e);
           e.printStackTrace();
   }
%>

   <p>The SimpleTestBean said: <%= output %></p>

 </body>
</html>
  8. Copy the openejb-loader jar file to the WEB-INF/lib directory of the web application in which you want to embed OpenEJB: 
    cp $OPENEJB_HOME/lib/openejb-loader-1.0-SNAPSHOT.jar $CATALINA_HOME/webapps/ROOT/WEB-INF/lib

    In this example, I'm doing my testing in the default or "ROOT" Tomcat web application.

    By default, the $CATALINA_HOME/webapps/ROOT/WEB-INF directory may NOT have a "lib" subdirectory, so make sure you create it first!

  9. Copy the jar with our tests to the web application WEB-INF/lib directory: 
    $ cp $OPENEJB_HOME/beans/simpletest.jar $CATALINA_HOME/webapps/ROOT/WEB-INF/lib
  10. Edit $CATALINA_HOME/webapps/ROOT/WEB-INF/web.xml and add the following: 
      <servlet>
    <servlet-name>loader</servlet-name>
    <servlet-class>org.openejb.loader.LoaderServlet</servlet-class>
    <init-param>
      <param-name>openejb.loader</param-name>
      <param-value>tomcat-webapp</param-value>
    </init-param>
    <init-param>
      <param-name>openejb.home</param-name>
      <param-value>/usr/local/share/openejb1</param-value>
    </init-param>
    <init-param>
      <param-name>openejb.base</param-name>
      <param-value>/usr/local/share/openejb1</param-value>
    </init-param>
    <load-on-startup>0</load-on-startup>
  </servlet>

    Modify the location of openejb.home and openejb.base to point to your $OPENEJB_HOME.

  11. Start Tomcat: 
    cd $CATALINA_HOME/bin
./catalina.sh start

    OpenEJB will now be started by Tomcat as an embedded service within your web application. This actually allows you to have multiple copies of OpenEJB embedded within different web applications. You don't have to start OpenEJB from the $OPENEJB_HOME directory.

  12. Point your browser to http://[hostname]:[port]/[jspname], where "[hostname]" refers to the machine Tomcat is running on, "[port]" refers to the Tomcat HTTP port (8080 is the default), and "[jspname]" refers to the name (and application prefix, if necessary), of your test JSP. In my case, for example, I simply type in: http://localhost:8080/openejb.jsp.

Back to Table of Contents
 
©2002-2005 Galatea Information Strategies. All rights reserved