Wiki Markup |
---|
{composition-setup}{composition-setup} |
Introduction
The OpenEJB plugin for Tomcat makes all of the OpenEJB features available to Servlets, including:
...
Requirements:
- OpenEJB 3.x
- Tomcat 6.x or 5.5
- Java 1.5 or 1.6
Anchor |
---|
| quick instructions |
---|
| quick instructions |
---|
|
Installation for the Impatient
The plugin installation process is pretty simple, so if you are comfortable with the command line and Tomcat, this will get you going ASAP; otherwise, skip to the detailed instructions below.
Assuming you have a normal working Tomcat 6.x or 5.5 installation:
Tomcat 6.x
- Download openejb.war
- Copy openejb.war to ${catalina.base}/webapps/openejb.war (Note: the file must be named openejb.war)
- Start Tomcat if it is not already running
- (optional) Visit http://localhost:8080/openejb/installer and click the 'install' button
- Restart Tomcat
...
These instructions assume you have a standard Tomcat installation running on port 8080. If you do not have an existing Tomcat installation, or want to start with a fresh installation for OpenEJB, the Tomcat Installation will show you how to setup and verify a Tomcat installation.
Add openejb.war to Tomcat
The OpenEJB plugin for Tomcat is distributed as a standalone war file containing all of the necessary files and an installer Servlet. The war can be obtained from the OpenEJB download page. Once downloaded, simply copy the file into the Tomcat webapps directory.
Wiki Markup |
---|
{deck:id=Copy openejb.war} |
Wiki Markup |
---|
{card:label=Windows} |
No Format |
---|
|
C:\>copy openejb.war apache-tomcat-6.0.14\webapps\openejb.war
1 file(s) copied.
C:\>dir apache-tomcat-6.0.14\webapps
Volume in drive C has no label.
Volume Serial Number is 0000-0000
Directory of C:\apache-tomcat-6.0.14\webapps
09/20/2007 03:03 PM <DIR> .
09/20/2007 03:03 PM <DIR> ..
09/20/2007 03:02 PM <DIR> docs
09/20/2007 03:01 PM <DIR> examples
09/20/2007 03:01 PM <DIR> host-manager
09/20/2007 03:03 PM <DIR> manager
09/19/2007 09:31 AM 13,394,733 openejb.war
09/20/2007 03:01 PM <DIR> ROOT
1 File(s) 13,394,733 bytes
7 Dir(s) 5,100,126,208 bytes free
|
Wiki Markup |
---|
{card:label=Unix} |
No Format |
---|
|
$ cp openejb.war apache-tomcat-6.0.14/webapps/openejb.war
$ ls apache-tomcat-6.0.14/webapps/
ROOT/ docs/ examples/ host-manager/ manager/ openejb.war
|
Run Installer Servlet
The OpenEJB Plugin for Tomcat contains an installer servlet which adds the OpenEJB listener and JavaAgent to the Tomcat installation. To run the installer, you must first start Tomcat.
Wiki Markup |
---|
{deck:id=Start Tomcat} |
Wiki Markup |
---|
{card:label=Windows} |
Tomcat 5.5
- Download openejb.war
- Copy openejb.war to ${catalina.base}/server/webapps/openejb.war (Note: the file must be named openejb.war)
- Create a file ${catalina.base}/conf/Catalina/localhost/openejb.xml with the following contents:
Code Block |
---|
|
<Context path="/openejb" docBase="${catalina.home}/server/webapps/openejb"
privileged="true" antiResourceLocking="false" antiJARLocking="false"/>
|
- Restart Tomcat
No Format |
---|
|
C:\>set JRE_HOME=C:\Program Files\Java\jre1.5.0_06
C:\>cd apache-tomcat-6.0.14\bin
C:\apache-tomcat-6.0.14\bin>startup.bat
Using CATALINA_BASE: C:\apache-tomcat-6.0.14
Using CATALINA_HOME: C:\apache-tomcat-6.0.14
Using CATALINA_TMPDIR: C:\apache-tomcat-6.0.14\temp
Using JRE_HOME: C:\your\java\installation
|
Wiki Markup |
---|
{card:label=Unix} |
No Format |
---|
|
$ cd apache-tomcat-6.0.14/bin
apache-tomcat-6.0.14/bin$ chmod u+x *.sh
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 locations.
It is a good idea to wait a 5-60 seconds (depending on the speed of your computer) for Tomcat to fully start. Once Tomcat is fully started, simply visit http://localhost:8080/openejb/installer and click the 'install' button to run the installer. The installer should report that the installation was successful. If it didn't work click here.
Warning |
---|
The installer servlet adds the OpenEJB JavaAgent declaration to the catalina.sh and catalina.bat files. If you are using an IDE or some other mechanism to start Tomcat, you will need to manually add the JavaAgent declaration to the Java VM options of the launcher you are using. |
Restart Tomcat
OpenEJB uses OpenJPA for persistence and OpenJPA currently requires a JavaAgent to function. Unfortunately, there is no way to install a JavaAgent at runtime, so you will have to restart Tomcat to enable the JavaAgent. Simply execute the shutdown command, wait 5-60 seconds (depending on the speed of your computer) for Tomcat to fully stop, and run the startup command to restart Tomcat.
Wiki Markup |
---|
{deck:id=Start Tomcat} |
Wiki Markup |
---|
{card:label=Windows} |
No Format |
---|
|
C:\>cd apache-tomcat-6.0.14\bin
C:\apache-tomcat-6.0.14\bin>shutdown.bat
Using CATALINA_BASE: C:\apache-tomcat-6.0.14
Using CATALINA_HOME: C:\apache-tomcat-6.0.14
Using CATALINA_TMPDIR: C:\apache-tomcat-6.0.14\temp
Using JRE_HOME: C:\your\java\installation
C:\apache-tomcat-6.0.14\bin>startup.bat
Using CATALINA_BASE: C:\apache-tomcat-6.0.14
Using CATALINA_HOME: C:\apache-tomcat-6.0.14
Using CATALINA_TMPDIR: C:\apache-tomcat-6.0.14\temp
Using JRE_HOME: C:\your\java\installation
|
Wiki Markup |
---|
{card:label=Unix} |
No Format |
---|
|
$ cd apache-tomcat-6.0.14/bin
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
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 locations.
...
Examples, Tutorials and Tests
ejb-examples.war
Download the ejb-examples.war, copy it into the Tomcat webapps directory, and visit http://localhost:8080/ejb-examples.
OpenEJB iTests
OpenEJB uses a large test suite to verify the final server assembly, and you can use this to verify your OpenEJB installation. Simply download the openejb-itests.war and openejb-standalone-client.jar and copy it the war into the Tomcat webapps directory. It will take a bit to load the application because it contains a huge number of EJBs. Finally, run the test client executable jar.
Wiki Markup |
---|
{deck:id=Start Tomcat} |
Wiki Markup |
---|
{card:label=Windows} |
No Format |
---|
|
C:\>java -jar openejb-itests-standalone-client.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/ejb
entry = java.naming.factory.initial:org.apache.openejb.client.RemoteInitialContextFactory
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
............................
Time: 20.644
OK (889 tests)
_________________________________________________
CLIENT JNDI PROPERTIES
java.naming.provider.url = http://127.0.0.1:8080/openejb/ejb
java.naming.factory.initial = org.apache.openejb.client.RemoteInitialContextFactory
_________________________________________________
|
Wiki Markup |
---|
{card:label=Unix} |
No Format |
---|
|
$ java -jar openejb-itests-standalone-client.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/ejb
entry = java.naming.factory.initial:org.apache.openejb.client.RemoteInitialContextFactory
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
............................
Time: 12.186
OK (889 tests)
_________________________________________________
CLIENT JNDI PROPERTIES
java.naming.provider.url = http://127.0.0.1:8080/openejb/ejb
java.naming.factory.initial = org.apache.openejb.client.RemoteInitialContextFactory
_________________________________________________
|
See the webapps/ejb-examples/ directory in the openejb-examples zip.
Tip |
---|
|
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. |
Problems?
...
- OpenEJB Version
- Tomcat Version
- Java Version (execute java -version)
- Operating System Type and Version
Limitations
Tomcat 6.x - Currently, only Tomcat 6.x is supported due to API difference between 5.5.x and 6.x. It is expected that 5.5 will be supported in the future, but there are no plans to support 5.0.x due to the lack of annotation support in 5.0.x.
Security - Unfortunately, at this time security with Tomcat/OpenEJB is not integrated, but is being worked on.
...
JavaAgent - OpenEJB uses OpenJPA to provide JPA and CMP persistence, and OpenJPA currently requires a JavaAgent to function properly. This requirement is something that the OpenJPA project is working on removing. Once removed, the OpenEJB plugin for Tomcat will no longer need to modify the startup shell scripts and you will not need to restart Tomcat after the OpenEJB installation.
...