content/embedding-openejb.mdtext

Title: Embedding OpenEJB
OpenEJB embedded in your app, server, IDE, or JUnit
<a name="EmbeddingOpenEJB-Saywhat?!Alocalserver?"></a>
# Say what?! A local server?


Yes, you read correctly. OpenEJB can be embedded and treated as your very
own personal EJB container.

If they can have Local and Remote EJB's, why not Local and Remote EJB
Servers too?

Haven't you ever wanted EJBs without the heavy? I mean you need the "heavy"
eventually, but not while you're developing. Well, there's the advantage of
an EJB implementation that was designed with a very clean and well defined
server-container contract, you can cut the server part out completely!

So, if you wish to access ejbs locally and not in client/server mode, you
can do so by embedding OpenEJB as a library and accessing ejbs through
OpenEJB's built-in IntraVM (Local) Server. Why would someone want to do
this?
* Your application is a server or other middleware
* You want to write an app that can be both stand alonedistributed
* To test your EJBs with JUnit and don't want to start/stop servers and
other nonsense
* Imagine the power from being able to use your IDE debugger to step from
your Client all the way into your EJB and back with no remote debugging
voodoo.


In this case, your application, test suite, IDE, or client 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 an IntraVM Client.

There are some interesting differences though. The IntraVM Server isn't a
heavyweight server as one normally associates with EJB. It doesn't open
connections, launch threads for processing requests, introduce complex
classloading heirarchies, or any of those "heavy" kind of things. All it
does is dish out proxies to your app that can be used to shoot calls right
into the EJB Container. Very light, very fast, very easy for testing,
debugging, developing, etc.

<a name="EmbeddingOpenEJB-AccessingEJBslocally"></a>
# Accessing EJBs locally


Try something like this for a simple IntraVM (Local) Client:


    import FooHome;

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

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




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:

    import FooHome;

    import javax.naming.InitialContext;

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




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.

<a name="EmbeddingOpenEJB-Passinginitializationparameters"></a>
# Passing initialization parameters


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.

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


Refer to the [OpenEJB Specification](spec.html#openejb.api.html)
 for information on the init method or the parameters you can pass to
OpenEJB.

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.


<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>c:\my\app\MyEjbApplication.java</B></DIV><DIV class="codeContent panelContent">
    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();
      }
    }
    }




<a name="EmbeddingOpenEJB-Settheopenejb.homevariable"></a>
# Set the openejb.home variable


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.

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.

*c:\my\app> java -Dopenejb.home=c:\dir\openejb MyEjbApplication*


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.


<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>c:\my\app\MyEjbApplication.java</B></DIV><DIV class="codeContent panelContent">
    ...
    public static void main(String args[]
) {
        
      System.setProperty("openejb.home", "c:\\dir\\openejb");
      ...
      
    }
    ...




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


<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>c:\my\app\MyEjbApplication.java</B></DIV><DIV class="codeContent panelContent">
    ...
    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 );
      ...
    }
    ...




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.

<a name="EmbeddingOpenEJB-EmbeddedOpenEJBFAQ"></a>
# Embedded OpenEJB FAQ


<a name="EmbeddingOpenEJB-Whatdoyoumeanembedded?"></a>
## What do you mean embedded?


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.

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.

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.

<a name="EmbeddingOpenEJB-Moreinfoonopenejb.conffiles"></a>
## More info on openejb.conf files


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.


    <openejb>
    ...

    <Deployments dir="beans\" />
    </openejb>

    
The above deployment path, "beans\", would automatically be expanded to
"c:\dir\openejb\beans".
    
If you want tell OpenEJB to look outside the OPENEJB_HOME, then use an
absolute file path as shown below.
    
    
    <openejb>
    ...
    
    <Deployments dir="beans\" /></openejb>




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


    <openejb>
    ...

    <Deployments dir="beans\" />
    <Deployments dir="c:\my\app\my\beans\" /></openejb>

Furthermore, you can add jars individually to OpenEJB's deployment path by
naming the jar directly.
    
    
    <openejb>
    ...
    
    <Deployments dir="beans\" />
    <Deployments dir="c:\my\app\my\beans\" />
    <Deployments dir="c:\my\special\beans\" />
    <Deployments dir="c:\foo\ejbs\" />
    <Deployments dir="d:\files\ejbjars\" /></openejb>