<?xml version="1.0"?>
<document url="http://openejb.sf.net/embedded.xml" toc="none">
  <properties>
    <title>Hello World!</title>
    <sub-title>A basic EJB example</sub-title>
  </properties>
  <body>

<section title="Before starting" ref-id="before">
    
<p>
This example assumes you have already downloaded and installed OpenEJB in the 
directory c:\openejb. Refer to the <a href="quickstart.html">QuickStart Guide</a> if you 
haven't yet installed OpenEJB.
</p>
<p>We also assume that you are running your client from the directory c:\my\app.</p>

</section>

<section title="Create the bean class" ref-id="bean.class">
<p>
First, create the package where we will place our ejb and application files.
</p>

<p>Windows</p>
<command>c:\my\app> mkdir org</command><br/>
<command>c:\my\app> mkdir org\acme</command>
<p>Linux/Unix</p>
<command>[user@host app]# mkdir org</command><br/>
<command>[user@host app]# mkdir org/acme</command>

<p>
In your favorite editor, create the file below.
</p>
<p>
<file name="c:\my\app\org\acme\HelloBean.java">
package org.acme;

import java.rmi.RemoteException;
import javax.ejb.*;

public class HelloBean implements SessionBean {
  private SessionContext sessionContext;
  public void ejbCreate() {
  }
  public void ejbRemove() {
  }
  public void ejbActivate() {
  }
  public void ejbPassivate() {
  }
  public void setSessionContext(SessionContext sessionContext) {
    this.sessionContext = sessionContext;
  }
  public String sayHello() throws java.rmi.RemoteException {
    return "Hello World!!!!!";
  }
}
</file>
</p> 
</section>


<section title="Create the EJB Home interface" ref-id="ejbhome">
<p>
<file name="c:\my\app\org\acme\HelloHome.java">
package org.acme;

import java.rmi.*;
import javax.ejb.*;
import java.util.*;

public interface HelloHome extends EJBHome {
  public HelloObject create() throws RemoteException, CreateException;
}
</file>
</p> 
</section>

<section title="Create the EJB Object interface" ref-id="ejbobject">
<p>
<file name="c:\my\app\org\acme\HelloObject.java">
package org.acme;

import java.rmi.*;
import javax.ejb.*;
import java.util.*;

public interface HelloObject extends EJBObject {
  public String sayHello() throws RemoteException;
}
</file>
</p> 
</section>


<section title="Create the ejb-jar.xml" ref-id="ejb-jar.xml">
<p>
Create a META-INF directory to put your ejb-jar.xml into.
</p>


<p>Windows</p>
<command>c:\my\app> mkdir META-INF</command>
<p>Linux/Unix</p>
<command>[user@host app]# mkdir META-INF</command>

<p>
Create am ejb-jar.xml file in your META-INF directory.
</p>


<p>
<file name="c:\my\app\META-INF\ejb-jar.xml">
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;ejb-jar&gt;
  &lt;enterprise-beans&gt;
    &lt;session&gt;
      &lt;ejb-name&gt;Hello&lt;/ejb-name&gt;
      &lt;home&gt;org.acme.HelloHome&lt;/home&gt;
      &lt;remote&gt;org.acme.HelloObject&lt;/remote&gt;
      &lt;ejb-class&gt;org.acme.HelloBean&lt;/ejb-class&gt;
      &lt;session-type&gt;Stateless&lt;/session-type&gt;
      &lt;transaction-type&gt;Container&lt;/transaction-type&gt;
    &lt;/session&gt;
  &lt;/enterprise-beans&gt;
  &lt;assembly-descriptor&gt;
    &lt;container-transaction&gt;
      &lt;method&gt;
        &lt;ejb-name&gt;Hello&lt;/ejb-name&gt;
        &lt;method-name&gt;*&lt;/method-name&gt;
      &lt;/method&gt;
      &lt;trans-attribute&gt;Required&lt;/trans-attribute&gt;
    &lt;/container-transaction&gt;
  &lt;/assembly-descriptor&gt;
&lt;/ejb-jar&gt;
</file>
</p> 
</section>

<section title="Compile the EJB" ref-id="compile">
<p>
Compile your bean.
</p> 

<p>Windows</p>
<command>c:\my\app> javac org\acme\*.java</command>
<p>Linux/Unix</p>
<command>[user@host app]# javac org/acme/*.java</command>
<p>
Make sure you don't make the mistake of trying to compile your classes 
while sitting inside the org/acme/ directory.
</p> 

