Overview

The manual installation process is significantly harder then the automatic installation which we normally recommend. In this installation process you will do the following:

1. Install openejb.war
   1. Download openejb.war from the OpenEJB download page
   2. Make webapps/openejb directory
   3. Change to new webapps/openejb directory
   4. Unpack the openejb.war file in the new directory
2. Add the OpenEJB listener the conf/server.xml file
3. Update the non-compliant Tomcat annotations-api.jar
4. Add the OpenEJB JavaAgent to the bin/catalina.bat or bin/catalina.bat script

install-openejbInstall openejb.war

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

Unpack OpenEJB Tomcat plugin in Tomcat webapps directory

Due to the structure of war files, you must create a new directory for OpenEJB, change to the new directory and execute the unpack command from within the new directory. If you get this wrong, it is difficult to undo, so follow the steps closely.

{card:label=Windows}true C:\apache-tomcat-6.0.14>mkdir webapps\openejb C:\apache-tomcat-6.0.14>cd webapps\openejb C:\apache-tomcat-6.0.14\webapps\openejb>jar -xvf \openejb.war created: WEB-INF/ created: WEB-INF/classes/ created: WEB-INF/classes/org/ created: WEB-INF/classes/org/apache/ created: WEB-INF/classes/org/apache/openejb/ ...snip... C:\apache-tomcat-6.0.14\webapps\openejb>dir Volume in drive C has no label. Volume Serial Number is 0000-0000 Directory of C:\apache-tomcat-6.0.14\webapps\openejb 09/21/2007 10:19 AM <DIR> . 09/21/2007 10:19 AM <DIR> .. 09/21/2007 10:19 AM 1,000 index.html 09/21/2007 10:19 AM <DIR> lib 09/21/2007 10:19 AM 11,358 LICENSE 09/21/2007 10:19 AM <DIR> META-INF 09/21/2007 10:19 AM 11,649 NOTICE 09/21/2007 10:19 AM 1,018 openejb.xml 09/21/2007 10:19 AM 1,886 README.txt 09/21/2007 10:19 AM <DIR> tomcat 09/21/2007 10:19 AM <DIR> WEB-INF 5 File(s) 26,911 bytes 6 Dir(s) 4,633,796,608 bytes free C:\apache-tomcat-6.0.14\webapps\openejb>cd ..\.. C:\apache-tomcat-6.0.14> {card}
{card:label=Unix}true apache-tomcat-6.0.14$ mkdir webapps/openejb apache-tomcat-6.0.14$ cd webapps/openejb/ apache-tomcat-6.0.14/webapps/openejb$ jar -xvf path/to/openejb.war created: WEB-INF/ created: WEB-INF/classes/ created: WEB-INF/classes/org/ created: WEB-INF/classes/org/apache/ created: WEB-INF/classes/org/apache/openejb/ ...snip... apache-tomcat-6.0.14/webapps/openejb$ ls LICENSE META-INF/ NOTICE README.txt WEB-INF/ index.html lib/ openejb.xml tomcat/ apache-tomcat-6.0.14/webapps/openejb$ cd ../.. apache-tomcat-6.0.14$ {card}

Add the OpenEJB listener to Tomcat

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

{card:label=Windows}true C:\apache-tomcat-6.0.14>copy webapps\openejb\lib\openejb-loader-3.0.0-SNAPSHOT.jar lib\openejb-loader.jar 1 file(s) copied. {card}
{card:label=Unix}true apache-tomcat-6.0.14$ cp webapps/openejb/lib/openejb-loader-*.jar lib/openejb-loader.jar {card}

Add the following

highlighted lines

conf/server.xml

<!-- Note: A "Server" is not itself a "Container", so you may not
     define subcomponents such as "Valves" at this level.
     Documentation at /docs/config/server.html
-->
<Server port="8005" shutdown="SHUTDOWN">
  

<!-- OpenEJB plugin for tomcat -->

<Listener className="org.apache.openejb.loader.OpenEJBListener" />

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

Update the Tomcat annotations-api.jar file

Tomcat contains an old non-compliant version of the javax.annotation classes and these invalid classes must be updated so OpenEJB can process annotations. Simply, replace the annotations-api.jar in the Tomcat lib directory with the updated annotations-api.jar in the OpenEJB war.

{card:label=Windows}true C:\apache-tomcat-6.0.14>copy webapps\openejb\tomcat\annotations-api.jar lib\annotations-api.jar Overwrite lib\annotations-api.jar? (Yes/No/All): y 1 file(s) copied. {card}
{card:label=Unix}true apache-tomcat-6.0.14$ cp webapps/openejb/tomcat/annotations-api.jar lib/annotations-api.jar {card}

javaagent 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.

First, copy the OpenEJB JavaAgent jar into the lib directory.

{card:label=Windows}true C:\apache-tomcat-6.0.14>copy webapps\openejb\lib\openejb-javaagent-3.0.0-SNAPSHOT.jar lib\openejb-javaagent.jar 1 file(s) copied. {card}
{card:label=Unix}true apache-tomcat-6.0.14$ cp webapps/openejb/lib/openejb-javaagent-*.jar lib/openejb-javaagent.jar {card}

Simply, add the following

highlighted lines

{deck:id=update script} {card:label=Windows} bin/catalina.bat

...snip...
if not exist "%CATALINA_BASE%\conf\logging.properties" goto noJuli
set JAVA_OPTS=%JAVA_OPTS% -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Djava.util.logging.config.file="%CATALINA_BASE%\conf\logging.properties"
:noJuli

rem Add OpenEJB javaagent
if not exist "%CATALINA_BASE%\webapps\openejb\lib\openejb-javaagent.jar" goto noOpenEJBJavaagent
set JAVA_OPTS="-javaagent:%CATALINA_BASE%\webapps\openejb\lib\openejb-javaagent.jar" %JAVA_OPTS%
:noOpenEJBJavaagent

rem ----- Execute The Requested Command ---------------------------------------

echo Using CATALINA_BASE: %CATALINA_BASE%
echo Using CATALINA_HOME: %CATALINA_HOME%
...snip...

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.