Page History

h1. Install Tomcat 6

If you already have Tomcat 6 installed, skip to [Install OpenEJB|#install-openejb].

h2. Unpack Tomcat

Unpack the Tomcat zip file  which will create a new directory containing the complete Tomcat installation.

{code:none}$ jar -xvf apache-tomcat-6.0.14.zip 
  created: apache-tomcat-6.0.14/
  created: apache-tomcat-6.0.14/bin/
  created: apache-tomcat-6.0.14/conf/
...snip...
{code}

Change to the new Tomcat installation directory.

{code:none}$ cd apache-tomcat-6.0.14/{code}

The Tomcat installation should contain the following files:

{code:none}apache-tomcat-6.0.14$ ls
LICENSE        RELEASE-NOTES  bin/           lib/           temp/          work/
NOTICE         RUNNING.txt    conf/          logs/          webapps/
{code}

h2. Make shell scripts executable

The shell scripts in the Tomcat installation are not executable by default, so in order to execute them, you must set mark them as executable.  If you unpacked the Tomcat tar.gz file, the scripts are already executable.  The following command will make all shell scripts executable:

{code}apache-tomcat-6.0.14$ chmod u+x bin/*.sh{code}

h2. Start Tomcat

Execute the following command to start the Tomcat server to verify it is functioning properly:

{code:none}apache-tomcat-6.0.14$ bin/startup.sh 
Using CATALINA_BASE:   /your/tomcat/installation/apache-tomcat-6.0.14
Using CATALINA_HOME:   /your/tomcat/installation/apache-tomcat-6.0.14
Using CATALINA_TMPDIR: /your/tomcat/installation/apache-tomcat-6.0.14/temp
Using JRE_HOME:        /your/java/installation{code}

*NOTE:* Your output will be different from the example above due to differences in installation location.

h2. Verify Tomcat is Running

Visit [http://localhost:8080/] and you should see the Tomcat welcome page.


h2. Stop Tomcat

Shutdown Tomcat by executing the following command:

{code:none}apache-tomcat-6.0.14$ bin/shutdown.sh
Using CATALINA_BASE:   /your/tomcat/installation/apache-tomcat-6.0.14
Using CATALINA_HOME:   /your/tomcat/installation/apache-tomcat-6.0.14
Using CATALINA_TMPDIR: /your/tomcat/installation/apache-tomcat-6.0.14/temp
Using JRE_HOME:        /your/java/installation{code}

*NOTE:* Your output will be different from the example above due to differences in installation location.

h1. {anchor:install-openejb}Install OpenEJB

Once Tomcat has been installed, the OpenEJB plugin for Tomcat can be installed.  The commands in this example are executed within the Tomcat installation directory.

h2. Unpack OpenEJB Tomcat plugin in Tomcat webapps directory

Change to the webapps directory:

{code:none}apache-tomcat-6.0.14$ cd webapps{code}

Unpack the openejb-tomcat-3.0.0-SNAPSHOT-bin.zip file.

{code:none}apache-tomcat-6.0.14/webapps$ jar -xvf ../openejb-tomcat-3.0.0-SNAPSHOT-bin.zip
  created: openejb/
  created: openejb/WEB-INF/
  created: openejb/lib/
 inflated: openejb/lib/geronimo-javamail_1.4_spec-1.1.jar
 inflated: openejb/lib/xbean-finder-3.1.jar
...snip...
{code}

The OpenEJB directory should contain the following files:

{code:none}apache-tomcat-6.0.14/webapps$ ls openejb
WEB-INF/     lib/         openejb.xml
{code}

Return to the Tomcat install directory 

{code:none}apache-tomcat-6.0.14/webapps$ cd ..{code}

h2. Add the OpenEJB listener to Tomcat 

Tomcat listeners must be available in the Tomcat common class loader, so the openejb-loader jar must be copied into the Tomcat lib directory.

{code:none} apache-tomcat-6.0.14$ cp webapps/openejb/lib/openejb-loader-3.0.0-SNAPSHOT.jar lib/{code}

Add the following {highlight}highlighted lines{highlight} to your conf/server.xml file to load the OpenEJB listener:
 
{panel:title=conf/server.xml}
<!-- Note:  A "Server" is not itself a "Container", so you may not
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;define subcomponents such as "Valves" at this level.
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Documentation at /docs/config/server.html
 -->
<Server port="8005" shutdown="SHUTDOWN">
&nbsp;&nbsp;{highlight}<!-- OpenEJB plugin for tomcat -->{highlight}
&nbsp;&nbsp;{highlight}<Listener className="org.apache.openejb.loader.OpenEJBListener" />{highlight}

&nbsp;&nbsp;<!--APR library loader. Documentation at /docs/apr.html -->
&nbsp;&nbsp;<Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />
...snip...
{panel} 

h2. Delete the Tomcat annotations-api.jar file

Tomcat contains an old non-compliant version of the javax.annotation classes and these invalid classes must be removed so OpenEJB can process annotations.  Simply, rename the annotation-api.jar so it doesn't end with {{".jar"}}.  For example:

{code:none}apache-tomcat-6.0.14$ mv lib/annotations-api.jar lib/annotations-api.jar-INVALID{code}

h2. Add OpenEJB javaagent to Tomcat startup

OpenJPA, the Java Persistence implementation used by OpenEJB, currently must enhanced persistence classes to function properly, and this requires the installation of a javaagent into the Tomcat startup process.

Simply, add the following {highlight}highlighted lines{highlight} to the bin/catalina.sh file to enable the OpenEJB javaagent:

{panel:title=bin/catalina.sh}
...snip...
\# Set juli LogManager if it is present
if [ -r "$CATALINA_BASE"/conf/logging.properties ]; then
&nbsp;&nbsp;JAVA_OPTS="$JAVA_OPTS "-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager" "-Djava.util.logging.config.file="$CATALINA_BASE/conf/logging.properties"
fi

{highlight}\# Add OpenEJB javaagent
if [ -r "$CATALINA_BASE"/webapps/openejb/lib/openejb-javaagent-3.0.0-SNAPSHOT.jar ]; then
&nbsp;&nbsp;JAVA_OPTS=""-javaagent:$CATALINA_BASE/webapps/openejb/lib/openejb-javaagent-3.0.0-SNAPSHOT.jar" $JAVA_OPTS"
fi{highlight}

\# ----- Execute The Requested Command -----------------------------------------

\# Bugzilla 37848: only output this if we have a TTY
if [ $have_tty -eq 1 ]; then
&nbsp;&nbsp;echo "Using CATALINA_BASE:   $CATALINA_BASE"
...snip...
{panel} 

*NOTE:* The example above is an excerpt from the middle of the bin/catalina.sh file.  Search for "Execute" in the file to locate the correct position in the file to add the new lines.

h1. \[OPTIONAL\] Run OpenEJB iTests

h2. Install iTests

Simply copy the OpenEJB iTests war to the Tomcat webapp directory.

{code:none}apache-tomcat-6.0.14$ cp openejb-tomcat-3.0.0-SNAPSHOT-itests.war webapps/{code}

h2. Start Tomcat

{code:none}apache-tomcat-6.0.14$ bin/startup.sh 
Using CATALINA_BASE:   /your/tomcat/installation/apache-tomcat-6.0.14
Using CATALINA_HOME:   /your/tomcat/installation/apache-tomcat-6.0.14
Using CATALINA_TMPDIR: /your/tomcat/installation/apache-tomcat-6.0.14/temp
Using JRE_HOME:        /your/java/installation{code}

*NOTE:* Your output will be different from the example above due to differences in installation location.

h2. Execute the test client

{code:none}$ java -Dtomcat.home=. -Dremote.servlet.url=http://127.0.0.1:8080/openejb/remote -jar openejb-tomcat-3.0.0-SNAPSHOT-test.jar tomcat
_________________________________________________
|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|

Running EJB compliance tests on HTTP/Tomcat Server
_________________________________________________
WARNING: No test suite configuration file specified, assuming system properties contain all needed 
information.  To specify a test suite configuration file by setting its location using the system 
property "openejb.testsuite.properties"
test server = org.apache.openejb.test.TomcatRemoteTestServer
entry = java.naming.provider.url:http://127.0.0.1:8080/openejb/remote
entry = java.naming.factory.initial:org.apache.openejb.client.RemoteInitialContextFactory
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
........................
Time: 10.853

OK (885 tests)


_________________________________________________
CLIENT JNDI PROPERTIES
java.naming.provider.url = http://127.0.0.1:8080/openejb/remote
java.naming.factory.initial = org.apache.openejb.client.RemoteInitialContextFactory
_________________________________________________
{code}

{tip:title=Failures}
The tests should completely pass the first time they are run.  If you execute the test client a second time, 21 tests fail for some unknown reason.
{tip}