<?xml version="1.0"?>
<document url="http://openejb.sf.net/tomcat-adapter.xml">
  <properties>
    <title>Accessing EJBs from Servlets</title>
    <sub-title>OpenEJB embedded in Tomcat</sub-title>
  </properties>
  <body>
  <sideimg src="images/diagram-tomcat-adapter.gif" width="240" height="500"/>

<section title="Introduction" ref-id="intro">
<p>
Servlets can access beans from OpenEJB using either the Local (IntraVM) Server 
or the default Remote Server
</p> 

<p>
This document is a starting point for using OpenEJB in Tomcat and will evolve based 
on user contributions.  If you wish to contribute to this document, please email the
text to the <a href="lists.html#openejb-user">OpenEJB User list</a>.
</p>
</section>

<section title="Accessing EJBs locally from Tomcat" ref-id="local.access">
<p>
Local Server access:
</p>

<p>
<file name="your servlet">
  ...
  try{
    Properties properties = new Properties();
    
    properties.put(Context.INITIAL_CONTEXT_FACTORY, 
        "org.openejb.client.LocalInitialContextFactory");
    
    InitialContext ctx = new InitialContext(properties);
    
    Object obj = ctx.lookup("my/bean/Foo");
    
    FooHome ejbHome = (FooHome)
        PortableRemoteObject.narrow(obj, FooHome.class);
  } catch (Exception e){
    e.printStackTRace();
  }
  ...
</file>
</p> 

<p>
Or simply
</p>

<p>
<file name="your servlet">
  ...
  try{
    
    FooHome ejbHome = (FooHome)new InitialContext().lookup(
                            "java:openejb/ejb/my/bean/Foo");
  
  } catch (Exception e){
    e.printStackTRace();
  }
  ...
</file>
</p>

<p>
Now keep in mind, that is not J2EE spec compliant.  Also keep in mind that we provide it 
as a convenience, so if there is something you don't like or think should be changed, 
send code.
</p>

</section>


<section title="Accessing EJBs remotely from Tomcat" ref-id="remote.access">

<p>
Servlets can access beans from OpenEJB using either the Local (IntraVM) Server 
or the default Remote Server
</p> 

<p>
Remote Server access:
</p>

<p>
<file name="your servlet">
  ...
  try{
    Properties p = new Properties();
    p.put("java.naming.factory.initial", 
    "org.openejb.client.RemoteInitialContextFactory");
    p.put("java.naming.provider.url", "25.14.3.92:4201");
    p.put("java.naming.security.principal", "myuser");
    p.put("java.naming.security.credentials", "mypass");
        
    InitialContext ctx = new InitialContext(p);
    
    Object obj = ctx.lookup("my/bean/Foo");
    
    FooHome ejbHome = (FooHome)
        PortableRemoteObject.narrow(obj, FooHome.class);
  } catch (Exception e){
    e.printStackTRace();
  }
  ...
</file>
</p> 

<p>
The java.naming.security.principal and java.naming.security.credentials parameters are
not used at the moment, but it is a good idea to use them as it will reduce the amount 
of patching you need to do when they are activated.
</p>

</section>


<section title="OpenEJB-Tomcat FAQ" ref-id="faq">
    
    <section title="How does the Local (IntraVM) Server work?" ref-id="how.local">
    <p>
    When OpenEJB runs in the same VM as Tomcat and Servlets are accessing OpenEJB, you're 
    really using OpenEJB as an embedded EJB Server inside Tomcat.  This is identical to 
    using embedded database servers like InstantDB and Cloudscape inside Tomcat.
    </p>
    
    <p>
    OpenEJB is the only EJB server that I know of that you can run as an embedded 
    library, so the fact that you can even do it is a real feather in our cap.  If 
    anyone knows of another, please tell me.
    </p>
    
    <p>
    In fact, anyone already using InstantDB or Cloudscape as embedded database servers in  
    Tomcat could just as easily use OpenEJB as an embedded EJB Server and add instant EJB 
    support as well.  OpenEJB can easily play with InstantDB or Cloudscape.
    </p>
    </section>

    
    <section title="What Security Service do I get?" ref-id="security">
    <p>
    A special adapter needs to be written so that OpenEJB can use the Security capabilities 
    of Tomcat and get the security credintials from calls by servlets.  If 
    you are interested in writing this, send mail to the OpenEJB 
    development list. </p> </section>
</section>

</body>
</document>
