{composition-setup}{composition-setup}

Introduction

The OpenEJB plugin for Tomcat makes all of the OpenEJB features available to Servlets, including:

• @Annotations
  • @Resource
  • @PersistenceUnit
  • @PersistenceContext
  • @EJB
• JPA - Java Persistence Architecture
• JMS - Java Messing Messaging Service
• JTA - Transaction Processing
  • TransactionManager
  • Container Managed Transactions
  • XA Support
• JavaMail

In addition, WAR files can contain EJB modules and JPA persistence units eliminating the annoying construction of .ear files. Adding EJBs and JPA Persistence beans to your application is as simple as adding the @Stateless, @Stateful, @MessageDriven or @Entity to a class. The packaging is refered to as Collapsed EAR style as the war file, ejb jar, and persistence unit files are merged into one archive and share the same classloader.

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

...

Assuming you have a normal working Tomcat 6.x or 5.5 installation:

1. Download openejb.war
2. Copy openejb.war to ${catalina.base}/webapps/openejb.war (Note: the file must be named openejb.war)
3. Start Tomcat if it is not already running
4. Visit http://localhost:8080/openejb/installer and click the 'install' button
5. Restart Tomcat

...

1. running

...

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.

{deck:id=Copy openejb.war}

{card:label=Windows}

...

{card}

{card:label=Unix}

$ 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

{card}

{deck}

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.

{deck:id=Start Tomcat}

{card:label=Windows}

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

{card}

{card:label=Unix}

$ 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

{card}

{deck}

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

...

...

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

1. (optional) Visit http://localhost:8080/openejb/installer and click the 'install' button

...

...

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.

{deck:id=Start Tomcat}

{card:label=Windows}

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

{card}

{card:label=Unix}

$ 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

{card}

{deck}

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

Once Tomcat is fully started, simply visit http://localhost:8080/openejb/installer to verify the installation is complete.

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.

{deck:id=Start Tomcat}

{card:label=Windows}

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
_________________________________________________

{card}

{card:label=Unix}

$ 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
_________________________________________________

{card}

See the webapps/ejb-examples/ directory in the openejb-examples zip.

{deck}

Anchor
problems problems

Problems?

...

If you want to access the openejb.war from another computer, you will need to either remove the valve, or modify the IP list in the valve declaration.

The easiest way to remove the valve it to simply delete the webapps/openejb/META-INF/context.xml file and and the webapps/openejb.war file while Tomcat is stopped. Warning that Tomcat keeps a copy of all context.xml files under conf/Catalina/localhost/<appname>.xml, so you may need to delete the conf/Catalina/localhost/openejb.xml file as well. The openejb.war file must be removed because some versions of Tomcat will use the context.xml file packed in the openejb.war file regardless of what is in the unpacked directory.

DuplicateDeploymentIdException:

If you try to deploy the same ejb in two different web applications, then you will get the following exception (in conf/openejb.log):

org.apache.openejb.DuplicateDeploymentIdException: Application cannot be deployed as it contains deployment-ids which are in use: 

To fix the issue, do the following:

1. Create a file named system.properties under the conf directory
2. Add the following to the system.properties file and save

   Code Block
   openejb.deploymentId.format={moduleId}/{ejbName}

java.lang.OutOfMemoryError: PermGen space

By default, the JVM starts with a small PermGen. Tomcat does not increase this limit, so you may encounter this exception by the time Tomcat deploys and executes your application. If you get this exception, you should consider increasing the PermGen allocation for the Tomcat JVM. You can achieve this by adding "-XX:MaxPermSize=256m" to the CATALINA_OPTS environment variable before starting Tomcat.

Other Issues

If you are having problems with the installation, please send a message to the OpenEJB users mailing list containing any error message(s) and the following information:

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

EAR Files - The integration only supports war (and collapsed-ear) files. EAR, EJB Jar, and RAR files will be supported in a future release.

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.

...

This document is a starting point for using OpenEJB in Tomcat and will evolve based on user contributions. If you wish to contribute to this document, feel very welcome to click the 'Edit' link in the upper lower right and make changes and add new HOWTO's and other docs.

JSF Injection Support

Now you can inject EJB's into JSF managed beans. Currently we have tested with JSF 1.2 RI (Mojarra) and MyFaces v1.2.3 . We would definitely appreciate any feedback on other JSF implementations.