Page History

h2. Install and run Tomcat 6 (last tested with 6.0.14)

Tomcat 5.x is not supported due to classloading differences and the lack of annotation processing support. 
For Tomcat installation documentation see [http://tomcat.apache.org/tomcat-6.0-doc/setup.html]. 

Note onOn Unix platforms (Linux, MacOSX):
If you unpacked the Tomcat tar.gz file, the scripts are already executable.  If not, the following command will make all shell scripts executable: 

{code}$ chmod u+x bin/*.sh{code}

Note onOn all platforms: the following instructions assume running Tomcat using the bin/catalina.sh or bin/catalina.bat scripts and not running as a service, a daemon or an IDE daemonplugin.

h2. {anchor:install-openejb}Install OpenEJB

The OpenEJB plugin distributable for Tomcat runs as a separate web application and is provided as a zip file.
Current version: e.g: /openejb3/assembly/openejb-tomcat/target/openejb-tomcat-3.0.0-SNAPSHOT-bin.zip

h3. Unpack the OpenEJB Tomcat plugin in the Tomcat webapps directory to deploy the OpenEJB plugin container.

The OpenEJB directory in webapps should contain the following files:

{code:none}$ ls openejb
WEB-INF/     lib/         openejb.xml
{code}

h3. Unix users use http://localhost:8080/openejb/installer and click on the install button

h3. Windows users need to do the following 3 steps:

h4.1 Install the OpenEJB listener to Tomcat.

Add the following {highlight}highlighted lines{highlight} to your conf/server.xml file to load the OpenEJB listener:
 
{panel:title=conf/server.xml}
<!-- Note:  A "Server" is not itself a "Container", so you may not
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;define subcomponents such as "Valves" at this level.
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Documentation at /docs/config/server.html
 -->
<Server port="8005" shutdown="SHUTDOWN">
&nbsp;&nbsp;{highlight}<!-- OpenEJB plugin for tomcat -->{highlight}
&nbsp;&nbsp;{highlight}<Listener className="org.apache.openejb.loader.OpenEJBListener" />{highlight}

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

h4.2 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:

{code:none}$ mv>move lib/annotations-api.jar lib/annotations-api.jar-INVALID{code}

h4.3 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 {highlight}highlighted lines{highlight} to the bin/\catalina.bat file to enable the OpenEJB javaagent:

{panel:title=bin/catalina.bat}
...snip...
\# Set juli LogManager if it is present
if [ -rnot exist "$CATALINA_BASE"/conf/%CATALINA_BASE%\conf\logging.properties" ];goto then
&nbsp;&nbsp;noJuli
set JAVA_OPTS="$JAVA%JAVA_OPTSOPTS% "-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager" "-Djava.util.logging.config.file="$CATALINA%CATALINA_BASE/BASE%\conf/\logging.properties"
fi:noJuli

{highlight}\# Add OpenEJB javaagent
if [not -rexist "$CATALINA_BASE"/webapps/openejb/lib/%CATALINA_BASE%\lib\openejb-javaagent-3.0.0-SNAPSHOT.jar ]; then
&nbsp;&nbsp;" goto noOpenEJB   
set JAVA_OPTS=""-javaagent:$CATALINA_BASE/webapps/openejb/lib/%CATALINA_BASE%\lib\openejb-javaagent-3.0.0-SNAPSHOT.jar" $JAVA%JAVA_OPTS"OPTS%
fi:noOpenEJB{highlight}

\#rem ----- Execute The Requested Command -----------------------------------------

\# Bugzilla 37848: only output this if we have a TTY
if [ $have_tty -eq 1 ]; then
&nbsp;&nbsp;echo "Using CATALINA_BASE:   $CATALINA_BASE"
...snip...
{panel} 
*NOTE:* The exampleabove aboveexcerpt is an excerpt from the middle of the bin/\catalina.shbat file.  Search for "ExecuteJAVA_OPTS" in the file to locate the correct position in the file to add the new lines.

h3. All Platforms: Restart Tomcat

{info}
Known Issues:
* 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.
* There is no security integration. Please do not try using secured EJB in Tomcat embedded mode yet.
{info}


h2. Test an example application
h3. Create a stateless session bean
h4.Create an interface
{code:java}
package org.acme;
import javax.ejb.*;
@Remote
public interface Greeting{
	public String greet();
}
{code}
h4. Create the bean class
{code:java}
package org.acme;
import javax.ejb.*;
@Stateless
public class GreetingBean implements Greeting{
	public String greet(){
		return "I just greeted you buddy";
	}
}
{code}
h4. Create a servlet
{code:java}
package org.acme;
import javax.servlet.*;
import javax.servlet.http.*;
import javax.naming.*;
import java.io.*;
import java.util.*;

public class TestServlet extends HttpServlet{
	public void doGet(HttpServletRequest request, HttpServletResponse response){
		try{
			response.setContentType("text/html");
			PrintWriter writer = response.getWriter();
			Properties p = new Properties();
			p.put("java.naming.factory.initial","org.apache.openejb.client.LocalInitialContextFactory");
			InitialContext ctx = new InitialContext(p);
			Greeting g = (Greeting)ctx.lookup("GreetingBeanBusinessRemote");
			writer.print(g.greet());
		}catch(Exception e){
			e.printStackTrace();
		}
		
	}
}
{code}

h4.Register the servlet in web.xml
{code:xml}
<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
    "http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>

  <display-name>Test Application</display-name>

  <servlet>
    <servlet-name>TestServlet</servlet-name>
    <servlet-class>org.acme.TestServlet</servlet-class>

  </servlet>


  <servlet-mapping>
    <servlet-name>TestServlet</servlet-name>
    <url-pattern>/test</url-pattern>
  </servlet-mapping>

</web-app>

{code}
h4.Package the war
Compile the above classes into the WEB-INF/classes directory and package everything into testweb.war (or a file name of your liking)
h4. Drop the war in the tomcat webapps directory
Drop the testweb.war in the tomcat webapps directory
h4. Send a request to the servlet
#Open the browser
#Send a request to http://localhost:8080/testweb/test
#You should now see the message "I just greeted you buddy"
h1. \[OPTIONAL\] Run OpenEJB iTests

h2. Install iTests

Simply copy the OpenEJB iTests war to the Tomcat webapp directory.

{code:none}apache-tomcat-6.0.14$ cp openejb-tomcat-3.0.0-SNAPSHOT-itests.war webapps/{code}

h2. Start Tomcat

{code:none}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{code}

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

h2. Execute the test client

{code:none}$ 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
_________________________________________________
{code}

{tip:title=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.
{tip}