<p>
<note>
To compile an EJB, you need to have Sun's EJB library
in your classpath.  One has been included for you
in the directory lib/ejb-1.0.jar
</note>
</p> 

</section>

<section title="Package the EJB" ref-id="jar">
<p>
Now, package your EJB classes and your META-INF directory into a jar.
</p>

<p>Windows</p>
<command>C:\my\app> jar cvf myHelloEjb.jar org META-INF</command>
<p>Linux/Unix</p>
<command>[user@host app]# jar cvf myHelloEjb.jar org META-INF</command>

<p>
That command should give you output like the following.
</p>
<file>
added manifest
adding: org/(in = 0) (out= 0)(stored 0%)
adding: org/acme/(in = 0) (out= 0)(stored 0%)
adding: org/acme/HelloBean.class(in = 946) (out= 467)(deflated 50%)
adding: org/acme/HelloObject.class(in = 234) (out= 177)(deflated 24%)
adding: org/acme/HelloHome.class(in = 263) (out= 188)(deflated 28%)
ignoring entry META-INF/
ignoring entry META-INF/MANIFEST.MF
adding: META-INF/ejb-jar.xml(in = 733) (out= 319)(deflated 56%)
</file>
<p>
Check to make sure at least the three classes are there and the 
ejb-jar.xml is there and that everything is in the directories you see 
above.</p>


</section>

<section title="Deploy the EJB jar" ref-id="deploy">
<p>
Use the OpenEJB <a href="deploy.html">Deploy Tool</a> to deploy your jar.
</p> 

<p>Windows</p>
<command>C:\my\app> cd C:\openejb</command><br/>
<command>C:\openejb> openejb.bat deploy -a -m c:\my\app\myHelloEjb.jar</command>
<p>Linux/Unix</p>
<command>[user@host app]# cd /openejb</command><br/>
<command>[user@host openejb]# ./openejb.sh deploy -a -m /my/app/myHelloEjb.jar</command>

<p>
<note>
Since the OpenEJB deployment tool writes to your jar file, make sure that 
no other programs are using it when you deploy (i.e. if you use an editor 
such as Forte for Java to create the jar file, that editor may still be 
using it). If you get an error such as "Error in writing existing jar 
file" close any programs that may be using the jar and try deploying 
again. 
</note>
</p>
</section>

<section title="A basic client application" ref-id="deploy">

<p>
Create a basic client application to access your HelloWorld bean.
</p> 

<p>
<code name="c:\my\app\org\acme\HelloWorld.java">
package org.acme;

import javax.rmi.*;
import javax.naming.*;
import java.util.*;

public class HelloWorld {

 public static void main( String args[]) {
  try{
    
    Properties p = new Properties();
    
    <comment>//The JNDI properties you set depend</comment>
    <comment>//on which server you are using.</comment>
    <comment>//These properties are for the Remote Server.</comment>
    p.put("java.naming.factory.initial", "org.openejb.client.RemoteInitialContextFactory");
    p.put("java.naming.provider.url", "127.0.0.1:4201");
    p.put("java.naming.security.principal", "myuser");
    p.put("java.naming.security.credentials", "mypass");    
    
    <comment>//Now use those properties to create</comment>
    <comment>//a JNDI InitialContext with the server.</comment>
    InitialContext ctx = new InitialContext( p );
    
    <comment>//Lookup the bean using it's deployment id</comment>
    Object obj = ctx.lookup("/Hello");
    
    <comment>//Be good and use RMI remote object narrowing</comment>
    <comment>//as required by the EJB specification.</comment>
    HelloHome ejbHome = (HelloHome)
        PortableRemoteObject.narrow(obj,HelloHome.class);

    <comment>//Use the HelloHome to create a HelloObject</comment>
    HelloObject ejbObject = ejbHome.create();
    
    <comment>//The part we've all been wainting for...</comment>
    String message = ejbObject.sayHello();

    <comment>//A drum roll please.</comment>
    System.out.println( message );
    
  } catch (Exception e){
    e.printStackTrace();
  }
 }
}

</code>
</p> 

<p>
JNDI properties for the <a href="embedded.html">Local Server</a>
would look like the following.  Be sure to read the Local Server
<a href="embedded.html">documentation</a> if you run into
any problems.
</p> 

<p>
<code>
Properties p = new Properties();

