<?xml version="1.0"?>
<document url="http://openejb.sf.net/embedded.xml">
  <properties>
    <title>Accessing EJBs Locally</title>
    <sub-title>OpenEJB embedded in your app, server, or IDE</sub-title>
  </properties>
  <body>
<sideimg src="images/diagram-local-server.gif" width="240" height="500"/>

<section title="Accessing EJBs locally" ref-id="local.access">
    
<p>
If you wish to access ejbs locally and not in client/server 
mode, for example if your application <i><u>is</u></i> a 
server or other middleware, you can do so by embedding 
OpenEJB as a library and accessing ejbs through OpenEJB's 
built-in IntraVM (Local) Server.
</p>
<p>
<note>
OpenEJB can be <a href="spec.html#openejb.api">initialized</a>
and <a href="spec.html#rpc.invoke.policy">invoked directly</a> as 
an API.  You would do this if you need closer integration with OpenEJB, you
wish to distribute beans using your own distributed object protocol, 
or if you need very advanced control over transaction
and security context propogation. See the <a href="spec.html">OpenEJB
Specification</a> for more information.
</note>
</p> 

<p>In this case, your application, server, or other middleware 
accesses beans as you would from any other EJB Server.  The EJB Server 
just happens to be running in the same virtual machine as
your application.  This EJB Server is thusly called the IntraVM Server, 
and, for all intense purposes, your application or server is an 
IntraVM Client.
</p>

<p>
Try something like this for a simple IntraVM (Local) Client:
</p>

<p>
<file name="c:\my\app\MyEjbApplication.java">

import java.util.Properties;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.rmi.PortableRemoteObject;
import FooHome;

