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

<section title="Notes" ref-id="intro">
<p>
This is a rough draft of how to set up Tomcat with OpenEJB on Window's 2000.
These are the minimum steps for integrating OpenEJB into Tomcat. The commands 
in this document are specifically for a Window's DOS prompt and Window's environment.
Please feel free to add to this document or email the 
<a href="mailto:openejb-user@lists.sourceforge.net">openejb-user</a> 
mailing list with your suggetions. <b>Your suggestions are always welcome!</b>
</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>
Here's the version of Window's and Java that I'm using:
<code-block>
Microsoft Windows 2000 [Version 5.00.2195]
(C) Copyright 1985-2000 Microsoft Corp.
<br/>
C:\>java -version
java version "1.4.1-rc"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.1-rc-b19)
Java HotSpot(TM) Client VM (build 1.4.1-rc-b19, 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.
</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><br/>
<br/>
Go into the latest version and click on the bin directory. 
If you have version 1.4.x of the Java 2 SDK you could download:
<b>jakarta-tomcat-4.x.x-LE-jdk14.exe</b> - which is a lighter version for 1.4.x
and makes use of the libraries that version 1.4.x has.  
Otherwise download <b>jakarta-tomcat-4.x.x.exe</b> which has the libraries that all 
versions below Java 2 SDK 1.4.x are missing.  
</p>

<note>
As an alternative to the self executable Tomcat download for Window's, you may also download the
zip version named: jakarta-tomcat-4.x.x.zip or jakarta-tomcat-4.x.x-LE-jdk14.zip. Unzip this version
into a directory instead of installing via the Window's installer.  The main difference between the two is that the zip
version does not have an NT Service installer or Start menu additions, so you would have to start/stop Tomcat manually.
<br/><br/>
If you choose to download the zip version of Tomcat, unzip it to a directory that makes sense to you
(such as C:\) and follow the post Tomcat install directions.  The start/stop Tomcat
utility will not be in Start->Programs->Apache Tomcat 4.1, instead they will be in C:\tomcat-4.x.x\bin
and you will need to run them manually by double clicking on them.  The rest of the Tomcat directory structure will 
be the same in both versions.
</note>

<p>
Install Tomcat
</p>
<p>
Go to the directory you downloaded and double click jakarta-tomcat-xxx.exe.  An install
shield will pop up and ask you for several options.  You may wish to click the check box that
installs Tomcat as an NT service.<br/>
</p>
<p>
<img src="images/tomcat_windows_nt_service.jpg" width="426" height="288" border="0" alt=""/>
</p>
<p>
Once Tomcat is finished installing, it will automatically start up and you can test it by
visiting this link: <a href="http://localhost:8080" target="_blank">http://localhost:8080</a>.  If there are
any problems, consult the Tomcat documentation on their website.
</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> - download the zip version of OpenEJB.  If you do not
have a zip utility, you can get WinZip here: 
<a href="http://download.com.com/3000-2250-10161502.html" target="_blank">
http://download.com.com/3000-2250-10161502.html</a>
</p>
<p>
Unpack OpenEJB 
</p>
<p>
Open your zip utility and unpack OpenEJB into the C:\ folder, or one that makes sense to you.
For our examples, we'll unpack it into c:\openejb-0.9.0
</p>
</section>

<section title="Hook them together" ref-id="download.openejb">
<p>
 Go to the Tomcat Dir.  In our case it should be:
 <b>C:\Program Files\Apache Group\Tomcat 4.1</b>
</p>

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

<p>
We'll want to copy <b>openejb_loader-0.9.0.war</b> from the OpenEJB dist directory
to the Tomcat webapps directory.
</p>

<img src="images/tomcat_windows_dist_dir.jpg" width="552" height="381" border="0" alt=""/>
<img src="images/tomcat_windows_webapps_dir.jpg" width="552" height="381" border="0" alt=""/>

<p>
If you add openejb_loader-0.9.0.war to the webapps directory while Tomcat is running, it
should automatically unpack the file and create a openejb_loader-0.9.0 
folder. If it doesn't automatically extract, check the server.xml file 
that comes with Tomcat.
</p>


<p>
Now, let the OpenEJB Loader webapp know where to find your OpenEJB 
distribution by setting the openejb.home init-param.
</p>
<p>
Open the web.xml file in the directory 
webapps\openejb_loader-0.9.0\WEB-INF.  Uncomment the openejb.home 
init-param then change the value from the default value to the actual 
path of your OpenEJB home directory.
</p>

<img src="images/tomcat_windows_webxml.gif" width="567" height="402" border="0" alt=""/>
</section>

<section title="Restart Tomcat" ref-id="restart">

<p>
Now, stop Tomcat and then start it again.
</p>

<img src="images/tomcat_windows_stop.gif" width="395" height="186" border="0" alt=""/>

<p>
 At this point, you're actually finished.
 All the libraries you need are in place.
 </p>

 <p>
 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 OpenEJB Loader webapp , so no other
JNDI options are needed by your servlets 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>
C:\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>
C:\Program Files\Apache Group\Tomcat 4.1\webapps\examples\WEB-INF\classes
</code>
</p>
<p>
<file name="HelloOpenEJB.java"><![CDATA[
import java.io.*;
import java.util.*;
import javax.servlet.*;
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();

        //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, 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>
<section title="What if it Didn't Work?" ref-id="didnotwork">
<p>
1. Try re-starting Tomcat. The war file that was copied or the environment
variable that we set may not have gotten picked up by Tomcat.<br/>
2. Make sure the openejb.home init-param in the web.xml file points 
to where you installed OpenEJB.<br/>
3. Check C:\Program Files\Apache Group\Tomcat 4.1 to see if there is
an openejb.log file.<br/>
4. Send an email to the email list <a href="mailto:openejb-user@lists.sourceforge.net">
openejb-user@lists.sourceforge.net</a> and give a thorough explain the problem.
</p>
</section>

</body>
</document>