<?xml version="1.0"?>
<document url="http://openejb.sf.net/tomcat-setup.xml">
  <properties>
    <title>David's notes on setting up Tomcat with OpenEJB</title>
  </properties>
  <body>
  <sideimg src="images/diagram-tomcat-adapter.gif" width="240" height="500"/>

<section title="Notes" ref-id="intro">
<p>
These are my notes from writing the Tomcat/OpenEJB integration.  These are 
the minimum steps for integrating OpenEJB into Tomcat. The commands in this
document are specifically for a bash shell in either Linux, Unix, Mac OS X 
or Windows with Cygwin. 
</p>

<p>
The steps will be the same for the Windows Command Prompt, but the 
syntax of the commands themselves will obviously be different.  Aside from 
that, there isn't a whole lot of information on what is going on behind 
the sences.  So, I encourage *anyone* to feel completely welcome (perhaps 
obligated) to rewrite this document.  
</p>

<p>
<i>Anyone...anyone...Bueller...Bueller....</i>
</p>
<p>
Regardless, this should help people get started. So here goes.
</p>

</section>
<section title="Before we start" ref-id="intro">

<p>
We always tell users to send us info on their OS and what version of 
OpenEJB, Java, or any other programs they are using when they submit 
support requests.  So, I guess it's only fair I do the same.  
</p>

<p>
Here is some 
information about my setup </p>

<p>

<code-block>
dblevins@Miles /home/j2ee
$ pwd
/home/j2ee

dblevins@Miles /home/j2ee
$ uname -a
CYGWIN_NT-5.0 Miles 1.3.12(0.54/3/2) 2002-07-06 02:16 i686 unknown

dblevins@Miles /home/j2ee
$ java -version
java version "1.3.1"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.1-b24)
Java HotSpot(TM) Client VM (build 1.3.1-b24, mixed mode)
</code-block>
</p>
</section>

<section title="Installing Everything" ref-id="intro">
<section title="Install Tomcat" ref-id="download.tomcat">
<p>
If you don't already have Tomcat on your machine, download the 
Tomcat version of your choice from Apache we recommend the latest
version as it has the most up-to-date libraries) In our example,
we'll be using version 4.1.12.
</p>
<p>
<a href="http://jakarta.apache.org/builds/jakarta-tomcat-4.0/release/" target="_blank">
http://jakarta.apache.org/builds/jakarta-tomcat-4.0/release/</a>
</p>
<p>
Unpack Tomcat
</p>
<p>
<code-block>
dblevins@Miles /home/j2ee
$ tar xzvf jakarta-tomcat-4.1.12.tar.gz
</code-block>
</p>

</section>

<section title="Install OpenEJB" ref-id="download.openejb">
<p>
You need OpenEJB 0.9.0 or higher, any older versions of OpenEJB will not 
work.  You can get that here: <a href="http://openejb.sf.net/download.html" target="_blank">
http://openejb.sf.net/download.html</a>
</p>
<p>
Unpack OpenEJB 
</p>
<p>
<code-block>
dblevins@Miles /home/j2ee
$ tar xzvf openejb-0.9.0.tar.gz
</code-block>
</p>
</section>

<section title="Hook them together" ref-id="download.openejb">
<p>
 Go to the Tomcat Dir
</p>

<p>
<code-block>
dblevins@Miles /home/j2ee
$ cd jakarta-tomcat-4.1.12
</code-block>
</p>

<p>
Pass the OPENEJB_HOME dir into Tomcat
using the CATALINA_OPTS environment variable
</p>    

<p>
<code-block>
dblevins@Miles /home/j2ee/jakarta-tomcat-4.1.12
$ export CATALINA_OPTS='-Dopenejb.home=/home/j2ee/openejb-0.9.0'
</code-block>
</p>

<p>
Add the OpenEJB Loader to Tomcat
</p>    

<p>
<code-block>
dblevins@Miles /home/j2ee/jakarta-tomcat-4.1.12
$ cp ../openejb-0.9.0/dist/openejb_loader-0.9.0.war webapps/
</code-block>
</p>

