<?xml version="1.0"?>

<document>

  <properties>
    <title>Melati - Java SQL Website Development Engine</title>
    <author email="timp">Tim Pizey</author>
    <keywords>
      Persistence, Java, SQL, Database, Templates, Object Relational Mapping,
      ORM, Objects, Object Oriented, J2EE replacement
    </keywords>
  </properties>

  <body>


<!--
<p align="center">
 <font size="-1"><i>
This page last updated: $Date: 2007/07/02 07:45:06 $ $Author: timp $
 </i></font>
</p>
-->
  
<!-- menu -->

<section name=" Working with Plain Old Java Objects (POJOs) ">
<p>
The <it>'flexibility'</it> afforded by working with 
Plain Old Java Objects is bought at a price, 
namely the use of introspection. 
</p>
<p>
The use of a system such as POEM has the disadvantage that, 
due to Java's lack of multiple inheritance, 
you have used your one opportunity to inherit.
</p>
<p>
If POJOs can be avoided, and you are happy to use <tt>Persistent</tt>s as 
your base class, then that is the best way to use POEM. 
However POEM enables you to persist a POJO object graph to a database, 
which can be useful for reporting, migrating to POEM or similar 
POJO to database transformations. It also enables you to re-populate 
an object graph from a database. 
</p>
<p>
What POEM does not attempt to do is keep track of changes to the POJO such that 
the system can tell which is most current the POJO or the store.
It is not intended as your main persistance mechanism, as it is 
not designed with bidirectionality in mind. You can populate a POJO from a 
database record and visa versa but there is no attempt at transaction 
handling or versioning, these issues are handled in POEM itself.
To use POEM as your persistence engine, 
with transactions and access control then your objects 
should inherit from <tt>Persistent</tt>; 
if that is not an option then 
<a href="http://www.hibernate.org/">Hibernate</a> is probably what you need.
</p>
<subsection name="Comparison with Hibernate">
<table>
<tr><th></th><th>Hibernate</th><th>POEM</th></tr>
<tr><td>Requires a noArg constructor</td>                         <td>Yes</td><td>Yes</td></tr>
<tr><td>Setters and getters must be public</td>                   <td>No</td><td>Yes</td></tr> 
<tr><td>Persist public fields</td>                                <td>Not by default</td><td>No</td></tr>
<tr><td>Use existing id fields</td>                               <td>Yes</td><td>No</td></tr> 
<tr><td>Fields must have both a setter and a getter</td>          <td>No</td><td>Yes</td></tr>
</table>
<p>
POEM enforces Hibernate best practice, 
except we do not believe that POEM's <tt>troid</tt> field should rely upon 
any existing <tt>id</tt> field. 
If your POJO has a field called <tt>id</tt> and is not an instance of <tt>Persistent</tt> 
then the <tt>troid</tt> column name will be <tt>poemId</tt> and 
your <tt>id</tt> field will be used as a normal field. 
The underlying database will plan queries effectively.
</p>
</subsection>
<subsection name="Persisting POJOs">
<p>
To persist an instance of a class:
</p>
<pre>
    Persistent persisted = PersistentFactory.fromInstance(getDb(), pojo);
</pre>
</subsection>
<subsection name="Resurrecting POJOs">
<p>
To populate an instance of a class:
</p>
<pre>
    AClass pojo  = (AClass)PersistentFactory.from(getDb().getAClassTable().getObject(id), AClass.class);
</pre>
</subsection>
</section>
</body>
</document>