public class MyEjbApplication {

public static void main( String args[]) {
  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>
That would be the simplest spec compliant client you could create.  
If you don't care about spec compliance and just want to "cheat", you can do this:
</p>

<p>
<file name="c:\my\app\MyEjbApplication.java">

import javax.naming.InitialContext;
import FooHome;

public class MyEjbApplication {

public static void main( String args[]) {
  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 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="Passing initialization parameters" ref-id="config">
<p>
When accessing OpenEJB in local (intra-vm) mode, the IntraVM server will instantiate 
OpenEJB for you.  When it instantiates OpenEJB, it puts default values 
for the items in the Properties object OpenEJB needs to actually instantiate.
</p> 

<p>
If you want to pass OpenEJB specific parameters, you can do this in two ways:
<ol>
<li>Call init yourself before any JNDI calls are made</li>
<li>Pass the parameters in the InitialContext hashtable</li>
</ol>    
</p>

<p>
Refer to the <a href="spec.html#openejb.api">OpenEJB Specification</a> for information
on the init method or the parameters you can pass to OpenEJB.
</p>

<p>
Here is an example of passing the initialization parameters in to OpenEJB
via the first InitialContext creation.  I stress, this is only applicable the 
very first time and InitialContext is created within your Virtual Machine.  After
that, OpenEJB will have been initialized and the parameters will be ignored.</p>

<p>
<file name="c:\my\app\MyEjbApplication.java">

import FooHome;
import java.util.Properties;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.rmi.PortableRemoteObject;

public class MyEjbApplication {

public static void main( String args[]) {
  try{
    
    Properties p = new Properties();
    
    p.put(Context.INITIAL_CONTEXT_FACTORY, 
          "org.openejb.client.LocalInitialContextFactory");
    
    p.put("openejb.home", "c:\\dir\\openejb");
    
    p.put("openejb.configuration", 
          "c:\\my\\app\\conf\\openejb.conf");
    
    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> 
    
</section>

<section title="Set the openejb.home variable" ref-id="openejb.home">
<p>
If you use OpenEJB Local Server, you are actually using OpenEJB as an embedded library.
This means when your application starts, OpenEJB will be starting too, in your virtual 
machine.  Odds are you will not want to execute your application in the directory where
OpenEJB was installed, but will want to execute your application where you are developing 
it. This is fine, but you will need to tell OpenEJB where it was installed.  To do this,
set the "openejb.home" system variable.  
</p>
<p>
For example, if OpenEJB was unpacked in the directory in c:\dir\openejb, you can 
set the openejb.home variable as a java vm flag as follows.
</p>
<p>
<command>c:\my\app> java -Dopenejb.home=c:\dir\openejb MyEjbApplication</command>
</p>
<p>
You can also set the openejb.home variable by calling System.setProperty(...) in your 
application before any calls to the OpenEJB Local Server are made.
</p>

<p>
<code name="c:\my\app\MyEjbApplication.java">
...
public static void main(String args[]) {
    
  System.setProperty("openejb.home", "c:\\dir\\openejb");
  ...
  
}
...
</code>
</p>

<p>
As mentioned above, you can pass OpenEJB parameters on your first call to 
the Local Server.
</p>

<p>
<code name="c:\my\app\MyEjbApplication.java">
...
public static void main( String args[]) {
    
  Properties p = new Properties();
  
  p.put(Context.INITIAL_CONTEXT_FACTORY, 
        "org.openejb.client.LocalInitialContextFactory");
  
  p.put("openejb.home", "c:\\dir\\openejb");
      
  InitialContext ctx = new InitialContext( p );
  ...
}
...
</code>
</p>

<p>
When OpenEJB is started, it will look for its configuration files
in the OPENJB_HOME/conf directory.  The paths to beans in your openejb.conf
file are also resolved relative to the openejb.home variable.
</p>
<p>
Here is an example of this.  The openejb.home variable, which we will refer to as 
OPENEJB_HOME, is set to "c:\dir\openejb".  The following relative path in your 
openejb.conf file will be resolved assuming OPENEJB_HOME as the base path.
</p>

<p>
<file name="openejb.conf">

&lt;openejb&gt;
...

&lt;Deployments dir="beans\" /&gt;
&lt;/openejb&gt;

</file>
</p>

<p>
The above deployment path, "beans\", would automatically be expanded to 
"c:\dir\openejb\beans".
</p>

<p>
If you want tell OpenEJB to look outside the OPENEJB_HOME, then use an absolute
file path as shown below.
</p>

<p>
<file name="openejb.conf">

&lt;openejb&gt;
...

&lt;Deployments dir="beans\" /&gt;
<b>&lt;Deployments dir="c:\my\app\my\beans\" /&gt;</b>
&lt;/openejb&gt;

</file>
</p>

<p>
OpenEJB can look in any number of directories for beans, just add those
directories to your openejb.conf file as such.
</p>

<p>
<file name="openejb.conf">

&lt;openejb&gt;
...

&lt;Deployments dir="beans\" /&gt;
&lt;Deployments dir="c:\my\app\my\beans\" /&gt;
<b>&lt;Deployments dir="c:\my\special\beans\" /&gt;</b>
<b>&lt;Deployments dir="c:\foo\ejbs\" /&gt;</b>
<b>&lt;Deployments dir="d:\files\ejbjars\" /&gt;</b>
&lt;/openejb&gt;

</file>
</p>

<p>
Furthermore, you can add jars individually to OpenEJB's deployment path by 
naming the jar directly.
</p>

<p>
<file name="openejb.conf">

&lt;openejb&gt;
...

&lt;Deployments dir="beans\" /&gt;
&lt;Deployments dir="c:\my\app\my\beans\" /&gt;
&lt;Deployments dir="c:\my\special\beans\" /&gt;
&lt;Deployments dir="c:\foo\ejbs\" /&gt;
&lt;Deployments dir="d:\files\ejbjars\" /&gt;
<b>&lt;Deployments jar="c:\the\very\special.jar" /&gt;</b>
&lt;/openejb&gt;

</file>
</p>
</section>

<section title="Embedded OpenEJB FAQ" ref-id="faq">
    <section title="Why do I need so many OpenEJB specific files to implement a client?" ref-id="whats.with.all.the.files">
    <p>
    This is the bane you face when running OpenEJB in the same VM, you have to configure
    OpenEJB as well as your client.  Any server has configuration files, you can't change 
    that.  When you run the server in the same vm as your application, you take on some 
    additional responsibility.  But as I mentioned, we are implementing some things to make 
    even that "additional" responsibility more transparent.
    </p>
    
    <p>
    When your clients run OpenEJB in the same VM using the IntraVM Server, you're using 
    OpenEJB as an embedded EJB Server just like InstantDB and Cloudscape are embedded 
    databases servers.  Just like InstantDB and Cloudscape, OpenEJB needs configuration 
    files and other files to do it's job.
    </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 a 
    product could just as easily use OpenEJB as an embedded EJB Server and add instant EJB 
    support to the product as well.  OpenEJB can easily play with InstantDB or Cloudscape, so 
    it would be pretty slick.  This would be extremely useful for IDEs like Visual Cafe, 
    JBuilder, Visual Age, etc.
    </p>
    </section>

    
    <section title="What Security Service do I get?" ref-id="security">
    <p>
    OpenEJB doesn't come with a valid SecurityService, this has been considered the
    role of the application server vendor since the beginning of the project.  However, 
    no app servers have yet created a SecurityService as we had hoped.  Months down the 
    road, we will create a simple SecurityService provider if one is not contributed.
    </p>
    
    <p>
    OpenEJB can do without a server and use the IntraVM Server, but it still needs a 
    SecurityService, therefore, a fake SecurityService implementation is used by default.
    This PseudoSecurityService just allows you to use OpenEJB without a valid security 
    service, it basically says everyone is a valid user.
    </p>
    </section>
</section>

</body>
</document>
