THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
Install Tomcat 6
If you already have Tomcat 6 installed, skip to Install OpenEJB.
Unpack Tomcat
Unpack the Tomcat zip file which will create a new directory containing the complete Tomcat installation.
$ 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...
Change to the new Tomcat installation directory.
$ cd apache-tomcat-6.0.14/
The Tomcat installation should contain the following files:
apache-tomcat-6.0.14$ ls LICENSE RELEASE-NOTES bin/ lib/ temp/ work/ NOTICE RUNNING.txt conf/ logs/ webapps/
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:
apache-tomcat-6.0.14$ chmod u+x bin/*.sh
Start Tomcat
Execute the following command to start the Tomcat server to verify it is functioning properly:
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
NOTE: Your output will be different from the example above due to differences in installation location.
Verify Tomcat is Running
Visit http://localhost:8080/
and you should see the Tomcat welcome page.
Stop Tomcat
Shutdown Tomcat by executing the following command:
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
NOTE: Your output will be different from the example above due to differences in installation location.
InstallOpenEJB">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.
Unpack OpenEJB Tomcat plugin in Tomcat webapps directory
Change to the webapps directory:
apache-tomcat-6.0.14$ cd webapps
Unpack the openejb-tomcat-3.0.0-SNAPSHOT-bin.zip file.
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...
The OpenEJB directory should contain the following files:
apache-tomcat-6.0.14/webapps$ ls openejb WEB-INF/ lib/ openejb.xml
Return to the Tomcat install directory
apache-tomcat-6.0.14/webapps$ cd ..
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.
apache-tomcat-6.0.14$ cp webapps/openejb/lib/openejb-loader-3.0.0-SNAPSHOT.jar lib/
Add the following
Unknown macro: {highlight}
highlighted lines
to your conf/server.xml file to load the OpenEJB listener:
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">
Unknown macro: {highlight}
<!-- OpenEJB plugin for tomcat -->
Unknown macro: {highlight}
<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...
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:
apache-tomcat-6.0.14$ mv lib/annotations-api.jar lib/annotations-api.jar-INVALID
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
Unknown macro: {highlight}
highlighted lines
to the bin/catalina.sh file to enable the OpenEJB javaagent:
bin/catalina.sh
...snip...
# Set juli LogManager if it is present
if [ -r "$CATALINA_BASE"/conf/logging.properties ]; then
JAVA_OPTS="$JAVA_OPTS "-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager" "-Djava.util.logging.config.file="$CATALINA_BASE/conf/logging.properties"
fi
Unknown macro: {highlight}
# Add OpenEJB javaagent
if [ -r "$CATALINA_BASE"/webapps/openejb/lib/openejb-javaagent-3.0.0-SNAPSHOT.jar ]; then
JAVA_OPTS=""-javaagent:$CATALINA_BASE/webapps/openejb/lib/openejb-javaagent-3.0.0-SNAPSHOT.jar" $JAVA_OPTS"
fi
# ----- Execute The Requested Command -----------------------------------------
# Bugzilla 37848: only output this if we have a TTY
if [ $have_tty -eq 1 ]; then
echo "Using CATALINA_BASE: $CATALINA_BASE"
...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.
[OPTIONAL] Run OpenEJB iTests
Install iTests
Simply copy the OpenEJB iTests war to the Tomcat webapp directory.
apache-tomcat-6.0.14$ cp openejb-tomcat-3.0.0-SNAPSHOT-itests.war webapps/
Start Tomcat
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
NOTE: Your output will be different from the example above due to differences in installation location.
Execute the test client
$ 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 _________________________________________________
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.
Useful instructions - Not properly integrated into this page. This info was picked up as is from an email from Dain
Information below just put here temporarily so that we don't lose it, needs proper integration with original content
The installer is still a work in progress (I'm working on it today),
but the currently checked in version works fine on unix.
David's process is correct, but here are the exact steps:
1. copy openejb-tomcat-3.0.0-SNAPSHOT-bin.zip to your Tomcat webapps
directory
2. make sure Tomcat is running
3. visit http://localhost:8080/openejb/installer
4. Assuming you don't get any errors, reboot tomcat
At this point OpenEJB will be installed just like the manual
instructions (http://cwiki.apache.org/confluence/display/OPENEJB/New
+Instructions). As for your applications, simply include EJBs in
your war WEB-INF/classes or WEB-INF/lib/*.jar using either annotated
classes or via a META-INF/ejb-jar.xml file.
Restrictions
o The installer only runs on Unix. Windows support will require a
tweaked catalina.bat and a work around for Windows file locking.
Cygwin won't work either and will require even more work arounds in
the Unix code to deal with pathing problems.
o There is no uninstaller. Currently, the installer deletes the non-
compliant Tomcat annotations-api.jar so in addition to backing out
the changes, you need to restore this file.
o Annotations in servlets to OpenEJB resources (EJBs,
PersistenceUnits, Topics, Queues, DataSources, etc) don't resolve.
You will have to use global JNDI for the time being.
o There is no security integration. I suggest you don't even try
using secured EJB in Tomcat embedded mode yet.
Hope this helps,
o We only support Tomcat 6 and I suggest you use the newest version
as I haven't tested any older 6 revisions. We could potentially
support older versions of Tomcat if there were enough demand, but I
doubt there will be since OpenEJB 3 requires Java5.