<html><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Hello OpenEJB World! -- 
              A basic CMP entity bean example</title><link href="default.css" rel="stylesheet"><link href="/images/favicon.ico" rel="SHORTCUT ICON"></head><body marginwidth="0" marginheight="0" leftmargin="0" bottommargin="0" topmargin="0" vlink="#6763a9" link="#6763a9" bgcolor="#ffffff"><a name="top"></a><table height="400" width="712" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#7270c2" align="left" valign="top" width="20"><img border="0" height="1" width="1" src="images/dotTrans.gif"></td><td bgcolor="#7270c2" align="left" valign="top" width="95"><img border="0" height="1" width="1" src="images/dotTrans.gif"></td><td align="left" valign="top" width="7"><img height="1" width="1" border="0" src="images/dotTrans.gif"></td><td align="left" valign="top" width="40"><img border="0" height="6" width="40" src="images/dotTrans.gif"></td><td bgcolor="#5A5CB8" align="left" valign="top" width="430"><img border="0" height="6" width="430" src="images/top_2.gif"></td><td bgcolor="#E24717" align="left" valign="top" width="120"><img src="images/top_3.gif" width="120" height="6" border="0"></td></tr><tr><td align="left" valign="top" bgcolor="#7270c2" width="20"><img height="1" width="1" border="0" src="images/dotTrans.gif"></td><td align="left" valign="top" bgcolor="#7270c2" width="95"><img height="1" width="1" border="0" src="images/dotTrans.gif"></td><td align="left" valign="top" bgcolor="#ffffff" width="7"></td><td align="left" valign="top" width="40"><img border="0" height="1" width="1" src="images/dotTrans.gif"></td><td align="left" valign="middle" width="430"><a href="faq.html"><span class="menuTopOff">[ f a q ]</span></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="http://wiki.codehaus.org/openejb"><span class="menuTopOff">[ w i k i ]</span></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="http://archive.openejb.codehaus.org/user/"><span class="menuTopOff">[ l i s t s ]</span></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="http://cvs.openejb.org/"><span class="menuTopOff">[ c v s ]</span></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="http://jira.codehaus.org/secure/BrowseProject.jspa?id=10401"><span class="menuTopOff">[ b u g s ]</span></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<br><img border="0" height="2" width="1" src="images/dotTrans.gif"></td><td align="left" valign="top" height="20" width="120">&nbsp;</td></tr><tr><td align="left" valign="top" bgcolor="#7270c2" width="20"><img border="0" height="3" width="20" src="images/dotTrans.gif"></td><td align="left" valign="top" bgcolor="#7270c2" width="95"><img border="0" height="3" width="105" src="images/line_sm.gif"></td><td align="left" valign="top" bgcolor="#a9a5de" width="7"><img border="0" height="3" width="7" src="images/line_sm.gif"></td><td align="left" valign="top" width="40"><img border="0" height="3" width="40" src="images/line_light.gif"></td><td align="left" valign="top" width="430"><img border="0" height="3" width="430" src="images/line_light.gif"></td><td align="left" valign="top" width="120"><img height="1" width="1" border="0" src="images/dotTrans.gif"></td></tr><tr><td align="left" valign="top" bgcolor="#7270c2"><img border="0" height="10" width="20" src="images/dotTrans.gif"></td><td align="left" valign="top" bgcolor="#7270c2" width="95"><img border="0" height="2" width="1" src="images/dotTrans.gif"><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">Main</span></td></tr><tr><td align="left" valign="top"><a href="index.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
                Welcome!</span></a></td></tr><tr><td align="left" valign="top"><a href="download.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
                Download</span></a></td></tr><tr><td align="left" valign="top"><a href="lists.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
                Mailing Lists</span></a></td></tr><tr><td align="left" valign="top"><a href="cvs.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
                Source Code</span></a></td></tr><tr><td align="left" valign="top"><a href="contributors.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
                The Team</span></a></td></tr><tr><td align="left" valign="top"><a href="status.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
                Status</span></a></td></tr></table><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">Users</span></td></tr><tr><td align="left" valign="top"><a href="quickstart.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
                Quickstart</span></a></td></tr><tr><td align="left" valign="top"><a href="hello-world.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
                Hello World!</span></a></td></tr><tr><td align="left" valign="top"><a href="cmp_entity_postgresql.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
                CMP Example</span></a></td></tr><tr><td align="left" valign="top"><a href="cmp_guide.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
                CMP Guide</span></a></td></tr><tr><td align="left" valign="top"><a href="deploy.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
                Deploy</span></a></td></tr><tr><td align="left" valign="top"><a href="start-command.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
                Startup</span></a></td></tr><tr><td align="left" valign="top"><a href="validate.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
                Validation</span></a></td></tr><tr><td align="left" valign="top"><a href="config_containers.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
                Configuration</span></a></td></tr><tr><td align="left" valign="top"><a href="properties.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
                Properties</span></a></td></tr></table><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">Servers</span></td></tr><tr><td align="left" valign="top"><a href="embedded.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
                Local Server</span></a></td></tr><tr><td align="left" valign="top"><a href="remote-server.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
                Remote Server</span></a></td></tr><tr><td align="left" valign="top"><a href="tomcat.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
                Tomcat</span></a></td></tr><tr><td align="left" valign="top"><a href="geronimo.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
                Geronimo</span></a></td></tr></table><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">Integrators</span></td></tr><tr><td align="left" valign="top"><a href="whyopenejb.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
                Why OpenEJB</span></a></td></tr><tr><td align="left" valign="top"><a href="containersystem.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
                Overview</span></a></td></tr><tr><td align="left" valign="top"><a href="design_openejb.html"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
                Design</span></a></td></tr><tr><td align="left" valign="top"><a href="OpenEJB_presentaion.ppt"><span class="subMenuOff">&nbsp;&nbsp;&nbsp;
                Presentation</span></a></td></tr></table><img border="0" height="15" width="1" src="images/dotTrans.gif"><br><img border="0" height="3" width="105" src="images/line_sm.gif"><br><A href="http://codehaus.org"><IMG alt="The Codehaus" border="0" height="17" width="88" src="http://www.openejb.org/codehaus-smaller.png"></A></td><td align="left" valign="top" bgcolor="#a9a5de" width="7">&nbsp;</td><td align="left" valign="top" width="40">&nbsp;</td><td valign="top" width="430" rowspan="4"><table width="430" cellspacing="0" cellpadding="0" border="0" rows="2" cols="1"><tr><td align="left" valign="top"><br><img width="200" vspace="0" src="./images/logo_ejb2.gif" hspace="0" height="55" border="0"><br><img src="images/dotTrans.gif" hspace="0" height="7" border="0"><br><span class="pageTitle">Hello OpenEJB World!</span><br><span class="pageSubTitle">A basic CMP entity bean example</span><br><img src="images/dotTrans.gif" hspace="0" height="1" border="0"></td></tr></table><p></p><p></p><br><span class="toc"><a href="#abstract">1<img border="0" height="1" width="5" src="images/dotTrans.gif">Abstract</a><br></span><span class="toc"><a href="#before">2<img border="0" height="1" width="5" src="images/dotTrans.gif">Before starting</a><br></span><span class="toc"><a href="#ejbbean">3<img border="0" height="1" width="5" src="images/dotTrans.gif">Create the entity bean class</a><br></span><span class="toc"><a href="#ejbhome">4<img border="0" height="1" width="5" src="images/dotTrans.gif">Create the entity bean's home interface</a><br></span><span class="toc"><a href="#ejbremote">5<img border="0" height="1" width="5" src="images/dotTrans.gif">Create the entity bean's remote interface</a><br></span><span class="toc"><a href="#ejb-jar.xml">6<img border="0" height="1" width="5" src="images/dotTrans.gif">Create the ejb-jar.xml</a><br></span><span class="toc"><a href="#compile">7<img border="0" height="1" width="5" src="images/dotTrans.gif">Compile the EJB</a><br></span><span class="toc"><a href="#jar">8<img border="0" height="1" width="5" src="images/dotTrans.gif">Package the EJB</a><br></span><span class="toc"><a href="#table">9<img border="0" height="1" width="5" src="images/dotTrans.gif">Create necessary structures in the database (e.g. PostgreSQL)</a><br></span><span class="toc"><a href="#datasource">10<img border="0" height="1" width="5" src="images/dotTrans.gif">Configure the data source</a><br></span><span class="toc"><a href="#deploy">11<img border="0" height="1" width="5" src="images/dotTrans.gif">Deploy the EJB jar</a><br></span><span class="toc"><a href="#client">12<img border="0" height="1" width="5" src="images/dotTrans.gif">A basic client application</a><br></span><span class="toc"><a href="#compile.app">13<img border="0" height="1" width="5" src="images/dotTrans.gif">Compile the application</a><br></span><span class="toc"><a href="#run.it">14<img border="0" height="1" width="5" src="images/dotTrans.gif">Run it!</a><br></span><span class="toc"><a href="#problems">15<img border="0" height="1" width="5" src="images/dotTrans.gif">What if it didn't work</a><br></span><br><a name="abstract"><h2>Abstract</h2></a>
    <p><span class="bodyBlack">
    The aim of this document is to help you out with deploying 