<p>
 At this point, you're actually finished.
 All the libraries you need are in place.
 Your servlets should use the following
 InitialContextFactory when creating
 an InitialContext to lookup beans
</p>

<p>
<code>org.openejb.client.LocalInitialContextFactory</code>
</p>

<p>
The openejb.home is taken care of for us 
with the CATALINA_OPTS variable, so no other
JNDI options are needed to get an
InitialContext from OpenEJB
</p>
</section>
</section>


<section title="Example Servlet" ref-id="example">
<p>
You can use the OpenEJB Hello World as an
example EJB to test things out. You won't
need to do anything differently.  Deploy
the myHelloEjb.jar just as described.
</p>

<p>
<a href="http://openejb.sourceforge.net/hello-world.html" target="_blank">http://openejb.sourceforge.net/hello-world.html</a>
</p>

<p>
Once deployed, the myHelloEjb.jar should be in the beans directory.
</p>

<p>
<code>
openejb-0.9.0/beans/myHelloEjb.jar
</code>
</p>

<p>
You can use the HelloOpenEJB servlet 
below as an example of a
servlet that looks up beans from OpenEJB.
</p>

<p>
It uses the HelloBean created in the 
OpenEJB Hello World document, so you'll
need to run through that first.
You can put the servlet in the following 
webapps directory
</p>    

<p>
<code>
jakarta-tomcat-4.1.12/webapps/examples/WEB-INF/classes
</code>
</p>
<p>

<file name="HelloOpenEJB.java"><![CDATA[
import javax.servlet.http.*; 
import javax.naming.*; 
import javax.rmi.PortableRemoteObject; 

import org.acme.*; 

public class HelloOpenEJB extends HttpServlet { 

    String factory = "org.openejb.client.LocalInitialContextFactory"; 

    public void doGet(HttpServletRequest request, HttpServletResponse response) 
        throws IOException, ServletException 
    { 
    PrintWriter out = response.getWriter();

    try{
        Properties p = new Properties();
        p.put(Context.INITIAL_CONTEXT_FACTORY, factory );
        InitialContext ctx = new InitialContext( p );

        //Lookup the bean using it's deployment id
        Object obj = ctx.lookup("/Hello");

        HelloHome ejbHome = (HelloHome) 
           PortableRemoteObject.narrow(obj, HelloHome.class); 

        //Use the HelloHome to create a HelloObject 
        HelloObject ejbObject = ejbHome.create(); 

        // Set content type.  If not done, only IE will be able 
        // to interpret that it's HTML.  Otherwise, you'll 
        // get nothing but tags and content, not HTML.
        response.setContentType("text/html");

        //The part we've all been wainting for...
        out.println("<html>");
        out.println("<body>");
        out.println("<head>");
        out.println("<title>Hello World!</title>");
        out.println("</head>");
        out.println("<body>");
        out.println("<h1>"+ ejbObject.sayHello() +"</h1>");
        out.println("</body>");
        out.println("</html>");
        } catch (Exception e){
            response.setContentType("text/plain");
            e.printStackTrace(out);
        }
    }
}]]>
</file>
</p>
<p>
Now you can start Tomcat...
</p>


<p>
<code-block>
dblevins@Miles /home/j2ee/jakarta-tomcat-4.1.12
$ ./bin/startup.sh
Using CATALINA_BASE:   C:\home\j2ee\jakarta-tomcat-4.1.12
Using CATALINA_HOME:   C:\home\j2ee\jakarta-tomcat-4.1.12
Using CATALINA_TMPDIR: /home/j2ee/jakarta-tomcat-4.1.12/temp
Using JAVA_HOME:       C:\program_files\jdk1.3.1
</code-block>
</p>

<p>
Now, pop open your browser and go to the
following URL.
</p>


<p>
<code>
<a href="http://localhost:8080/examples/servlet/HelloOpenEJB" target="_blank">http://localhost:8080/examples/servlet/HelloOpenEJB</a>
</code>
</p>

<p>
Should say "Hello World!!!" on the screen
</p>
</section>
</body>
</document>
