Title: Tomcat

<a name="Tomcat-Introduction"></a>
# 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 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 [OPENEJB:Collapsed EAR](openejb:collapsed-ear.html)
 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

<a name="Tomcat-{anchor:quickinstructions}InstallationfortheImpatient"></a>
# Installation for the Impatient

Assuming you have a [normal working Tomcat 6.x or 5.5 installation](tomcat-installation.html)
:

1. Download [openejb.war](openejb:download.html)
1. Copy openejb.war to $\{catalina.base\}/webapps/openejb.war (Note: the
file *must* be named openejb.war)
1. Start Tomcat if it is not already running
1. (optional) Visit [http://localhost:8080/openejb/installer](http://localhost:8080/openejb/installer)
 and click the 'install' button

<a name="Tomcat-Examples,TutorialsandTests"></a>
# Examples, Tutorials and Tests

<a name="Tomcat-ejb-examples.war"></a>
## ejb-examples.war

See the webapps/ejb-examples/ directory in the [openejb-examples zip](openejb:download.html)
.

<a name="Tomcat-{anchor:problems}Problems?"></a>
#Problems?

<a name="Tomcat-HTTPStatus403"></a>
## HTTP Status 403 

Did you get a "HTTP Status 403" error page containing the description
"Access to the specified resource () has been forbidden." when visiting [http://localhost:8080/openejb](http://localhost:8080/openejb)
?

The openejb.war is protected by a Tomcat valve that restricts access to the
application to the computer on which Tomcat is running.  If your browser is
running on the same computer as Tomcat, try accessing OpenEJB using this
link instead [http://127.0.0.1:8080/openejb](http://127.0.0.1:8080/openejb)
.

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

<a name="Tomcat-DuplicateDeploymentIdException:"></a>
## 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
1. Add the following to the system.properties file and save

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


<a name="Tomcat-java.lang.OutOfMemoryError:PermGenspace"></a>
## 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.

<a name="Tomcat-OtherIssues"></a>
## Other Issues

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

* OpenEJB Version
* Tomcat Version
* Java Version (execute java -version)
* Operating System Type and Version


<a name="Tomcat-Limitations"></a>
# Limitations

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

<a name="Tomcat-Misc"></a>
# Misc

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 lower right and
make changes and add new HOWTO's and other docs.  

<a name="Tomcat-JSFInjectionSupport"></a>
# 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.