container-managed persistence (CMP) entity beans into OpenEJB. The 
database being used is PostgreSQL 7.2.1, but the steps are described in 
such a way that it should be very easy to switch over to another database 
system (chances are that when you send a request to the OpenEJB <a href="lists.html#openejb-user">user mailing list</a> about how to enable 
your preffered RDBMS in OpenEJB, someone, possibly from the development 
group, will pick it up and modify the document, accordingly). </span></p>

<p><span class="bodyBlack">
The first sections deal with developing a CMP entity bean. It is a CMP 
entity's view of Employee.You may skip them if your bean is ready and 
waiting to be deployed. 
</span></p>

<p><span class="bodyBlack">
We will be configuring PostgreSQL afterwards and creating the table and 
sequence the entity bean is to be mapped to. OpenEJB interacts with 
databases and XML files with the help of Castor. Although Castor plays a 
great role in OpenEJB the document doesn't assume you are already familiar 
with it nor will it be described here thoroughly. It is strongly adviced 
to learn more about Castor, indeed. Please visit <a href="http://castor.exolab.org">Castor home page</a> to find out more.
</span></p>

<p><span class="bodyBlack">
A few words are aimed to rise your awareness of the structure of OpenEJB 
configuration file - openejb.conf - and how to modify it. That is going to 
be a very broad overview and some facts are skipped for the sake of 
simplicity. 
</span></p>