p.put("java.naming.factory.initial", 
    "org.openejb.client.LocalInitialContextFactory");
p.put("openejb.home", "c:\\openejb");
    
InitialContext ctx = new InitialContext(p);
</code>
</p>

<p>
JNDI properties for the <a href="remote-server.html">Remote Server</a>
would look like the following.  Be sure to start the Remote Server before
running your application.  See the Remote Server 
<a href="remote-server.html">documentation</a> for more information on 
using the Remote Server.
</p> 

<p>
<code>
Properties p = new Properties();
p.put("java.naming.factory.initial", "org.openejb.client.RemoteInitialContextFactory");
p.put("java.naming.provider.url", "127.0.0.1:4201");
p.put("java.naming.security.principal", "myuser");
p.put("java.naming.security.credentials", "mypass");
    
InitialContext ctx = new InitialContext(p);
</code>
</p>

<p>
Update the HelloWorld.java to contain the right JNDI properties.
</p> 

</section>

<section title="Compile the application" ref-id="compile.app">
<p>
Compile your client code.  Don't forget to add your EJBs in the 
classpath!
</p>
 
<p>Windows</p>
<command>C:\my\app> javac org\acme\HelloWorld.java</command>
<p>Linux/Unix</p>
<command>[user@host app]# javac org/acme/HelloWorld.java</command>

<p>
<note>
To compile this application, you need to have Sun's 
JNDI library in your classpath.  One has been included for you
in the directory lib/jndi_1.2.1.jar
</note>
</p> 

</section>

<section title="Run it!" ref-id="run.it">
<p>
When you run OpenEJB in embedded server mode, you need all the server libraries
in your classpath along with your beans and client code.  Here is a simple script 
that will add those classes automactically.  Feel free to use this script, or add
it's contents to you own scripts.
</p> 

<p>
Example Windows Batch script.
<file name="c:\my\app\RunIt.bat">
@echo off

set OPENEJB_HOME=C:\openejb
set PATH=%PATH%;%OPENEJB_HOME%\bin
set JAVA=%JAVA_HOME%\bin\java

set CP=
for %%i in (%OPENEJB_HOME%\lib\*.jar) do call cp.bat %%i 
for %%i in (%OPENEJB_HOME%\dist\*.jar) do call cp.bat %%i 
for %%i in (%OPENEJB_HOME%\beans\*.jar) do call cp.bat %%i 
set CLASSPATH=%JAVA_HOME%\lib\tools.jar;%CP%

%JAVA% %OPTIONS% -Dopenejb.home=%OPENEJB_HOME% org.acme.HelloWorld
</file>
</p> 

<p>
Example Linux/Unix Batch script.
<file name="/my/app/RunIt.sh">
#!/bin/sh

# Set OPENEJB_HOME to the full path where you 
# installed your OpenEJB distribution
export OPENEJB_HOME=/openejb

# Set JAVA_HOME to the full path where you 
# installed your JDK distribution
export JAVA_HOME=/usr/java/jdk1.3.1



export PATH=${PATH}:${OPENEJB_HOME}/bin
export JAVA=${JAVA_HOME}/bin/java

export CP=
CP=`echo $OPENEJB_HOME/lib/*.jar | tr ' ' ':'`:${CP}
CP=`echo $OPENEJB_HOME/dist/*.jar | tr ' ' ':'`:${CP}
CP=`echo $OPENEJB_HOME/beans/*.jar | tr ' ' ':'`:${CP}
export CLASSPATH=$JAVA_HOME/lib/tools.jar:${CP}

$JAVA -Dopenejb.home=$OPENEJB_HOME org.acme.HelloWorld
</file>
</p> 

<p>
Now run the script!
</p> 
<p>Windows</p>
<command>C:\my\app> RunIt</command>
<p>Linux/Unix</p>
<command>[user@host app]# ./RunIt.sh</command>
<p>
</p> 

</section>


<section title="What if it didn't work" ref-id="problems">
<p>
If you ran into any problems, first check your openejb.log file at c:\openejb\openejb.log.
Look for any lines that begin with <b><term>"WARN"</term></b>, 
<b><term>"ERROR"</term></b>, or <b><term>"FATAL"</term></b>.
</p> 
<p>
If the log file doesn't help you, email it to the OpenEJB <a href="lists.html#openejb-user">
user mailing list</a> and let people know you are using the Hello World example.
</p> 
</section>



</body>
</document>

