Note

title	READ THIS FIRST

Restrictions
o The installer only runs on Unix. Windows support will require a tweaked catalina.bat and a work around for Windows file locking.
Cygwin won't work either and will require even more work arounds in the Unix code to deal with pathing problems.
o 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.
o Annotations in servlets to OpenEJB resources (EJBs,PersistenceUnits, Topics, Queues, DataSources, etc) don't resolve.
You will have to use global JNDI for the time being.
o There is no security integration. Please do not try using secured EJB in Tomcat embedded mode yet.
o We only support Tomcat 6 and we suggest you use the newest version as we haven't tested any older 6 revisions. We could potentially
support older versions of Tomcat if there were enough demand, but it is doubtful there will be since OpenEJB 3 requires Java5.

Install Tomcat 6

If you already have Tomcat 6 installed, skip to Install OpenEJB.

Unpack Tomcat

Unpack the Tomcat zip file which will create a new directory containing the complete Tomcat installation.

Code Block

	none
	none

$ jar -xvf

Wiki Markup

h1. Install Tomcat 6

If you already have Tomcat 6 installed, skip to [Install OpenEJB|#install-openejb].

h2. Unpack Tomcat

Unpack the Tomcat zip file  which will create a new directory containing the complete Tomcat installation.

{code:none}$ jar -xvf apache-tomcat-6.0.14.zip 
  created: apache-tomcat-6.0.14/
  created: apache-tomcat-6.0.14/bin/
  created: apache-tomcat-6.0.14/conf/
...snip...
{code}

Change to the new Tomcat installation directory.

{code:none}$ cd apache-tomcat-6.0.14/{code}

The Tomcat installation should contain the following files:

{code:none}apache-tomcat-6.0.14.14$zip ls
LICENSE        RELEASE-NOTES  bin/           lib/           temp/          work/
NOTICE         RUNNING.txt    conf/    created: apache-tomcat-6.0.14/
  created: apache-tomcat-6.0.14/bin/
  created: apache-tomcat-6.0.14/conf/
...snip...

Change to the new Tomcat installation directory.

Code Block

	none
	none

$ cd apache-tomcat-6.0.14/

The Tomcat installation should contain the following files:

Code Block

	none
	none

apache-tomcat-6.0.14$ ls
LICENSE      logs/  RELEASE-NOTES  bin/      webapps/
{code}

h2. Make shell scripts executable

The shell scripts in the Tomcat installation are not executable by default, so in order to execute them, you must set mark them as executable.  If you unpacked the Tomcat tar.gz file, the scripts are already executable.  The following command will make all shell scripts executable:

{code}apache-tomcat-6.0.14$ chmod u+x bin/*.sh{code}

h2. Start Tomcat

Execute the following command to start the Tomcat server to verify it is functioning properly:

{code:none}apache-tomcat-6.0.14$ bin/startup.sh 
Using CATALINA_BASE:   /your/tomcat/installation/ lib/           temp/          work/
NOTICE         RUNNING.txt    conf/          logs/          webapps/

Make shell scripts executable

The shell scripts in the Tomcat installation are not executable by default, so in order to execute them, you must set mark them as executable. If you unpacked the Tomcat tar.gz file, the scripts are already executable. The following command will make all shell scripts executable:

Code Block
apache-tomcat-6.0.14 Using CATALINA_HOME: /your/tomcat/installation/apache-tomcat-6.0.1414$ chmod u+x bin/*.sh

Start Tomcat

Execute the following command to start the Tomcat server to verify it is functioning properly:

Code Block

	none
	none

apache-tomcat-6.0.14$ bin/startup.sh 
Using CATALINA_BASE:  
Using CATALINA_TMPDIR: /your/tomcat/installation/apache-tomcat-6.0.14/temp
Using JRECATALINA_HOME:        /your/javatomcat/installation{code}

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

h2. Verify Tomcat is Running

Visit [/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.

Verify Tomcat is Running

Visit http://localhost:8080/

...

and

...

you

...

should

...

see

...

the

...

Tomcat

...

welcome

...

page.

Stop Tomcat

Shutdown Tomcat by executing the following command:

Code Block

	none
	none




h2. Stop Tomcat

Shutdown Tomcat by executing the following command:

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

*

NOTE:

...

Your

...

output

...

will

...

be

...

different

...

from

...

the

...

example

...

above

...

due

...

to

...

differences

...

in

...

installation

...

location.

...

Anchor
install-openejb
install-openejb

...

Install

...

OpenEJB

...

Once
...
Tomcat
...
has
...
been
...
installed,
...
the
...
OpenEJB
...
plugin
...
for
...
Tomcat
...
can
...
be
...
installed.
...
The
...
commands
...
in
...
this
...
example
...
are
...
executed
...
within
...
the
...
Tomcat
...
installation
...
directory.
...

Unpack

...

OpenEJB

...

Tomcat

...

plugin

...

in

...

Tomcat

...

webapps

...

directory

...

1. Change

...

to

...

the

...

webapps

...

directory:

{:

Code Block

none
	none

}apache-tomcat-6.0.14$ cd webapps{code}

Unpack the

2. Unpack the openejb-tomcat-3.0.0-SNAPSHOT-bin.zip

...

file.

Code Block

	none
	none



{code:none}apache-tomcat-6.0.14/webapps$ jar -xvf ../openejb-tomcat-3.0.0-SNAPSHOT-bin.zip
  created: openejb/
  created: openejb/WEB-INF/
  created: openejb/lib/
 inflated: openejb/lib/geronimo-javamail_1.4_spec-1.1.jar
 inflated: openejb/lib/xbean-finder-3.1.jar
...snip...

3. The OpenEJB directory should contain the following files:

Code Block

	none
	none

{code}

The OpenEJB directory should contain the following files:

{code:none}apache-tomcat-6.0.14/webapps$ ls openejb
WEB-INF/     lib/         openejb.xml
{code}

Return to the Tomcat install directory 

{code:none}apache-tomcat-6.0.14/webapps$ cd ..{code}

h2. Add the OpenEJB listener to Tomcat 

Tomcat listeners must be available in the Tomcat common class loader,

4. Start tomcat again

5. Visit http://localhost:8080/openejb/installer^{Image Added} and click on the install button

6. Assuming you don't get any errors, reboot tomcat

At this point OpenEJB will be installed

Info

title	IN CASE YOU WANT TO INSTALL IT MANUALLY, YOU CAN SKIP STEPS 4,5 AND 6 ABOVE AND FOLLOW THESE STEPS

Wiki Markup


Return to the Tomcat install directory 

{code:none}apache-tomcat-6.0.14/webapps$ cd ..{code}

h2. Add the OpenEJB listener to Tomcat 

Tomcat listeners must be available in the Tomcat common class loader, so the openejb-loader jar must be copied into the Tomcat lib directory.

{code:none} apache-tomcat-6.0.14$ cp webapps/openejb/lib/openejb-loader-3.0.0-SNAPSHOT.jar lib/{code}

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} 

h2. 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}apache-tomcat-6.0.14$ mv lib/annotations-api.jar lib/annotations-api.jar-INVALID{code}

h2. 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.sh file to enable the OpenEJB javaagent:

{panel:title=bin/catalina.sh}
...snip...
\# Set juli LogManager if it is present
if [ -r "$CATALINA_BASE"/conf/logging.properties ]; then
&nbsp;&nbsp;JAVA_OPTS="$JAVA_OPTS "-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager" "-Djava.util.logging.config.file="$CATALINA_BASE/conf/logging.properties"
fi

{highlight}\# Add OpenEJB javaagent
if [ -r "$CATALINA_BASE"/webapps/openejb/lib/openejb-javaagent-3.0.0-SNAPSHOT.jar ]; then
&nbsp;&nbsp;JAVA_OPTS=""-javaagent:$CATALINA_BASE/webapps/openejb/lib/openejb-javaagent-3.0.0-SNAPSHOT.jar" $JAVA_OPTS"
fi{highlight}

\# ----- 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 example above is an excerpt from the middle of the bin/catalina.sh file.  Search for "Execute" in the file to locate the correct position in the file to add the new lines.

Test an example application

Create a stateless session bean

Create an interface

Code Block

	java
	java


package org.acme;
import javax.ejb.*;
@Remote
public interface Greeting{
	public String greet();
}

Create the bean class

Code Block

	java
	java


package org.acme;
import javax.ejb.*;
@Stateless
public class GreetingBean implements Greeting{
	public String greet(){
		return "I just greeted you buddy";
	}
}

Create a servlet

Code Block

	java
	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();
		}
		
	}
}

Register the servlet in web.xml

Code Block

	xml
	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^{Image Added}
#You should now see the message "I just greeted you buddy"

Wiki Markup
\[OPTIONAL\] Run OpenEJB iTests

Install iTests

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

Code Block

	none
	none

apache-tomcat-6.0.14$ cp openejb-tomcat-3.0.0-SNAPSHOT-itests.war webapps/

Start Tomcat

Code Block

	none
	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

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

Execute the test client

Code Block

	none
	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
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}


{note:title=Useful instructions - Not properly integrated into this page. This info was picked up as is from an email from Dain}
_Information below just put here temporarily so that we don't lose it, needs proper integration with original content_


The installer is still a work in progress (I'm working on it today),
but the currently checked in version works fine on unix.

David's process is correct, but here are the exact steps:

1. copy openejb-tomcat-3.0.0-SNAPSHOT-bin.zip to your Tomcat webapps
directory
2. make sure Tomcat is running
3. visit http://localhost:8080/openejb/installer
4. Assuming you don't get any errors, reboot tomcat

At this point OpenEJB will be installed just like the manual
instructions (http://cwiki.apache.org/confluence/display/OPENEJB/New
+Instructions).  As for your applications, simply include EJBs in
your war WEB-INF/classes or WEB-INF/lib/*.jar using either annotated
classes or via a META-INF/ejb-jar.xml file.

Restrictions
o The installer only runs on Unix.  Windows support will require a
tweaked catalina.bat and a work around for Windows file locking.
Cygwin won't work either and will require even more work arounds in
the Unix code to deal with pathing problems.
o 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.
o Annotations in servlets to OpenEJB resources (EJBs,
PersistenceUnits, Topics, Queues, DataSources, etc) don't resolve.
You will have to use global JNDI for the time being.
o There is no security integration.  I suggest you don't even try
using secured EJB in Tomcat embedded mode yet.

Hope this helps,

o We only support Tomcat 6 and I suggest you use the newest version
as I haven't tested any older 6 revisions.  We could potentially
support older versions of Tomcat if there were enough demand, but I
doubt there will be since OpenEJB 3 requires Java5.
{note}......
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
.........................................
........................
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
_________________________________________________

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.

Child pages

Page History

Versions Compared

Old Version 6

New Version 7

Key

Install Tomcat 6

Unpack Tomcat

Make shell scripts executable

Start Tomcat

Verify Tomcat is Running

Stop Tomcat

Anchorinstall-openejbinstall-openejb

Install

OpenEJB

Once ... Tomcat ... has ... been ... installed, ... the ... OpenEJB ... plugin ... for ... Tomcat ... can ... be ... installed. ... The ... commands ... in ... this ... example ... are ... executed ... within ... the ... Tomcat ... installation ... directory....

Unpack

OpenEJB

Tomcat

plugin

in

Tomcat

webapps

directory

1. Change

to

the

webapps

directory:

2. Unpack the openejb-tomcat-3.0.0-SNAPSHOT-bin.zip

file.

3. The OpenEJB directory should contain the following files:

4. Start tomcat again

5. Visit http://localhost:8080/openejb/installerImage Added and click on the install button

6. Assuming you don't get any errors, reboot tomcat

Test an example application

Create a stateless session bean

Create an interface

Create the bean class

Create a servlet

Register the servlet in web.xml

Package the war

Drop the war in the tomcat webapps directory

Send a request to the servlet

Wiki Markup\[OPTIONAL\] Run OpenEJB iTests

Install iTests

Start Tomcat

Execute the test client

Anchor
install-openejb
install-openejb

Once
...
Tomcat
...
has
...
been
...
installed,
...
the
...
OpenEJB
...
plugin
...
for
...
Tomcat
...
can
...
be
...
installed.
...
The
...
commands
...
in
...
this
...
example
...
are
...
executed
...
within
...
the
...
Tomcat
...
installation
...
directory.
...

5. Visit http://localhost:8080/openejb/installer^{Image Added} and click on the install button

Wiki Markup
\[OPTIONAL\] Run OpenEJB iTests