<p><span class="bodyBlack">
The last but not least step will be to start up everything (i.e. OpenEJB, 
PostgreSQL) and access the Employee entity bean from the out-of-process 
client (i.e. the client, which is outside of JVM OpenEJB runs in). 
</span></p>
    
<p><span class="bodyBlack">
Everything was tested on MS Windows 2000 with PostgreSQL 7.2.1 installed 
on Cygwin 1.3.12-2 as well as with Sun JDK 1.3.1_04 and PostgreSQL JDBC 
driver. 
</span></p>
<a name="before"><h2>Before starting</h2></a>
<p><span class="bodyBlack">
This example assumes you have already followed the steps outlined in the 
<a href="hello-world.html">basic EJB example</a>. 
</span></p>
<a name="ejbbean"><h2>Create the entity bean class</h2></a>
<p><span class="bodyBlack">
First, create the package where we will place our ejb and application 
files. 
</span></p>
<span class="command">C:\&gt; cd \my\app</span>
<br>
<span class="command">C:\my\app&gt; mkdir org\acme\employee</span>

<p><span class="bodyBlack">
In your favorite editor, create the file below.
</span></p>
    
<p><span class="bodyBlack">
<table width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#c0c0c0"><i><span class="code-title">C:\my\app\org\acme\employee\EmployeeBean.java</span></i></td></tr><tr><td bgcolor="#e0e0e0"><span class="code-block"><pre>
package org.acme.employee;

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

public class EmployeeBean implements EntityBean
{
  public int id;
  public String firstname;
  public String lastname;
  public String email;
  public EntityContext context;

  public EmployeeBean()
  {
  }

  public Integer ejbCreate( String firstname, String lastname, String email )
    throws CreateException
  {
    this.firstname = firstname;
    this.lastname = lastname;
    this.email = email;
    return null;
  }

  public void ejbPostCreate( String firstname, String lastname, String email )
    throws CreateException
  {
  }

  public void says( String message )
  {
    System.out.println( "[" + firstname + " " + lastname + 
          "(" + id + ") " + email + "] " + message );
  }

  public void setEntityContext( EntityContext context )
    throws EJBException, RemoteException
  {
    this.context = context;
  }

  public void unsetEntityContext()
    throws EJBException, RemoteException
  {
  }

  public void ejbActivate()
    throws EJBException, RemoteException
  {
  }

  public void ejbLoad()
    throws EJBException, RemoteException
  {
  }

  public void ejbPassivate()
    throws EJBException, RemoteException
  {
  }

  public void ejbRemove()
    throws RemoveException, EJBException, RemoteException
  {
  }

  public void ejbStore()
    throws EJBException, RemoteException
  {
  }
}                                                                                   
</pre></span></td></tr></table>
</span></p>
<a name="ejbhome"><h2>Create the entity bean's home interface</h2></a>
<p><span class="bodyBlack">
In your favorite editor, create the file below.
</span></p>

<p><span class="bodyBlack">
<table width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#c0c0c0"><i><span class="code-title">C:\my\app\org\acme\employee\EmployeeHome.java</span></i></td></tr><tr><td bgcolor="#e0e0e0"><span class="code-block"><pre>
package org.acme.employee;

import javax.ejb.CreateException;
import javax.ejb.EJBHome;
import javax.ejb.FinderException;
import java.rmi.RemoteException;

public interface EmployeeHome extends EJBHome
{
  public Employee create( String firstname, String lastname, String email )
    throws RemoteException, CreateException;

  public Employee findByPrimaryKey( Integer id )
    throws RemoteException, FinderException;
}                                                                                   
</pre></span></td></tr></table>
</span></p>
<a name="ejbremote"><h2>Create the entity bean's remote interface</h2></a>
<p><span class="bodyBlack">
In your favorite editor, create the file below.
</span></p>

<p><span class="bodyBlack">
<table width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#c0c0c0"><i><span class="code-title">C:\my\app\org\acme\employee\Employee.java</span></i></td></tr><tr><td bgcolor="#e0e0e0"><span class="code-block"><pre>
package org.acme.employee;

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

public interface Employee extends EJBObject
{
  public void says( String message )
    throws RemoteException;
}                                                                                   
</pre></span></td></tr></table>
</span></p>
<a name="ejb-jar.xml"><h2>Create the ejb-jar.xml</h2></a>
<p><span class="bodyBlack">
<span class="command">C:\my\app&gt; mkdir META-INF</span>
</span></p>
    
<p><span class="bodyBlack">
And finally it's time for the deployment descriptor of the entity bean. 
In your favorite editor, create the file below.
</span></p> 

<p><span class="bodyBlack">
<table width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#c0c0c0"><i><span class="code-title">C:\my\app\META-INF\ejb-jar.xml</span></i></td></tr><tr><td bgcolor="#e0e0e0"><span class="code-block"><pre>
&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 1.1//EN"
                         "http://java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd"&gt;
