<html><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Castor JDO - Advanced features</title><link href="default.css" rel="stylesheet"></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" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#7270c2" align="left" valign="top" width="10"><img border="0" height="1" width="1" src="images/dotTrans.gif"></td><td bgcolor="#7270c2" align="left" valign="top" width="150"><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="70"><img border="0" height="6" width="70" src="images/dotTrans.gif"></td><td align="left" valign="top" width="100%"><img border="0" height="6" width="100%" src="images/top_2.gif"></td></tr><tr><td align="left" valign="top" bgcolor="#7270c2" width="10"><img height="1" width="1" border="0" src="images/dotTrans.gif"></td><td align="left" valign="top" bgcolor="#7270c2" width="150"><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="70"><img border="0" height="1" width="1" src="images/dotTrans.gif"></td><td align="left" valign="middle" width="100%"><a href="license.html"><span class="menuTopOff">License</span></a> <a href="http://www.codehaus.org"><span class="menuTopOff">Codehaus</span></a> <a href="http://openejb.org"><span class="menuTopOff">OpenEJB</span></a> <a href="http://openjms.sf.net"><span class="menuTopOff">OpenJMS</span></a> <a href="http://openorb.sf.net"><span class="menuTopOn">OpenORB</span></a> <a href="http://tyrex.sf.net"><span class="menuTopOff">Tyrex</span></a> <br><img border="0" height="2" width="1" src="images/dotTrans.gif"></td></tr><tr><td align="left" valign="top" bgcolor="#7270c2" width="10"><img border="0" height="3" width="10" src="images/dotTrans.gif"></td><td align="right" valign="top" bgcolor="#7270c2" width="150"><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="70"><img border="0" height="3" width="70" src="images/line_light.gif"></td><td align="left" valign="top" width="100%"><img border="0" height="3" width="100%" src="images/line_light.gif"></td></tr><tr><td align="left" valign="top" bgcolor="#7270c2"><img border="0" height="10" width="10" src="images/dotTrans.gif"></td><td align="left" valign="top" bgcolor="#7270c2" width="150"><img border="0" height="2" width="1" src="images/dotTrans.gif"><br><table cellspacing="0" cellpadding="10" border="0"><tr><td><script src="http://www.ohloh.net/p/3635/widgets/project_users_logo.js" type="text/javascript"></script></td></tr></table><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">Old releases</span></td></tr><tr><td align="left" valign="top">
<a href="releases-old.html"><span class="subMenuOff">General</span></a></td></tr><tr><td align="left" valign="top">
<a href="http://www.castor.org/1.3/index.html"><span class="subMenuOff">Release 1.3</span></a></td></tr><tr><td align="left" valign="top">
<a href="http://www.castor.org/1.3rc1/index.html"><span class="subMenuOff">Release 1.3rc1</span></a></td></tr><tr><td align="left" valign="top">
<a href="http://www.castor.org/1.2/index.html"><span class="subMenuOff">Release 1.2</span></a></td></tr></table><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">Home</span></a></td></tr><tr><td align="left" valign="top">
<a href="about.html"><span class="subMenuOff">About</span></a></td></tr><tr><td align="left" valign="top">
<a href="features.html"><span class="subMenuOff">Features</span></a></td></tr><tr><td align="left" valign="top">
<a href="download.html"><span class="subMenuOff">Download</span></a></td></tr><tr><td align="left" valign="top">
<a href="dependencies.html"><span class="subMenuOff">Dependencies</span></a></td></tr><tr><td align="left" valign="top">
<a href="reference-guide.html"><span class="subMenuOffHighlighted">Reference guide</span></a></td></tr><tr><td align="left" valign="top">
<a href="presentations.html"><span class="subMenuOff">Publications</span></a></td></tr><tr><td align="left" valign="top">
<a href="javadoc/overview-summary.html"><span class="subMenuOff">JavaDoc</span></a></td></tr><tr><td align="left" valign="top">
<a href="maven-integration.html"><span class="subMenuOff">Maven 2 support</span></a></td></tr><tr><td align="left" valign="top">
<a href="maven-archetypes.html"><span class="subMenuOff">Maven 2 archetypes</span></a></td></tr><tr><td align="left" valign="top">
<a href="schema.html"><span class="subMenuOff">DTD & Schemas</span></a></td></tr><tr><td align="left" valign="top">
<a href="changes.html"><span class="subMenuOff">Recent HTML changes</span></a></td></tr><tr><td align="left" valign="top">
<a href="news.html"><span class="subMenuOff">News Archive</span></a></td></tr><tr><td align="left" valign="top">
<a href="http://castor.codehaus.org/rss/castor-announce.xml"><span class="subMenuOff">RSS news feed</span></a></td></tr><tr><td align="left" valign="top">
<a href="http://docs.codehaus.org/display/CASTOR/"><span class="subMenuOffHighlighted">Project Wiki</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">Development/Support</span></td></tr><tr><td align="left" valign="top">
<a href="lists.html"><span class="subMenuOff">Mailing Lists</span></a></td></tr><tr><td align="left" valign="top">
<a href="scm.html"><span class="subMenuOff">SVN/JIRA</span></a></td></tr><tr><td align="left" valign="top">
<a href="contributing.html"><span class="subMenuOff">Contributing</span></a></td></tr><tr><td align="left" valign="top">
<a href="support.html"><span class="subMenuOff">Support</span></a></td></tr><tr><td align="left" valign="top">
<a href="http://bamboo.ci.codehaus.org/browse/CASTOR"><span class="subMenuOff">Continuous builds</span></a></td></tr><tr><td align="left" valign="top">
<a href="professional-services.html"><span class="subMenuOffHighlighted">Prof. services</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">Related projects</span></td></tr><tr><td align="left" valign="top">
<a href="spring-orm-integration.html"><span class="subMenuOff">Spring ORM support</span></a></td></tr><tr><td align="left" valign="top">
<a href="spring-xml-intro.html"><span class="subMenuOff">Spring XML factories</span></a></td></tr><tr><td align="left" valign="top">
<a href="ws-integration.html"><span class="subMenuOff">WS frameworks</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">XML</span></td></tr><tr><td align="left" valign="top">
<a href="xml-link.html"><span class="subMenuOff">XML</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">XML Code Generator</span></td></tr><tr><td align="left" valign="top">
<a href="srcgen-link.html"><span class="subMenuOff">XML Code Generator</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">JDO</span></td></tr><tr><td align="left" valign="top">
<a href="jdo-introduction.html"><span class="subMenuOff">Introduction</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-starter-tutorial.html"><span class="subMenuOff">First steps</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo.html"><span class="subMenuOff">Using JDO</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-database-conf.html"><span class="subMenuOff">JDO Config</span></a></td></tr><tr><td align="left" valign="top">
<a href="types.html"><span class="subMenuOff">Types</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-mapping.html"><span class="subMenuOff">JDO Mapping</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-faq.html"><span class="subMenuOff">JDO FAQ</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-examples.html"><span class="subMenuOff">JDO Examples</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-howto.html"><span class="subMenuOffHighlighted">JDO HOW-TOs</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-tips-tricks.html"><span class="subMenuOffHighlighted">Tips & Tricks</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-other-features.html"><span class="subMenuOff">Other Features</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-self-executable-examples.html"><span class="subMenuOff">JDO sample JAR</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">Tools</span></td></tr><tr><td align="left" valign="top">
<a href="schemaGen-anttask.html"><span class="subMenuOff">Schema generator</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">Advanced JDO</span></td></tr><tr><td align="left" valign="top">
<a href="jdo-caching-detail.html"><span class="subMenuOff">Caching</span></a></td></tr><tr><td align="left" valign="top">
<a href="oql.html"><span class="subMenuOff">OQL</span></a></td></tr><tr><td align="left" valign="top">
<a href="locking.html"><span class="subMenuOff">Trans. & Locks</span></a></td></tr><tr><td align="left" valign="top">
<a href="design-persist.html"><span class="subMenuOff">Design</span></a></td></tr><tr><td align="left" valign="top">
<a href="key-generator.html"><span class="subMenuOff">KeyGen</span></a></td></tr><tr><td align="left" valign="top">
<a href="long-transact.html"><span class="subMenuOff">Long Trans.</span></a></td></tr><tr><td align="left" valign="top">
<a href="nested-attr.html"><span class="subMenuOff">Nested Attrs.</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-pooling.html"><span class="subMenuOff">Pooling Examples</span></a></td></tr><tr><td align="left" valign="top">
<a href="postgresql-blobs.html"><span class="subMenuOff">LOBs</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-best-practice.html"><span class="subMenuOff">Best practice</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">DDL Generator</span></td></tr><tr><td align="left" valign="top">
<a href="ddlgen.html"><span class="subMenuOff">Using DDL Generator</span></a></td></tr><tr><td align="left" valign="top">
<a href="ddlgen-properties.html"><span class="subMenuOff">Properties</span></a></td></tr><tr><td align="left" valign="top">
<a href="ddlgen-anttask.html"><span class="subMenuOff">Ant task</span></a></td></tr><tr><td align="left" valign="top">
<a href="ddlgen-mapping.html"><span class="subMenuOff">Type Mapping</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">More</span></td></tr><tr><td align="left" valign="top">
<a href="examples.html"><span class="subMenuOff">The Examples</span></a></td></tr><tr><td align="left" valign="top">
<a href="extras.html"><span class="subMenuOff">3rd Party Tools</span></a></td></tr><tr><td align="left" valign="top">
<a href="test-framework.html"><span class="subMenuOff">JDO Tests</span></a></td></tr><tr><td align="left" valign="top">
<a href="ctf.html"><span class="subMenuOff">XML Tests</span></a></td></tr><tr><td align="left" valign="top">
<a href="conf-lib.html"><span class="subMenuOff">Configuration</span></a></td></tr><tr><td align="left" valign="top">
<a href=""><span class="subMenuOff"></span></a></td></tr><tr><td align="left" valign="top">
<a href="http://www.java.net/"><span class="subMenuOff"><img border="0" src="images/javanet_button_90.gif"></span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">About</span></td></tr><tr><td align="left" valign="top">
<a href="license.html"><span class="subMenuOff">License</span></a></td></tr><tr><td align="left" valign="top">
<a href="user-experience.html"><span class="subMenuOffHighlighted">User stories</span></a></td></tr><tr><td align="left" valign="top">
<a href="contributors.html"><span class="subMenuOff">Contributors</span></a></td></tr><tr><td align="left" valign="top">
<a href="marketplace.html"><span class="subMenuOff">Marketplace</span></a></td></tr><tr><td align="left" valign="top">
<a href="status.html"><span class="subMenuOff">Status, Todo</span></a></td></tr><tr><td align="left" valign="top">
<a href="release-notes.html"><span class="subMenuOff">Changelog</span></a></td></tr><tr><td align="left" valign="top">
<a href="library.html"><span class="subMenuOff">Library</span></a></td></tr><tr><td align="left" valign="top">
<a href="contacts.html"><span class="subMenuOff">Contact</span></a></td></tr><tr><td align="left" valign="top">
<a href="origins.html"><span class="subMenuOff">Project Name</span></a></td></tr></table><br></td><td align="left" valign="top" bgcolor="#a9a5de" width="7"> </td><td align="left" valign="top" width="70"> </td><td valign="top" width="100%" rowspan="4"><table width="100%" cellspacing="0" cellpadding="0" border="0" rows="2" cols="2"><tr><td align="left" valign="top"><br><img width="115" vspace="0" src="images/castor.gif" hspace="0" height="34" border="0"><br><img src="images/dotTrans.gif" hspace="0" height="10" border="0"></td><td align="right" valign="top" height="5" width="120"></td></tr></table><p></p><p></p><br><h2 align="center">Castor JDO - Advanced features</h2><p align="center">
Documentation Author(s):<br>Werner Guttmann<br></p><p><span class="bodyGrey">Reference: <a href="javadoc/org/exolab/castor/jdo/package-summary.html"><api package="org.exolab.castor.jdo">The Java Data Objects API</api></a></span></p><HR size="1"><span class="bodyGrey"><b><a href="#Introduction">Introduction</a></b><br></span><span class="bodyGrey"><b><a href="#Caching">Caching</a></b><br></span><span class="bodyGrey"><b><a href="#Dependent-and-related-relationships">Dependent and related relationships</a></b><br></span><span class="bodyGrey"><b><a href="#Different-cardinalities-of-relationship">Different cardinalities of relationship</a></b><br></span><span class="bodyGrey"><b><a href="#Lazy-Loading">Lazy Loading</a></b><br></span><span class="bodyGrey"><a href="#1:1-relations"> 1:1 relations</a><br></span><span class="bodyGrey"><a href="#1:M-and-M:N-relations"> 1:M and M:N relations</a><br></span><span class="bodyGrey"><b><a href="#Multiple-columns-primary-keys">Multiple columns primary keys</a></b><br></span><span class="bodyGrey"><b><a href="#Callback-interface-for-persistent-operations">Callback interface for persistent operations</a></b><br></span><HR size="1"><br><a name="Introduction"><h2>Introduction</h2></a>
<p><span class="bodyGrey">As explained at <a href="jdo-introduction.html">the introduction to Castor JDO</a>,
Castor has support for many advanced features such as caching, depend relations,
inheritance, polymorphism, etc. The below sections detail these features, as their
understanding is required to use Castor JDO in a performant and secure way.</span></p>
<a name="Caching"><h2>Caching</h2></a>
<p><span class="bodyGrey">All information related to caching and related concepts supported
by Castor has been consolidated into one place, and is available
<a href="jdo-caching-detail.html">here</a>.</span></p>
<a name="Dependent-and-related-relationships"><h2>Dependent and related relationships</h2></a>
<p><span class="bodyGrey">Castor distinguishes the relationship of two objects as dependent or related, and
maintains the life cycle independently for the two types of relationships. Starting
from Castor 0.9, the developer can explicitly define a dependent relationship in
the mapping file.</span></p>
<p><span class="bodyGrey">When using independent relations, related objects’ life cycle is independent of each
other, meaning that they have to be created, removed and updated (for long
transaction) independently.</span></p>
<p><span class="bodyGrey">When using dependent relations, one data object class must be declared as
<b>depends</b> on one other data object class in the mapping file, and such an object
is called a dependent data object class. A data object class without
<i>depends</i> declared in the mapping is called a master object. A master object can
be depended upon by zero or more dependent data object class.</span></p>
<p><span class="bodyGrey">As of Castor 0.9, a dependent object class can be related to other master data
object classes including extended classes, but cannot depend on more than one
master class.</span></p>
<p><span class="bodyGrey">If an object class declared as <i>depends</i> on another class, it may not be
created, removed or updated separately. Attempting to create, remove or update a
dependent object will result in ObjectNotPersistcapableException. Note that Castor
doesn'’t allow a dependent object instance to change its master object instance during
a transaction. Each dependent object can have only one master object. Both dependent and
master objects must have identities, and may or may not make use of key-generators.</span></p>
<p><span class="bodyGrey">
Here is the DTD for declaring dependent object:
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
<!ATTLIST class name ID #REQUIRED
extends IDREF #IMPLIED
depends IDREF #IMPLIED
identity CDATA #IMPLIED
access ( read-only | shared | exclusive | db-locked ) "shared"
key-generator IDREF #IMPLIED</pre></span></td></tr></table></td></tr></table><p></p></span></p>
<p><span class="bodyGrey">
For example,
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
<mapping>
<class name="com.xyz.MyDependentObject"
depends="com.xyz.MyObject">
...
</class>
</mapping></pre></span></td></tr></table></td></tr></table><p></p>
declares the data object class <tt>com.xyz.MyDependentObject</tt> as a dependent
upon class <tt>com.xyz.MyObject</tt>.</span></p>
<a name="Different-cardinalities-of-relationship"><h2>Different cardinalities of relationship</h2></a>
<p><span class="bodyGrey">Castor supports different cardinalities of relationship, namely one-to-one,
one-to-many, and many-to-many. Many-to-many relationship must be related rather than
dependent, because each dependent object can have only one master object. </span></p>
<p><span class="bodyGrey">Many-to-many requires a separate table for storing the relations between two types of
objects. Many-to-many introduces two attributes, namely many-key and many-table that reside
in the <tt><sql></tt> element which is a sub-element of the <tt><field></tt>
element. For all many-to-many relations, a many-table must be specified. If the column
name of the primary key of the class is different from the foreign keys columns of the
class in the relation tables, then the relation table columns can be specified using the
many-key attributes. Similarly, if the column name of the primary key of the related class
is different from the foreign key columns of the related class, then the relation table
columns can be specified using the name attribute. </span></p>
<p><span class="bodyGrey">The many-table is used to store relations in a separate table
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
<mapping>
<class>
<field>
<sql many-key="#OPTIONAL" name="#OPTIONAL"
many-table="#REQURIED">
</field>
</class>
</mapping></pre></span></td></tr></table></td></tr></table><p></p>
</span></p>
<p><span class="bodyGrey">
So, for example, if the SQL table is the following,
<center>
<b>employee_table</b></center>
<center><table BORDER="true" COLS="3" WIDTH="60%">
<tr ALIGN="CENTER">
<td><span class="bodyGrey"><b>id</b></span></td> <td><span class="bodyGrey"><b>name</b></span></td> <td><span class="bodyGrey"><b>salary</b></span></td>
</tr>
<tr>
<td><span class="bodyGrey">1482</span></td> <td><span class="bodyGrey">Smith, Bob</span></td> <td><span class="bodyGrey">$123,456</span></td>
</tr>
<tr>
<td><span class="bodyGrey">628</span></td> <td><span class="bodyGrey">Lee, John</span></td> <td><span class="bodyGrey">$43,210</span></td>
</tr>
<tr>
<td><span class="bodyGrey">1926</span></td> <td><span class="bodyGrey">Arnold, Pascal</span></td> <td><span class="bodyGrey">$24,680</span></td>
</tr></table></center>
<center>
<b>department_table</b></center>
<center><table BORDER="true" COLS="3" WIDTH="60%">
<tr ALIGN="CENTER">
<td><span class="bodyGrey"><b>id</b></span></td> <td><span class="bodyGrey"><b>name</b></span></td> <td><span class="bodyGrey"><b>comment</b></span></td>
</tr>
<tr>
<td><span class="bodyGrey">3</span></td> <td><span class="bodyGrey">Accounting</span></td> <td><span class="bodyGrey"></span></td>
</tr>
<tr>
<td><span class="bodyGrey">7</span></td> <td><span class="bodyGrey">Engineering</span></td> <td><span class="bodyGrey">The very important department. :-)</span></td>
</tr>
</table></center>
<center>
<b>employee_department</b></center>
<center><table BORDER="true" COLS="2" WIDTH="40%">
<tr ALIGN="CENTER">
<td><span class="bodyGrey"><b>e_id</b></span></td> <td><span class="bodyGrey"><b>d_id</b></span></td>
</tr>
<tr>
<td><span class="bodyGrey">....</span></td> <td><span class="bodyGrey">....</span></td>
</tr>
</table></center></span></p>
<p><span class="bodyGrey">
Then, the mapping for employee data object would look like this
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
<mapping>
<class name="com.xyz.Employee" identity="id">
<map-to table="employee_table"/>
<field name="id" type="integer">
<sql name="id"/>
</field>
<field>
<sql many-table="employee_department"
many-key="e_id" name="d_id"/>
</field>
<field name="salary">
<sql name="salary" type="integer">
</field>
</class>
</mapping></pre></span></td></tr></table></td></tr></table><p></p></span></p>
<a name="Lazy-Loading"><h2>Lazy Loading</h2></a>
<p><span class="bodyGrey">As of release 0.9.6, Castor has full support for lazy loading object instances referenced
as part of all relation types currently supported:</span></p>
<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">-</td><td valign="top" align="left"><span class="bodyGrey">1:1 relations</span></td></tr>
<tr><td width="10" valign="top" align="left">-</td><td valign="top" align="left"><span class="bodyGrey">1:m relations</span></td></tr>
<tr><td width="10" valign="top" align="left">-</td><td valign="top" align="left"><span class="bodyGrey">M:N relations.</span></td></tr>
</span></table>
<a name="1:1-relations"><h3>1:1 relations</h3></a>
<p><span class="bodyGrey">As of release 0.9.6, Castor supports lazy-loading of 1:1 relations. Imagine the
following class mapping:</span></p>
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
<mapping>
<class name="com.xzy.Department">
...
<field "employee" type="com.xyz.Employee" lazy="true" />
...
</class>
</mapping></pre></span></td></tr></table></td></tr></table><p></p>
<p><span class="bodyGrey">Per definition, when an instance of Department is loaded through e.g. Database.load(),
Castor will not (pre-)load the Employee instance referenced (as such reducing the size
pf the initial query as well as the size of the result set returned). Only when the
Emplyoee instance is accessed through Department.getEmployee(), Castor will load
the actual object into memory from the persistence store.</span></p>
<p><span class="bodyGrey">This means that if the Employee instance is not accessed at all, not only will
the initial query to load the Department object have had its complexity reduced,
but no performance penalty will be incurred for the additional access to the
persistence store either.</span></p>
<a name="1:M-and-M:N-relations"><h3>1:M and M:N relations</h3></a>
<p><span class="bodyGrey">The elements in the collection are only loaded when the application asks for
the object from the collection, using, for example, iterator.next(). The
iterator in Castor’s lazy collection is optimized to return a loaded object
first.</span></p>
<p><span class="bodyGrey">In the mapping file, lazy loading is specified in the element of the collection’s
<tt><field></tt>, for example,</span></p>
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
<mapping>
<class name="com.xzy.Department">
...
<field name="employee" type="com.xyz.Employee" lazy="true"
collection="collection"/>
</class>
</mapping></pre></span></td></tr></table></td></tr></table><p></p>
<p><span class="bodyGrey">declares that the collection of type Employee in a Department is lazy loaded.</span></p>
<p><span class="bodyGrey">If lazy loading is specified for a field of a class, Castor will set the field with a
special collection which contains only the identities of the objects. Because of
that, it requires the data object to have the method setDepartment( Collection
department) in the data object class which was not required in previous
versions.</span></p>
<p><table bgcolor="#7270c2" cellpadding="3" cellspacing="1" border="0" width="100%"><tr><td><span class="noteHeader">Note</span></td></tr><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="noteBody">Please note that currently <b>only</b> the <tt><b>java.util.Collection</b></tt>
type is supported. </span></td></tr></table></td></tr></table></p>
<a name="Multiple-columns-primary-keys"><h2>Multiple columns primary keys</h2></a>
<p><span class="bodyGrey">
The support of multiple column primary keys (also called compound primary keys) was another major enhancement added into Castor 0.9. Specifying multiple column primary keys is simple and straightforward, in the mapping file,
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
<mapping>
<class name="com.xyz.MyObject" identity="firstName lastName">
<field name="firstName" type="string">
<sql name="fname"/>
</field>
<field name="lastName" type="string">
<sql name="lname"/>
</field>
...
</class>
</mapping></pre></span></td></tr></table></td></tr></table><p></p></span></p>
<p><span class="bodyGrey">Multiple column primary keys work with both master and dependent objects, all
cardinalities of relationship, including one-to-one, one-to-many and many-to-many,
as well as lazy loading. </span></p>
<p><span class="bodyGrey">However, multiple column primary keys should only be used to adhere to an existing
database design, not when designing a new database. In general, it is not a good
idea to use an identity or identities which can be modified by the user, or which
contain application-visible data. For example, if the system allows the user name to
be changed, using user name as identity is highly discouraged, as this practice can require
a major data migration to a new schema to update all foreign keys to adhere to a
new primary key structure, should the user name no longer be adequate as a primary key. It should
be noted that Castor doesn’t support identity change, as specified in the ODMG 3.0
specification. So, primary keys changes are almost certainly a large trade off between
data integrity and performance. Well chosen primary keys are usually single (not
multiple) column numeric or character fields for the reasons outlined above, as well as
performance, as joining operations are faster for single column primary keys. </span></p>
<a name="Callback-interface-for-persistent-operations"><h2>Callback interface for persistent operations</h2></a>
<p><span class="bodyGrey">For the various persistence operations as available through the
<a href="javadoc/org/exolab/castor/jdo/Database.html#Database">Database</a>
interface, Castor JDO provides a callback interface that informs the
implementing class on events taking place related to selected
persistence operations.</span></p>
<p><span class="bodyGrey">Once your entity class implements the
<a href="javadoc/org/exolab/castor/jdo/Persistence.html#Persistence">Persistence</a> interface,
you'll have to provide implementations for the following methods (with their
respective semantics described next to them):</span></p>
<table bgcolor="#7270c2" cellpadding="2" cellspacing="1" width="100%" border="0"><tr><td><table bgcolor="#ededed" cellpadding="8" cellspacing="1" width="100%" border="0"><caption></caption><tr class="cheader"><td class="cheader">Method</td><td class="cheader">Description</td></tr><tr bgcolor="#DDDDDD">
<td><span class="bodyGrey">jdoAfterCreate()</span></td>
<td><span class="bodyGrey">Indicates that an object has been created in persistent storage.</span></td>
</tr><tr bgcolor="#FFFFFF">
<td><span class="bodyGrey">jdoAfterRemove()</span></td>
<td><span class="bodyGrey">Indicates that an object has been removed from persistent storage.</span></td>
</tr><tr bgcolor="#DDDDDD">
<td><span class="bodyGrey">jdoBeforeCreate()</span></td>
<td><span class="bodyGrey">Indicates that an object is to be created in persistent storage.</span></td>
</tr><tr bgcolor="#FFFFFF">
<td><span class="bodyGrey">jdoBeforeRemove()</span></td>
<td><span class="bodyGrey">Indicates that an object is to be removed from persistent storage.</span></td>
</tr><tr bgcolor="#DDDDDD">
<td><span class="bodyGrey">jdoLoad()</span></td>
<td><span class="bodyGrey">Indicates that the object has been loaded from persistent storage.</span></td>
</tr><tr bgcolor="#FFFFFF">
<td><span class="bodyGrey">jdoPersistent(Database)</span></td>
<td><span class="bodyGrey">Sets the database to which this object belongs when this object becomes persistent.</span></td>
</tr><tr bgcolor="#DDDDDD">
<td><span class="bodyGrey">jdoStore()</span></td>
<td><span class="bodyGrey">Indicates that an object is to be stored in persistent storage.</span></td>
</tr><tr bgcolor="#FFFFFF">
<td><span class="bodyGrey">jdoTransient()</span></td>
<td><span class="bodyGrey">Indicates the object is now transient.</span></td>
</tr><tr bgcolor="#DDDDDD">
<td><span class="bodyGrey">jdoUpdate()</span></td>
<td><span class="bodyGrey">Indicates that an object has been included to the current transaction by
means of db.update() method (in other words, at the end of a
"long" transaction).</span></td>
</tr></table></td></tr></table>
</td></tr><tr height="5"><td align="left" valign="top" bgcolor="#7270c2" height="5" width="10"> </td><td valign="top" bgcolor="#7270c2" height="5" width="150"><img border="0" height="15" width="1" src="images/dotTrans.gif"><br><img align="right" border="0" height="3" width="105" src="images/line_sm.gif"></td><td align="left" valign="top" bgcolor="#a9a5de" height="5" width="7"> </td><td align="left" valign="top" height="5" width="70"> </td><td align="left" valign="top" height="5" width="120"> </td></tr><tr><td align="left" valign="top" bgcolor="#7270c2" height="5" width="10"> </td><td align="left" valign="top" bgcolor="#7270c2" width="150"></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="70"><img border="0" height="25" width="1" src="images/dotTrans.gif"></td><td align="left" valign="top" width="120"> </td></tr><tr height="5"><td align="left" valign="bottom" bgcolor="#7270c2" height="100%" rowspan="2" width="10"><img border="0" height="125" width="10" src="images/stripes1.gif"></td><td align="left" valign="bottom" bgcolor="#7270c2" height="100%" rowspan="2" width="150"><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"> </td><td align="left" valign="top" height="100%" width="70"> </td><td align="left" valign="top" height="100%" width="120"> </td></tr><tr height="5"><td align="left" valign="top" height="25" width="70"> </td><td align="left" valign="bottom" height="25" width="400"><br><br><img height="3" width="400" border="0" src="images/line_light.gif"><br><p></p><span class="bodyGrey"><small><notice>
Copyright © 1999-2005 <a href="http://www.exolab.org">ExoLab Group</a>, Intalio Inc.,
and Contributors. All rights reserved.
</notice><br> <br></small><small><notice>
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> <br></small></span><p></p>
</td><td align="left" valign="top" height="25" width="120"> </td></tr></table><script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script><script type="text/javascript">
var pageTracker = _gat._getTracker("UA-3544187-1");
pageTracker._trackPageview();
</script></body></html>
