Google Git
Sign in
apache / openejb / ff4c3995cf32f0a3fc5fe4b624f529023f76b530 / . / html / old-site / html / cmp_entity_postgresql.html
blob: 9b702d15ff1163872f72531f32032e99ae27fd1d [file] [log] [blame]
<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>