&lt;ejb-jar&gt;
  &lt;enterprise-beans&gt;
    &lt;entity&gt;
      &lt;ejb-name&gt;EmployeeBean&lt;/ejb-name&gt;
      &lt;home&gt;org.acme.employee.EmployeeHome&lt;/home&gt;
      &lt;remote&gt;org.acme.employee.Employee&lt;/remote&gt;
      &lt;ejb-class&gt;org.acme.employee.EmployeeBean&lt;/ejb-class&gt;
      &lt;persistence-type&gt;Container&lt;/persistence-type&gt;
      &lt;prim-key-class&gt;java.lang.Integer&lt;/prim-key-class&gt;
      &lt;reentrant&gt;False&lt;/reentrant&gt;
      &lt;cmp-field&gt;
        &lt;field-name&gt;id&lt;/field-name&gt;
      &lt;/cmp-field&gt;
      &lt;cmp-field&gt;
        &lt;field-name&gt;firstname&lt;/field-name&gt;
      &lt;/cmp-field&gt;
      &lt;cmp-field&gt;
        &lt;field-name&gt;lastname&lt;/field-name&gt;
      &lt;/cmp-field&gt;
      &lt;cmp-field&gt;
        &lt;field-name&gt;email&lt;/field-name&gt;
      &lt;/cmp-field&gt;
      &lt;primkey-field&gt;id&lt;/primkey-field&gt;
      &lt;resource-ref&gt;
        &lt;res-ref-name&gt;jdbc/postgresql&lt;/res-ref-name&gt;
        &lt;res-type&gt;javax.sql.DataSource&lt;/res-type&gt;
        &lt;res-auth&gt;Container&lt;/res-auth&gt;
      &lt;/resource-ref&gt;
    &lt;/entity&gt;
  &lt;/enterprise-beans&gt;
  &lt;assembly-descriptor&gt;
    &lt;container-transaction&gt;
      &lt;method&gt;
        &lt;ejb-name&gt;EmployeeBean&lt;/ejb-name&gt;
        &lt;method-name&gt;*&lt;/method-name&gt;
      &lt;/method&gt;
      &lt;trans-attribute&gt;Supports&lt;/trans-attribute&gt;
    &lt;/container-transaction&gt;
  &lt;/assembly-descriptor&gt;
