Install and run Tomcat 6
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.
On 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:
$ chmod u+x bin/*.sh
On 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 plugin.
InstallOpenEJB">Install OpenEJB
The OpenEJB plugin distributable for Tomcat runs as a separate web application and is provided as a zip file.
e.g: /openejb3/assembly/openejb-tomcat/target/openejb-tomcat-3.0.0-SNAPSHOT-bin.zip
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:
$ ls openejb WEB-INF/ lib/ openejb.xml
Unix users use http://localhost:8080/openejb/installer and click on the install button
Windows users need to do the following 4 steps:
1 Install the OpenEJB listener to Tomcat.
Add the following
highlighted lines
to your conf/server.xml file to load the OpenEJB listener:
<!-- 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">
<!-- OpenEJB plugin for tomcat -->
<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...
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:
>move lib\annotations-api.jar lib\annotations-api.jar-INVALID
3 Copy the files, openejb-loader-3.0.0-SNAPSHOT.jar and openejb-javaagent-3.0.0-SNAPSHOT.jar
from webapps/openejb/lib/ to Tomcat's lib/ folder.
4 Add OpenEJB javaagent to Tomcat startup
OpenJPA, the Java Persistence implementation used by OpenEJB, currently must use enhanced persistence classes to function properly, and this requires the installation of a javaagent into the Tomcat startup process.
Simply, add the following
highlighted lines
to the bin\catalina.bat file to enable the OpenEJB javaagent:
...snip...
if not exist "%CATALINA_BASE%\conf\logging.properties" goto noJuli
set JAVA_OPTS=%JAVA_OPTS% -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Djava.util.logging.config.file="%CATALINA_BASE%\conf\logging.properties"
:noJuli
if not exist "%CATALINA_BASE%\lib\openejb-javaagent-3.0.0-SNAPSHOT.jar" goto noOpenEJB
set JAVA_OPTS=-javaagent:%CATALINA_BASE%\lib\openejb-javaagent-3.0.0-SNAPSHOT.jar %JAVA_OPTS%
:noOpenEJB
rem ----- Execute The Requested Command ---------------------------------------
...snip...
NOTE: The above excerpt is from the middle of the bin\catalina.bat file. Search for "JAVA_OPTS" in the file to locate the correct position in the file to add the new lines.
All Platforms: Restart Tomcat
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.
Test an example application
Create a stateless session bean
Create an interface
package org.acme; import javax.ejb.*; @Remote public interface Greeting{ public String greet(); }
Create the bean class
package org.acme; import javax.ejb.*; @Stateless public class GreetingBean implements Greeting{ public String greet(){ return "I just greeted you buddy"; } }
Create a servlet
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(); } } }
Register the servlet in web.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>
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)
Drop the war in the tomcat webapps directory
Drop the testweb.war in the tomcat webapps directory
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"
[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.