&lt;/ejb-jar&gt;

                                                                                    
</pre></span></td></tr></table>
</span></p>
<a name="compile"><h2>Compile the EJB</h2></a>
<p><span class="bodyBlack">
<span class="command">C:\my\app&gt; javac -d . -classpath %OPENEJB_HOME%\lib\ejb-1.0.jar org\acme\employee\*.java</span>
</span></p>
<a name="jar"><h2>Package the EJB</h2></a>
<p><span class="bodyBlack">
<span class="command">C:\my\app&gt; jar -cvMf employee.jar org/acme/employee/*.class META-INF</span>
</span></p>
<a name="table"><h2>Create necessary structures in the database (e.g. PostgreSQL)</h2></a>
<p><span class="bodyBlack">
The procedure outlined here describes how to prepare PostgreSQL to work 
with the Employee entity bean. It basically shows the SQL statements to 
create the structures: a table and sequence. As sequences are a few RDBMS' 
feature you will have to work it around if your chosen database doesn't 
support it or try out PostgreSQL. Will it ever be a better time to find 
out what PostgreSQL is really able to do? 
</span></p>

<p><span class="bodyBlack">
Firstly, let's start up PostgreSQL. It's assumed you followed the 
procedures on how to configure PostgreSQL to allow external users connect 
to the system, and a database is already created. Just to make sure we are 
on the same track from now on the name of the database will be reffered to 
as <b>mydb</b>, and the user and its password are <b>username</b> and 
<b>password</b>, respectively. 
</span></p>

<p><span class="bodyBlack">
Now, please connect to the database (i.e. invoke <span class="command">psql mydb 
username</span>) and run the following SQL scripts:
</span></p>

<table width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#e0e0e0"><span class="code-block"><pre>
create table employee (
    id integer primary key, 
    first_name varchar(15), 
    last_name varchar(15),
    email varchar(30)); 
create sequence employee_seq;
</pre></span></td></tr></table>
<a name="datasource"><h2>Configure the data source</h2></a>
<p><span class="bodyBlack">
Having done everything up to that point has showed you really nothing 
about OpenEJB itself. As you might have guessed, we're about to change it 
and see how different files influence the way OpenEJB works. 
</span></p>

<p><span class="bodyBlack">
When OpenEJB starts up, the default configuration file is 
%OPENEJB_HOME%\conf\openejb.conf. We will, however, be using another one - 
our own configuration file. We're doing it because: 

<table cellspacing="2" cellpadding="2" border="0"><tr><td height="5" colspan="2"></td></tr><span class="bodyGrey">
    <tr><td width="10" valign="top" align="left"><img src="images/grayDot.gif"></td><td valign="top" align="left"><span class="bodyBlack">it shall get you familiar with the configuration file's elements</span></td></tr>
    <tr><td width="10" valign="top" align="left"><img src="images/grayDot.gif"></td><td valign="top" align="left"><span class="bodyBlack">it shall avoid bothering you with log messages that do not pertain to our example</span></td></tr>
    <tr><td width="10" valign="top" align="left"><img src="images/grayDot.gif"></td><td valign="top" align="left"><span class="bodyBlack">it shall get you a feeling of how easy (or not) is to manage OpenEJB</span></td></tr>
</span></table>
</span></p>

<p><span class="bodyBlack">
Thus, here goes the configuration file - openejb.xml - which will satisfy 
the aforementioned requirements. 
</span></p>
            
<p><span class="bodyBlack">
Create the file in the conf directory.
</span></p>

<p><span class="bodyBlack">
<span class="command">C:\my\app&gt; mkdir conf</span>
</span></p>

<p><span class="bodyBlack">
In your favorite editor, create the file below.
</span></p>

<table width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#c0c0c0"><i><span class="code-title">C:\my\app\conf\openejb.xml</span></i></td></tr><tr><td bgcolor="#e0e0e0"><span class="code-block"><pre>
&lt;?xml version="1.0"?&gt;

&lt;openejb&gt;
  &lt;Container id="Default CMP Container" ctype="CMP_ENTITY"&gt;
    Global_TX_Database  c:/my/app/conf/postgresql.cmp_global_database.xml
    Local_TX_Database   c:/my/app/conf/postgresql.cmp_local_database.xml
  &lt;/Container&gt;
  &lt;Deployments jar="c:/my/app/employee.jar"/&gt;
  &lt;Connector id="Default JDBC Database"&gt;
    JdbcDriver org.postgresql.Driver
    JdbcUrl jdbc:postgresql://localhost/mydb
    UserName username
    Password password
  &lt;/Connector&gt;
  &lt;SecurityService id="Default Security Service"/&gt;
  &lt;TransactionService id="Default Transaction Manager"/&gt;
&lt;/openejb&gt;
                                                                                    </pre></span></td></tr></table>

<p><span class="bodyBlack">
Before we go on a few words about the structure of the file.
<table cellspacing="2" cellpadding="2" border="0"><tr><td height="5" colspan="2"></td></tr><span class="bodyGrey">
    <tr><td width="10" valign="top" align="left"><img src="images/grayDot.gif"></td><td valign="top" align="left"><span class="bodyBlack"><b>Container</b> - there are 4 different container types:
        <table cellspacing="2" cellpadding="2" border="0"><tr><td height="5" colspan="2"></td></tr><span class="bodyGrey">
        <tr><td width="10" valign="top" align="left"><img src="images/grayDot.gif"></td><td valign="top" align="left"><span class="bodyBlack">CMP_ENTITY</span></td></tr>
        <tr><td width="10" valign="top" align="left"><img src="images/grayDot.gif"></td><td valign="top" align="left"><span class="bodyBlack">BMP_ENTITY</span></td></tr>
        <tr><td width="10" valign="top" align="left"><img src="images/grayDot.gif"></td><td valign="top" align="left"><span class="bodyBlack">STATEFUL</span></td></tr>
        <tr><td width="10" valign="top" align="left"><img src="images/grayDot.gif"></td><td valign="top" align="left"><span class="bodyBlack">STATELESS</span></td></tr>
        </span></table>
        <p><span class="bodyBlack">
        The type of a container determines what capabilities it provides. The 
        Employee entity bean is a CMP entity bean so the chosen container is of 
        the CMP_ENTITY type. 
        </span></p>
        <p><span class="bodyBlack">
        Since entity beans represent (in most cases) records in a table there must 
        be a way to point an EJB container to it. OpenEJB does it via 
        <b>Global_TX_Database</b> and <b>Local_TX_Database</b> parameters. The 
        values of the parameters are configuration files which are specific to the 
        underlaying platform OpenEJB depends on - Castor. Their structure is 
        hopefully self-explanatory thus the document will not explain it in more 
        details.
        </span></p>
        <p><span class="bodyBlack">
        These files are shown right after the bullet points below.
        </span></p>
        <br>
    </span></td></tr>
    <tr><td width="10" valign="top" align="left"><img src="images/grayDot.gif"></td><td valign="top" align="left"><span class="bodyBlack"><b>Deployments</b> - the element specifies the locations of beans 
        to be deployed onto OpenEJB. The element may have only one of the two 
        attributes (they are mutually exclusive): 
        <br>
        <table cellspacing="2" cellpadding="2" border="0"><tr><td height="5" colspan="2"></td></tr><span class="bodyGrey">
        <tr><td width="10" valign="top" align="left"><img src="images/grayDot.gif"></td><td valign="top" align="left"><span class="bodyBlack"><b>jar</b> - points to one particular bean</span></td></tr>
        <tr><td width="10" valign="top" align="left"><img src="images/grayDot.gif"></td><td valign="top" align="left"><span class="bodyBlack"><b>dir</b> - points to a directory that contains beans</span></td></tr>
        </span></table>
        <p><span class="bodyBlack">
        The locations may be relative or absolute paths, where the former is 
        constructed to be an absolute path with %OPENEJB_HOME% prepended. 
        </span></p>
        <br>
    </span></td></tr>
    <tr><td width="10" valign="top" align="left"><img src="images/grayDot.gif"></td><td valign="top" align="left"><span class="bodyBlack"><b>Connector</b> - the element allows to specify what parameters 
        to use while connecting to the default JDBC database. The contents of the 
        element consists of lines which begin with the name of the parameters you 
        could have seen before - these constitute the required JDBC parameters to 
        connect to the database, i.e. PostgreSQL. 
        <br>
        <p><span class="bodyBlack">
        The <b>id</b> attribute must be "Default JDBC Database" unless you 
        know what changes are required upon changing the value. 
        </span></p>
        <br>
    </span></td></tr>
    <tr><td width="10" valign="top" align="left"><img src="images/grayDot.gif"></td><td valign="top" align="left"><span class="bodyBlack"><b>SecurityService</b> and <b>TransactionService</b> - these 
        elements are included in the file because they are required and without 
        them OpenEJB refuses to run. Nothing to configure so we skip them 
        silently.  
 </span></td></tr> 
</span></table>
<table bgcolor="#7270c2" width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#7270c2"><span class="note-caption">&nbsp;NOTE</span></td></tr><tr><td bgcolor="#7270c2"><table bgcolor="#7270c2" width="100%" cellspacing="2" cellpadding="7" border="0"><tr><td bgcolor="#FFFFFF"><span class="note">
In future versions of OpenEJB, you won't be required to include 
the SecurityService or TransactionService lines in your config 
files unless there is some part of them that you wish to configure.
</span></td></tr></table></td></tr></table>
</span></p>
            
<p><span class="bodyBlack">
Create the following files in the conf directory using your favorite 
editor. 
</span></p>

<table width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#c0c0c0"><i><span class="code-title">C:\my\app\conf\postgresql.cmp_global_database.xml</span></i></td></tr><tr><td bgcolor="#e0e0e0"><span class="code-block"><pre>
&lt;?xml version="1.0"?&gt;

&lt;database name="Global_TX_Database" engine="postgresql"&gt;
  &lt;jndi name="java:comp/env/jdbc/postgresql" /&gt;
  &lt;mapping href="c:/my/app//conf/postgresql.cmp_or_mapping.xml" /&gt;
&lt;/database&gt;
                                                                                    </pre></span></td></tr></table>

<br>
<table width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#c0c0c0"><i><span class="code-title">C:\my\app\conf\postgresql.cmp_or_mapping.xml</span></i></td></tr><tr><td bgcolor="#e0e0e0"><span class="code-block"><pre>
&lt;?xml version="1.0"?&gt;

&lt;mapping&gt;
  &lt;class name="org.acme.employee.EmployeeBean" identity="id" key-generator="SEQUENCE"&gt;
    &lt;map-to table="employee"/&gt;
    &lt;field name="id" type="integer" direct="true"&gt;
      &lt;sql name="id" type="integer"/&gt;
    &lt;/field&gt;
    &lt;field name="firstname" type="string" direct="true"&gt;
      &lt;sql name="first_name" type="varchar" dirty="check"/&gt;
    &lt;/field&gt;
    &lt;field name="lastname" type="string" direct="true"&gt;
      &lt;sql name="last_name" type="varchar" dirty="check"/&gt;
    &lt;/field&gt;
    &lt;field name="email" type="string" direct="true"&gt;
      &lt;sql name="email" type="varchar" dirty="check"/&gt;
    &lt;/field&gt;
  &lt;/class&gt;
&lt;/mapping&gt;
</pre></span></td></tr></table>
<br>
<table width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#c0c0c0"><i><span class="code-title">C:\my\app\conf\postgresql.cmp_local_database.xml</span></i></td></tr><tr><td bgcolor="#e0e0e0"><span class="code-block"><pre>
&lt;?xml version="1.0"?&gt;

&lt;database name="Local_TX_Database" engine="postgresql"&gt;
  &lt;driver class-name="org.postgresql.Driver" url="jdbc:postgresql://localhost/mydb"&gt;
    &lt;param name="user" value="username"/&gt;
    &lt;param name="password" value="password"/&gt;
  &lt;/driver&gt;
  &lt;mapping href="C:\my\app\conf\postgresql.cmp_or_mapping.xml"/&gt;
&lt;/database&gt;
                                                                                    </pre></span></td></tr></table>

<p><span class="bodyBlack">
<table bgcolor="#7270c2" width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#7270c2"><span class="note-caption">&nbsp;NOTE</span></td></tr><tr><td bgcolor="#7270c2"><table bgcolor="#7270c2" width="100%" cellspacing="2" cellpadding="7" border="0"><tr><td bgcolor="#FFFFFF"><span class="note">
    As connections to PostgreSQL are being performed through JDBC data source 
    PostgreSQL JDBC2 driver's classes have to be available to OpenEJB. Thus, 
    you need to download from <a href="http://jdbc.postgresql.org">PostgreSQL 
    JDBC2 driver home page</a> and save it in %OPENEJB_HOME%\lib directory as 
    pgjdbc2.jar. The driver will be loaded by OpenEJB at startup.
</span></td></tr></table></td></tr></table>
</span></p>
<a name="deploy"><h2>Deploy the EJB jar</h2></a>
<p><span class="bodyBlack">
Use the OpenEJB <a href="deploy.html">Deploy Tool</a> to deploy your jar.
</span></p>

<p><span class="bodyBlack">
<span class="command">C:\my\app&gt; cd %OPENEJB_HOME%</span>
<br>
<span class="command">C:\openejb&gt; openejb deploy -a -conf c:\my\app\conf\openejb.xml c:\my\app\employee.jar</span>
</span></p>

<p><span class="bodyBlack">
The tool will ask for the resource to link the bean's reference to. You 
should type in <b>1</b> as it points to the resource declared in our 
configuration file which is the "Default JDBC Database", i.e. PostgreSQL. 
</span></p>

<p><span class="bodyBlack">
<table bgcolor="#7270c2" width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#7270c2"><span class="note-caption">&nbsp;NOTE</span></td></tr><tr><td bgcolor="#7270c2"><table bgcolor="#7270c2" width="100%" cellspacing="2" cellpadding="7" border="0"><tr><td bgcolor="#FFFFFF"><span class="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. 
</span></td></tr></table></td></tr></table>
</span></p>
<a name="client"><h2>A basic client application</h2></a>
<p><span class="bodyBlack">
Create the basic client application to access your Employee entity bean. 
The client looks up the entity EJBHome object, creates a user, then finds 
it with <i>findByPrimaryKey</i> and finally compare the references to each 
other in order to find out whether or not they points to the same 
EJBObject managed by OpenEJB. The following lines show invocation of the 
bussines method - <i>says</i> - and at the end removes the bean's 
representation from the table. 
</span></p>
            
<p><span class="bodyBlack">
Please refer to the <a href="hello-world.html">basic EJB example</a> to 
choose proper InitialContext environment variables. 
</span></p>
            
<p><span class="bodyBlack"><span class="command">C:\openejb&gt; cd c:\my\app</span></span></p>
            
<p><span class="bodyBlack">
Create the file in your favorite editor.
</span></p>
            
<p><span class="bodyBlack">
<table width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#c0c0c0"><i><span class="code-title">C:\my\app\org\acme\employee\EmployeeClient.java</span></i></td></tr><tr><td bgcolor="#e0e0e0"><span class="code-block"><pre>
package org.acme.employee;

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

public class EmployeeClient
{
   public static void main( String[] args )
           throws Exception
   {
      Properties env = new Properties();
      <comment>//The JNDI properties you set depend</comment>
      <comment>//on which server you are using.</comment>
      String jndiProvider = "org.openejb.client.RemoteInitialContextFactory";
      env.put( "java.naming.factory.initial", jndiProvider );
      env.put( "java.naming.provider.url", "localhost:4201" );
      env.put( "java.naming.security.principal", "fakeuser" );
      env.put( "java.naming.security.credentials", "fakepass" );
      Context ctx = new InitialContext( env );

      Object obj = ctx.lookup( "EmployeeBean" );
      obj = PortableRemoteObject.narrow( obj, EmployeeHome.class );
      EmployeeHome home = ( EmployeeHome ) obj;

      Employee empl_create = home.create( "Jacek", "Laskowski", 
            "OpenEJB-" + System.currentTimeMillis() + "@SF.net" );
      
      Integer primaryKey = ( Integer ) empl_create.getPrimaryKey();
      Employee empl_find = home.findByPrimaryKey( primaryKey );
      
      System.out.println( "Are the \"create\" and \"find\" users identical ? "+ 
            empl_create.isIdentical( empl_find ) );
      
      empl_find.says( "Hello OpenEJB World!" );
      empl_find.remove();
   }
}                                                                                   
</pre></span></td></tr></table>
</span></p>
<a name="compile.app"><h2>Compile the application</h2></a>
<p><span class="bodyBlack">
<span class="command">C:\my\app&gt; javac -d . -classpath .;%OPENEJB_HOME%/lib/ejb-1.0.jar;%OPENEJB_HOME%/lib/jndi_1.2.1.jar org\acme\employee\EmployeeClient.java</span>
</span></p>
<a name="run.it"><h2>Run it!</h2></a>
<p><span class="bodyBlack">
Create the file in your favorite editor.
</span></p>
<table width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#c0c0c0"><i><span class="code-title">C:\my\app\RunIt.bat</span></i></td></tr><tr><td bgcolor="#e0e0e0"><span class="code-block"><pre>
@echo off

set OPENEJB_HOME=C:\openejb
set PATH=%PATH%;%OPENEJB_HOME%\bin

set OLD_CLASSPATH=%CLASSPATH%

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 
set CP=c:\my\app\employee.jar;%CP%

set CLASSPATH=%JAVA_HOME%\lib\tools.jar;%CP%

%JAVA_HOME%\bin\java -Dopenejb.home=%OPENEJB_HOME% org.acme.employee.EmployeeClient

set CLASSPATH=%OLD_CLASSPATH%</pre></span></td></tr></table>

<p><span class="bodyBlack">
Open the command line window and start up OpenEJB with the following 
command: 
</span></p>

<p><span class="bodyBlack">
<span class="command">C:\&gt; cd %OPENEJB_HOME%</span>
<br>
<span class="command">C:\openejb&gt; start openejb start -conf c:\my\app\conf\openejb.xml</span>             
</span></p>

<p><span class="bodyBlack">
Now run the script!
</span></p>
            
<p><span class="bodyBlack">
<span class="command">C:\&gt; cd \my\app</span>
<br>
<span class="command">C:\my\app&gt; RunIt</span>
</span></p>

<p><span class="bodyBlack">
You will see the following sample output on the out-of-process client's console:
</span></p>

<table width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#e0e0e0"><span class="code-block"><pre>
C:\my\app&gt;RunIt
Are the "create" and "find" users identical ? true</pre></span></td></tr></table>

<p><span class="bodyBlack">
And the following on the OpenEJB server's console:
</span></p>

<table width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#e0e0e0"><span class="code-block"><pre>
OpenEJB Remote Server 0.8.1    build: 20020731-0133
http://openejb.sf.net
----------------STARTUP----------------
[init] OpenEJB Container System
[init] OpenEJB Remote Server
  ** Starting Services **
  NAME             IP              PORT
  ejb server       127.0.0.1       4201
  admin console    127.0.0.1       4200
-----------------INFO------------------
To log into the admin console, telnet to:
 telnet 127.0.0.1 4200
---------------------------------------
Ready!
[FirstName LastName(1) OpenEJB-1029465232802@SF.net] Hello OpenEJB World !</pre></span></td></tr></table>
<a name="problems"><h2>What if it didn't work</h2></a>
<p><span class="bodyBlack">
If you ran into any problems, first check your openejb.log file at 
%OPENEJB_HOME%\openejb.log. Look for any lines that begin with 
<span class="bodyTerm">"WARN"</span>, <span class="bodyTerm">"ERROR"</span>, or <span class="bodyTerm">"FATAL"</span>. 
</span></p>
            
<p><span class="bodyBlack">
There is a list of the most common problems with possible solutions: 
<table cellspacing="2" cellpadding="2" border="0"><tr><td height="5" colspan="2"></td></tr><span class="bodyGrey">
<tr><td width="10" valign="top" align="left"><img src="images/grayDot.gif"></td><td valign="top" align="left"><span class="bodyBlack">
<p><span class="bodyBlack"><b>Problem:</b></span></p>
<table width="440" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#e0e0e0"><span class="code-block"><pre>
OpenEJB Remote Server 0.8.1    build: 20020731-0133
http://openejb.sf.net
----------------STARTUP----------------
[init] OpenEJB Container System
java.lang.ClassNotFoundException: org.postgresql.Driver
        at java.net.URLClassLoader$1.run(URLClassLoader.java:195)
        at java.security.AccessController.doPrivileged(Native Method)
        ...
</pre></span></td></tr></table>

<p><span class="bodyBlack"><b>Solution:</b> Add the PostgreSQL JDBC2 driver to OpenEJB's 
CLASSPATH. See the <a href="#datasource">Configure the data source</a> 
section for more details.
</span></p> 
</span></td></tr>

</span></table>
</span></p>

<p><span class="bodyBlack">
If nothing has helped, email it to the OpenEJB <a href="lists.html#openejb-user"> user mailing list</a> and let people know 
you are using the basic CMP entity bean example. 
</span></p>

</td><td align="left" valign="top" height="5" width="120">
        
        
        &nbsp;        
        </td></tr><tr height="5"><td align="left" valign="top" bgcolor="#7270c2" height="5" width="20">&nbsp;</td><td valign="top" bgcolor="#7270c2" height="5" width="95">&nbsp;</td><td align="left" valign="top" bgcolor="#a9a5de" height="5" width="7">&nbsp;</td><td align="left" valign="top" height="5" width="40">&nbsp;</td><td align="left" valign="top" height="5" width="120">&nbsp;</td></tr><tr><td align="left" valign="top" bgcolor="#7270c2" height="5" width="20">&nbsp;</td><td align="left" valign="top" bgcolor="#7270c2" width="95">&nbsp;</td><td align="left" valign="top" bgcolor="#a9a5de" width="7"><img border="0" height="25" width="1" src="images/dotTrans.gif"></td><td align="left" valign="top" width="40"><img border="0" height="25" width="1" src="images/dotTrans.gif"></td><td align="left" valign="top" width="120">&nbsp;</td></tr><tr height="5"><td align="left" valign="bottom" bgcolor="#7270c2" height="100%" rowspan="2" width="20"><img border="0" height="125" width="20" src="images/stripes1.gif"></td><td align="left" valign="bottom" bgcolor="#7270c2" height="100%" rowspan="2" width="95"><img border="0" height="125" width="105" src="images/stripe105.gif"></td><td align="left" valign="top" bgcolor="#a9a5de" height="100%" rowspan="2" width="7">&nbsp;</td><td align="left" valign="top" height="100%" width="40">&nbsp;</td><td align="left" valign="top" height="100%" width="120">&nbsp;</td></tr><tr height="5"><td align="left" valign="top" height="25" width="40">&nbsp;</td><td align="left" valign="bottom" height="25" width="430"><br><br><img height="3" width="430" border="0" src="images/line_light.gif"><br><p></p><span class="bodyGrey"><small><notice>
    OpenEJB is a trademark of the OpenEJB Group.
    Java, EJB, JDBC, JNDI, JTA, Sun, Sun Microsystems are trademarks or registered
    trademarks of Sun Microsystems, Inc. in the United States and in other
    countries. XML, XML Schema, XSLT and related standards are trademarks or registered
    trademarks of MIT, INRIA, Keio or others, and a product of the World Wide Web
    Consortium. All other product names mentioned herein are trademarks of their respective
    owners. 
  </notice><br>&nbsp;<br></small></span><p></p>
          &nbsp;
        </td><td align="left" valign="top" height="25" width="120">&nbsp;</td></tr></table></body></html>