<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> <html><head><title></title><link rel="stylesheet" href="default.css"></head><body bgcolor="#ffffff" link="#6763a9" vlink="#6763a9" topmargin="0" bottommargin="0" leftmargin="0" marginheight="0" marginwidth="0"><a name="top"></a><table border="0" cellpadding="0" cellspacing="0" height="400"><tr><td width="10" valign="top" align="left" bgcolor="#7270c2"><img src="images/dotTrans.gif" width="1" height="1" border="0"></td><td width="115" valign="top" align="left" bgcolor="#7270c2"><img src="images/dotTrans.gif" width="1" height="1" border="0"></td><td width="7" valign="top" align="left"><img src="images/dotTrans.gif" border="0" width="1" height="1"></td><td width="70" valign="top" align="left"><img src="images/dotTrans.gif" width="70" height="6" border="0"></td><td width="400" valign="top" align="left"><img src="images/top_2.gif" width="400" height="6" border="0"></td><td width="120" valign="top" align="left"><img src="images/line_purple.gif" width="120" height="6" border="0"></td></tr><tr><td width="10" bgcolor="#7270c2" valign="top" align="left"><img src="images/dotTrans.gif" border="0" width="1" height="1"></td><td width="115" bgcolor="#7270c2" valign="top" align="left"><img src="images/dotTrans.gif" border="0" width="1" height="1"></td><td width="7" bgcolor="#ffffff" valign="top" align="left"></td><td width="70" valign="top" align="left"><img src="images/dotTrans.gif" width="1" height="1" border="0"></td><td width="400" valign="middle" align="left"><a href="http://www.exolab.org"><span class="menuTopOff">ExoLab</span></a> <a href="http://openejb.sf.net"><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="menuTopOff">OpenORB</span></a> <a href="http://castor.exolab.org"><span class="menuTopOn">Castor</span></a> <a href="http://tyrex.sf.net"><span class="menuTopOff">Tyrex</span></a> <br><img src="images/dotTrans.gif" width="1" height="2" border="0"></td><td width="120" height="20" valign="top" align="left"> </td></tr><tr><td width="10" bgcolor="#7270c2" valign="top" align="left"><img src="images/dotTrans.gif" width="10" height="3" border="0"></td><td width="115" bgcolor="#7270c2" valign="top" align="right"><img src="images/line_sm.gif" width="105" height="3" border="0"></td><td width="7" bgcolor="#a9a5de" valign="top" align="left"><img src="images/line_sm.gif" width="7" height="3" border="0"></td><td width="70" valign="top" align="left"><img src="images/line_light.gif" width="70" height="3" border="0"></td><td width="400" valign="top" align="left"><img src="images/line_light.gif" width="400" height="3" border="0"></td><td width="120" valign="top" align="left"><img src="images/dotTrans.gif" border="0" width="1" height="1"></td></tr><tr><td bgcolor="#7270c2" valign="top" align="left"><img src="images/dotTrans.gif" width="10" height="10" border="0"></td><td width="115" bgcolor="#7270c2" valign="top" align="left"><img src="images/dotTrans.gif" width="1" height="2" border="0"><br><table border="0" cellpadding="0" cellspacing="0"><tr><td valign="top" align="left"><span class="subMenuOn">Main</span></td></tr><tr><td valign="top" align="left"> <a href="index.html"><span class="subMenuOff">Home</span></a></td></tr><tr><td valign="top" align="left"> <a href="download.html"><span class="subMenuOff">Download</span></a></td></tr><tr><td valign="top" align="left"> <a href="api/overview-summary.html"><span class="subMenuOff">API</span></a></td></tr><tr><td valign="top" align="left"> <a href="schema.html"><span class="subMenuOff">Schema</span></a></td></tr><tr><td valign="top" align="left"> <a href="lists.html"><span class="subMenuOff">Mailing Lists</span></a></td></tr><tr><td valign="top" align="left"> <a href="cvs.html"><span class="subMenuOff">CVS / Bugzilla</span></a></td></tr><tr><td valign="top" align="left"> <a href="support.html"><span class="subMenuOff">Support</span></a></td></tr></table><br><table border="0" cellpadding="0" cellspacing="0"><tr><td valign="top" align="left"><span class="subMenuOn">XML</span></td></tr><tr><td valign="top" align="left"> <a href="xml-framework.html"><span class="subMenuOff">Using XML</span></a></td></tr><tr><td valign="top" align="left"> <a href="sourcegen.html"><span class="subMenuOff">Source Generator</span></a></td></tr><tr><td valign="top" align="left"> <a href="xmlschema.html"><span class="subMenuOff">Schema Support</span></a></td></tr><tr><td valign="top" align="left"> <a href="xml-mapping.html"><span class="subMenuOff">XML Mapping</span></a></td></tr><tr><td valign="top" align="left"> <a href="xml-faq.html"><span class="subMenuOff">XML FAQ</span></a></td></tr></table><br><table border="0" cellpadding="0" cellspacing="0"><tr><td valign="top" align="left"><span class="subMenuOn">JDO</span></td></tr><tr><td valign="top" align="left"> <a href="jdo.html"><span class="subMenuOff">Using JDO</span></a></td></tr><tr><td valign="top" align="left"> <a href="database-conf.html"><span class="subMenuOff">JDO Config</span></a></td></tr><tr><td valign="top" align="left"> <a href="types.html"><span class="subMenuOff">Types</span></a></td></tr><tr><td valign="top" align="left"> <a href="jdo-mapping.html"><span class="subMenuOff">JDO Mapping</span></a></td></tr><tr><td valign="top" align="left"> <a href="jdo-faq.html"><span class="subMenuOff">JDO FAQ</span></a></td></tr><tr><td valign="top" align="left"> <a href="castor-one.html"><span class="subMenuOff">Other Features</span></a></td></tr></table><br><table border="0" cellpadding="0" cellspacing="0"><tr><td valign="top" align="left"><span class="subMenuOn">Advanced JDO</span></td></tr><tr><td valign="top" align="left"> <a href="oql.html"><span class="subMenuOff">OQL</span></a></td></tr><tr><td valign="top" align="left"> <a href="locking.html"><span class="subMenuOff">Trans. & Locks</span></a></td></tr><tr><td valign="top" align="left"> <a href="design-persist.html"><span class="subMenuOff">Design</span></a></td></tr><tr><td valign="top" align="left"> <a href="key-generator.html"><span class="subMenuOff">KeyGen</span></a></td></tr><tr><td valign="top" align="left"> <a href="long-transact.html"><span class="subMenuOff">Long Trans.</span></a></td></tr><tr><td valign="top" align="left"> <a href="nested-attr.html"><span class="subMenuOff">Nested Attrs.</span></a></td></tr><tr><td valign="top" align="left"> <a href="pooling.html"><span class="subMenuOff">Pooling Examples</span></a></td></tr><tr><td valign="top" align="left"> <a href="postgresql-blobs.html"><span class="subMenuOff">Blobs and PostgreSQL</span></a></td></tr></table><br><table border="0" cellpadding="0" cellspacing="0"><tr><td valign="top" align="left"><span class="subMenuOn">More</span></td></tr><tr><td valign="top" align="left"> <a href="presentations.html"><span class="subMenuOff">Presentations</span></a></td></tr><tr><td valign="top" align="left"> <a href="examples.html"><span class="subMenuOff">The Examples</span></a></td></tr><tr><td valign="top" align="left"> <a href="extras.html"><span class="subMenuOff">Extras and 3rd Party Tools</span></a></td></tr><tr><td valign="top" align="left"> <a href="test-framework.html"><span class="subMenuOff">Test Framework -- JDO</span></a></td></tr><tr><td valign="top" align="left"> <a href="ctf.html"><span class="subMenuOff">Test Framework -- XML</span></a></td></tr><tr><td valign="top" align="left"> <a href="conf-lib.html"><span class="subMenuOff">Configuration</span></a></td></tr><tr><td valign="top" align="left"> <a href="tips-tricks.html"><span class="subMenuOff">Tips & Tricks</span></a></td></tr><tr><td valign="top" align="left"> <a href="javadoc/overview-summary.html"><span class="subMenuOff">Full JavaDoc</span></a></td></tr></table><br><table border="0" cellpadding="0" cellspacing="0"><tr><td valign="top" align="left"><span class="subMenuOn">About</span></td></tr><tr><td valign="top" align="left"> <a href="license.html"><span class="subMenuOff">License</span></a></td></tr><tr><td valign="top" align="left"> <a href="contributors.html"><span class="subMenuOff">Contributors</span></a></td></tr><tr><td valign="top" align="left"> <a href="status.html"><span class="subMenuOff">Status, Todo</span></a></td></tr><tr><td valign="top" align="left"> <a href="changelog.html"><span class="subMenuOff">Changelog</span></a></td></tr><tr><td valign="top" align="left"> <a href="library.html"><span class="subMenuOff">Library</span></a></td></tr><tr><td valign="top" align="left"> <a href="contacts.html"><span class="subMenuOff">Contact</span></a></td></tr></table><br></td><td width="7" bgcolor="#a9a5de" valign="top" align="left"> </td><td width="70" valign="top" align="left"> </td><td rowspan="4" width="400" valign="top"><table cols="2" rows="2" border="0" cellpadding="0" cellspacing="0" width="400"><tr><td valign="top" align="left"><br><img border="0" height="34" hspace="0" src="images/castor.gif" vspace="0" width="115"><br><img border="0" height="10" hspace="0" src="images/dotTrans.gif"></td><td width="120" height="5" valign="top" align="right"><a href="http://www.exolab.org"><img src="images/logo_exolab.gif" hspace="0" vspace="10" width="77" height="20" border="0"></a></td></tr></table><p></p><p></p><br><span class="header">Castor Persistence Architecture</span><br><br><span class="bodyGrey"><a href="#Layered-Achitecture">Layered Achitecture</a><br></span><span class="bodyGrey"><a href="#Persistence-API">Persistence API</a><br></span><span class="bodyGrey"><a href="#Transactions">Transactions</a><br></span><span class="bodyGrey"><a href="#OIDs-and-Locks">OIDs and Locks</a><br></span><span class="bodyGrey"><a href="#Cache-Engine">Cache Engine</a><br></span><span class="bodyGrey"><a href="#Pessimistic/Optimistic-Locking">Pessimistic/Optimistic Locking</a><br></span><span class="bodyGrey"><a href="#Relations">Relations</a><br></span><span class="bodyGrey"><a href="#QueryResults">QueryResults</a><br></span><span class="bodyGrey"><a href="#Service-Providers-(SPI)">Service Providers (SPI)</a><br></span><span class="bodyGrey"><a href="#Persistence">Persistence</a><br></span><span class="bodyGrey"><a href="#PersistenceQuery">PersistenceQuery</a><br></span><span class="bodyGrey"><a href="#Enterprise-JavaBeans-CMP">Enterprise JavaBeans CMP</a><br></span><br><a name="Layered-Achitecture"><h2>Layered Achitecture</h2></a> <p><span class="bodyGrey">The Castor persistence engine is based on a layer architecture allowing different APIs to be plugged on top of the system, and different persistence engines to be combined in a single environment.</span></p> <div align="center"> <table border="0" cellspacing="8" cellpadding="10" bgcolor="#444466"> <tr> <td bgcolor="#565680" align="center"><span class="bodyGrey" bgcolor="#565680" align="center"> <font color="white">API</font> <table border="0" cellspacing="8" cellpadding="12"> <tr> <td bgcolor="#676799" align="center"><span class="bodyGrey" bgcolor="#676799" align="center"><font color="white">EJB</font></span></td> <td bgcolor="#676799" align="center"><span class="bodyGrey" bgcolor="#676799" align="center"><font color="white">ODMG</font></span></td> <td bgcolor="#676799" align="center"><span class="bodyGrey" bgcolor="#676799" align="center"><font color="white">DAX</font></span></td> <td bgcolor="#676799" align="center"><span class="bodyGrey" bgcolor="#676799" align="center"><font color="white">JNDI</font></span></td> </tr> </table> </span></td> </tr> <tr> <td bgcolor="#565680" align="center"><span class="bodyGrey" bgcolor="#565680" align="center"> <font color="white">Persistence</font> <table border="0" cellspacing="8" cellpadding="12"> <tr> <td bgcolor="#676799" align="center"><span class="bodyGrey" bgcolor="#676799" align="center"><font color="white">Transactions</font></span></td> <td bgcolor="#676799" align="center"><span class="bodyGrey" bgcolor="#676799" align="center"><font color="white">Caching</font></span></td> <td bgcolor="#676799" align="center"><span class="bodyGrey" bgcolor="#676799" align="center"><font color="white">Relations</font></span></td> </tr> </table> </span></td> </tr> <tr> <td bgcolor="#565680" align="center"><span class="bodyGrey" bgcolor="#565680" align="center"> <font color="white">Service Providers</font> <table border="0" cellspacing="8" cellpadding="8"> <tr> <td bgcolor="#676799" align="center"><span class="bodyGrey" bgcolor="#676799" align="center"><font color="white">SQL 92</font></span></td> <td bgcolor="#676799" align="center"><span class="bodyGrey" bgcolor="#676799" align="center"><font color="white">Oracle</font></span></td> <td bgcolor="#676799" align="center"><span class="bodyGrey" bgcolor="#676799" align="center"><font color="white">Sybase</font></span></td> <td bgcolor="#676799" align="center"><span class="bodyGrey" bgcolor="#676799" align="center"><font color="white">LDAP</font></span></td> </tr> </table> </span></td> </tr> </table> </div> <p><span class="bodyGrey">At the top level are the application level APIs. These are industry standard APIs that allow an application to be ported in and to other environments. These APIs consist of interfaces as well as semantics that make them suitable for a particular type of applications.</span></p> <p><span class="bodyGrey">At the medium level is the Castor persistence mechanism. The persistence mechanism exposes itself to the application through the application level APIs. These typically have a one to one mapping with the persistence mechanism API. The persistence mechanism takes care of object caching and rollback, locking and deadlock detection, transactional integrity, and two phase commit.</span></p> <p><span class="bodyGrey">At the bottom level are the Castor service providers. SPIs provide the persistence and query support into a variety of persistence mechanism. This version of Castor is bundled with an SQL 92 and LDAP persistence SPIs. Additional SPIs can be added, for example, alternative engines streamlined for Oracle, Sybase, DB2 and other databases.</span></p> <p><span class="bodyGrey">This document will describe the persistence mechanism API and SPI to allow for those interested in adding new top level APIs or service providers.</span></p> <a name="Persistence-API"><h2>Persistence API</h2></a> <p><span class="bodyGrey">The persistence mechanism is responsible for object caching and rollback, locking and deadlock detection, transaction integrity and two phase commit. All data access goes through the persistence mechanism. All operations are performed in the context of a transaction, even if the underlying SPI does not support transactions (e.g. LDAP).</span></p> <p><span class="bodyGrey">The persistence API is defined in the package <a href="javadoc/org/exolab/castor/persist/package-summary.html"><javadoc type="package">org.exolab.castor.persist</javadoc></a>. The persistence mechanism implements the <a href="javadoc/org/exolab/castor/persist/PersistenceEngine.html"><javadoc>org.exolab.castor.persist.PersistenceEngine</javadoc></a> interface, which allows objects to be loaded, created, deleted and locked in the context of a transaction. The actual implementation is obtained from <a href="javadoc/org/exolab/castor/persist/PersistenceEngineFactory.html"><javadoc>org.exolab.castor.persist.PersistenceEngineFactory</javadoc></a>.</span></p> <p><span class="bodyGrey">All operations are performed through the context of a transaction. A transaction is required in order to properly manage locking and caching, and to automatically commit or rollback objects at transaction termination (write-at-commit). Persistence operations are performed through the <a href="javadoc/org/exolab/castor/persist/TransactionContext.html"><javadoc>org.exolab.castor.persist.TransactionContext</javadoc></a> interface.</span></p> <p><span class="bodyGrey">The actual implementation of a transaction context is specific to each application API and set of SPIs. One is created from an <a href="javadoc/org/exolab/castor/persist/XAResourceSource.html"><javadoc>org.exolab.castor.persist.XAResourceSource</javadoc></a> which abstracts the data source for the purpose of connection pooling and XA transaction enlistment. A default implementation of <tt>XAResource</tt> is available from <a href="javadoc/org/exolab/castor/persist/XAResourceImpl.html"><javadoc>org.exolab.castor.persist.XAResourceImpl</javadoc></a>.</span></p> <a name="Transactions"><h3>Transactions</h3></a> <p><span class="bodyGrey">Every persistence operation is performed within the context of a transaction. This allows changes to objects to be saved when the transaction commits and to be rolled back when the transaction aborts. Using a transactional API relieves the application developer from worrying about the commit/rollback phase. In addition it allows distributed transactions to be managed by a transactional environment, such as an EJB server.</span></p> <p><span class="bodyGrey">Each time an object is retrieved or created the operation is performed in the context of a transaction and the object is recorded with the transaction and locked. When the transaction completes, the modified object is persisted automatically. If not all objects can be persisted, the transaction rolls back. The transaction context implements full two phase commit.</span></p> <p><span class="bodyGrey">Each transaction sees it's own view of the objects it retrieves from persistent storage. Until the transaction commit, these changes are viewable only within that transaction. If the transaction rolled back, the objects are automatically reverted to their state in persistent storage.</span></p> <p><span class="bodyGrey">The transaction context (<a href="javadoc/org/exolab/castor/persist/TransactionContext.html"><javadoc>org.exolab.castor.persist.TransactionContext</javadoc></a>) is the only mechanism by which the top level APIs can interact with the persistence engine. A new transaction must be opened in order to perform any operation.</span></p> <p><span class="bodyGrey">A transaction context is not created directly, but through a derived class that implements the proper mechanism for obtaining a new connection, committing and rolling back the connection. Note that commit and rollback operations are only required in a non-JTA environment. When running inside a JTA environment (e.g. an EJB server), the container is responsible to commit/rollback the underlying connection.</span></p> <p><span class="bodyGrey">Application level APIs implement data sources that can be enlisted directly with the transaction monitor through the JTA <tt>XAResource</tt> interface. A data source can be implemented using <a href="javadoc/org/exolab/castor/persist/XAResourceSource.html"><javadoc>org.exolab.castor.persist.XAResourceSource</javadoc></a> which serves as a factory for new transaction contexts and <a href="javadoc/org/exolab/castor/persist/XAResourceImpl.html"><javadoc>org.exolab.castor.persist.XAResourceImpl</javadoc></a> which provides an <tt>XAResource</tt> implementation.</span></p> <a name="OIDs-and-Locks"><h3>OIDs and Locks</h3></a> <p><span class="bodyGrey">Each object participating in a transaction is associated with an object identifier, or <b>OID</b> (<tt>org.exolab.castor.persist.OID</tt>). The OID identifies the object through its type and identity value. The identity object must be unique across all OIDs for the same object type in the same persistence engine.</span></p> <p><span class="bodyGrey">Each object is also associated with a lock (<tt>org.exolab.castor.persist.ObjectLock</tt>). An <b>object lock</b> supports read and write locks with deadlock detection. Any number of transactions may acquire a read lock on the object. Read lock allows the transaction to retrieve the object, but not to delete or store it. Prior to deleting or storing the object, the transaction must acquire a write lock. Only one transaction may acquire a write lock, and a write lock will not be granted if there is any read lock on the object.</span></p> <p><span class="bodyGrey">If a transaction requires a read lock on an object which is write-locked by another transaction, or requires a write lock on an object which is read-locked by another transaction, the transaction will block until the lock is released, or the lock timeout has elapsed. The lock timeout is a property of the transaction and is specified in seconds. A <a href="javadoc/org/exolab/castor/persist/LockNotGrantedException.html"><javadoc>org.exolab.castor.persist.LockNotGrantedException</javadoc></a> is thrown if the lock could not be acquired within the specified timeout.</span></p> <p><span class="bodyGrey">This locking mechanism can lead to the possibility of a deadlock. The object lock mechanism provides automatic deadlock detection by tracking blocked transactions, without depending on a lock wait to timeout.</span></p> <p><span class="bodyGrey">Write locks and exclusive locks are always delegated down to the persistence storage. In a distributed environment the database server itself provides the distributed locking mechanism. This approach assures proper concurrency control in a distributed environments where multiple application servers access the same database server.</span></p> <a name="Cache-Engine"><h3>Cache Engine</h3></a> <p><span class="bodyGrey">The concurrency engine includes a layer that acts as a cache engine. This layer is particularly useful for implementing optimistic locking and reducing synchronization with the database layer. It is also used to perform dirty checks and object rollback. The cache engine is implemented in <tt>org.exolab.castor.persist.CacheEngine</tt> and exposed to the application through the <a href="javadoc/org/exolab/castor/persist/PersistenceEngine.html"><javadoc>org.exolab.castor.persist.PersistenceEngine</javadoc></a>.</span></p> <p><span class="bodyGrey">When an object is retrieved from persistent storage it is placed in the cache engine. Subsequent requests to retrieve the same object will return the cached copy (with the exception of pessimistic locking, more below). When the transaction commits, the cached copy will be updated with the modified object. When the transaction rolls back, the object will be reverted to its previous state from the cache engine.</span></p> <p><span class="bodyGrey">In the event of any error or doubt, the cached copy will be dumped from the cache engine. The least recently used objects will be cleared from the cache periodically.</span></p> <p><span class="bodyGrey">The cache engine is associated with a single persistence mechanism, e.g. a database source, and LDAP directory. Proper configuration is the only way to assure that all access to persistent storage goes through the same cache engine.</span></p> <a name="Pessimistic/Optimistic-Locking"><h3>Pessimistic/Optimistic Locking</h3></a> <p><span class="bodyGrey">The concurrency engine works in two locking modes, based on the type of access requested by the application (typically through the API). Pessimistic locking are used in read-write access mode, optimistic locking are used in exclusive access mode.</span></p> <p><span class="bodyGrey">In <b>optimistic locking mode</b> it is assumed that concurrent access to the same object is rare, or that objects are seldom modified. Therefore objects are retrieved with a read lock and are cached in memory across transactions.</span></p> <p><span class="bodyGrey">When an object is retrieved for read/write access, if a copy of the object exists in the cache, that copy will be used. A read lock will be acquired in the cache engine, preventing other Castor transactions from deleting or modifying the object. However, no lock is acquired in persistent storage, allowing other applications to delete or modify the object while the Castor transaction is in progress.</span></p> <p><span class="bodyGrey">To prevent inconsistency, Castor will perform <b>dirty checking</b> prior to storing the object, detecting whether the object has been modified in persistent storage. If the object has been modified outside the transaction, the transaction will rollback. The application must be ready for that possibility, or resort to using pessimistic locking.</span></p> <p><span class="bodyGrey">In <b>pessimistic locking mode</b> it is assumed that concurrent access to the same object is the general case and that objects are often modified. Therefore objects are retrieved with a write lock and are always synchronized against the persistence storage. When talking to a database server, a request to load an object in exclusive mode will always load the object (unless already loaded in the same transaction) using a <tt>SELECT .. FOR UPDATE</tt> which assures no other application can change the object through direct access to the database server.</span></p> <p><span class="bodyGrey">The locking mode is a property of the chosen access mode. The two access modes as well as read-only access can be combined in a single transaction, as a property of the query or object lookup. However, it is not possible to combine access modes for the same object, in certain cases this will lead to a conflict.</span></p> <p><span class="bodyGrey">The pessimistic locking mode is not supported in LDAP and similar non-transactional servers. LDAP does not provide a mechanism to lock records and prevent concurrent access while they are being used in a transaction. Although all Castor access to the LDAP server is properly synchronized, it is possible that an external application will modify or delete a record while that record is being used in a Castor transaction.</span></p> <a name="Relations"><h3>Relations</h3></a> <p><span class="bodyGrey">TBD</span></p> <a name="QueryResults"><h3>QueryResults</h3></a> <p><span class="bodyGrey">TBD</span></p> <a name="Service-Providers-(SPI)"><h2>Service Providers (SPI)</h2></a> <p><span class="bodyGrey">Castor supports a service provider architecture that allows different persistence storage providers to be plugged in. The default implementation includes an SQL 92 provider and an and an LDAP provider. Additional providers will be available optimized for a particular database server or other storage mechanisms.</span></p> <p><span class="bodyGrey">The service provider is defined through two interfaces, <a href="javadoc/org/exolab/castor/persist/spi/Persistence.html"><javadoc>org.exolab.castor.persist.spi.Persistence</javadoc></a> and <a href="javadoc/org/exolab/castor/persist/spi/PersistenceQuery.html"><javadoc>org.exolab.castor.persist.spi.PersistenceQuery</javadoc></a>. The first provides creation, deletion, update and lock services, the second is used to process queries and result sets. Service providers are obtained through the <a href="javadoc/org/exolab/castor/persist/spi/PersistenceFactory.html"><javadoc>org.exolab.castor.persist.spi.PersistenceFactory</javadoc></a> interface.</span></p> <a name="Persistence"><h3>Persistence</h3></a> <p><span class="bodyGrey">The interface <a href="javadoc/org/exolab/castor/persist/spi/Persistence.html"><javadoc>org.exolab.castor.persist.spi.Persistence</javadoc></a> defines the contract between the persistence mechanism and a persistence service provider. Each persistence storage (i.e. database server, directory server) is associated with a single persistence engine, which in turn contains a number of service providers, one per object type. Service providers are acquired through a <a href="javadoc/org/exolab/castor/persist/spi/PersistenceFactory.html"><javadoc>org.exolab.castor.persist.spi.PersistenceFactory</javadoc></a> interface, which is asked by each persistence engine to return implementations for all the object types supported by that persistence engine.</span></p> <p><span class="bodyGrey">The object's identity is an object that unique identifies the object within persistent storage. Typically this would be the primary key on a table, or an RDN for LDAP. The identity object may be a simple type (e.g. integer, string) or a complex type.</span></p> <p><span class="bodyGrey">The service provider may support the stamp mechanism for efficiently tracking dirty objects. The stamp mechanism is a unique identifier of the persistent object that changes when the object is modified in persistent storage. For example, a RAWID in Oracle or TIMESTAMP in Sybase. If a stamp is return by certain operations it will be stored with the object's OID and passed along to the store method.</span></p> <p><span class="bodyGrey">The <tt>create</tt> method is called to create a new object in persistent storage. This method is called when the created object's identity is known. If the object's identity is not know when the object is made persistent, this method will be called only when the transaction commits. This method must check for duplicate identity with an already persistent object, create the object in persistent storage, such that successful completion of the transaction will result in durable storage, and retain a write lock on that object for the duration of the transaction.</span></p> <p><span class="bodyGrey">The <tt>load</tt> method is called to load an object from persistent storage. An object is passed with the requested identity. If the object is found in persistent storage, it's values should be copied into the object passed as argument. If the lock flag is set, this method must create a write lock on the object at the same time it loads it.</span></p> <p><span class="bodyGrey">The <tt>load</tt> method is called in two cases, when an object is first loaded or when an object is synchronized with the database (reloaded) in exclusive access mode. In the second case this method will be called with an object that is already set with values that are not considered valued, and must reset these values.</span></p> <p><span class="bodyGrey">The <tt>store</tt> method is called to store an object into persistent storage. The store method is called for an object that was loaded and modified during a transaction when the transaction commits, as well as for an object that was created during the transaction. This method must update the object in persistent storage and retain a write lock on that object.</span></p> <p><span class="bodyGrey">This method might be given two views of an object, one that is being saved and one that was originally loaded. If the original view is provided as well, this method should attempt to perform dirty check prior to storing the object. Dirty check entails a comparison of the original object against the copy in persistent storage, to determine whether the object has changed in persistent storage since it was originally loaded. The class descriptor will indicate whether the object is interested in dirty checking and which of its fields should be checked.</span></p> <p><span class="bodyGrey">The <tt>delete</tt> method is called to delete an object from persistent storage. The delete method is called when the transaction commits and expects the object to deleted, if it exists. This method is not called when the transaction rolls back, objects created during the transaction with the create method are automatically rolled back by the persistent storage mechanism.</span></p> <p><span class="bodyGrey">The <tt>writeLock</tt> method is called to obtain a write lock on an object for which only a read lock was previously obtained. The <tt>changeIdentity</tt> method is called to change the identity of the object after it has been stored with the old identity.</span></p> <a name="PersistenceQuery"><h3>PersistenceQuery</h3></a> <p><span class="bodyGrey">The interface <a href="javadoc/org/exolab/castor/persist/spi/PersistenceQuery.html"><javadoc>org.exolab.castor.persist.spi.PersistenceQuery</javadoc></a> defines the contract between the persistence engine and a query mechanism.</span></p> <a name="Enterprise-JavaBeans-CMP"><h2>Enterprise JavaBeans CMP</h2></a> <p><span class="bodyGrey">TBD</span></p> </td></tr><tr height="5"><td width="10" height="5" bgcolor="#7270c2" valign="top" align="left"> </td><td width="115" height="5" bgcolor="#7270c2" valign="top"><img src="images/dotTrans.gif" width="1" height="15" border="0"><br><img src="images/line_sm.gif" width="105" height="3" border="0" align="right"></td><td width="7" height="5" bgcolor="#a9a5de" valign="top" align="left"> </td><td width="70" height="5" valign="top" align="left"> </td><td width="120" height="5" valign="top" align="left"> </td></tr><tr><td width="10" height="5" bgcolor="#7270c2" valign="top" align="left"> </td><td width="115" bgcolor="#7270c2" valign="top" align="left"></td><td width="7" bgcolor="#a9a5de" valign="top" align="left"><img src="images/dotTrans.gif" width="1" height="25" border="0"></td><td width="70" valign="top" align="left"><img src="images/dotTrans.gif" width="1" height="25" border="0"></td><td width="120" valign="top" align="left"> </td></tr><tr height="5"><td width="10" rowspan="2" height="100%" bgcolor="#7270c2" valign="bottom" align="left"><img src="images/stripes1.gif" width="10" height="125" border="0"></td><td width="115" rowspan="2" height="100%" bgcolor="#7270c2" valign="bottom" align="left"><img src="images/stripe105.gif" width="105" height="125" border="0"></td><td width="7" rowspan="2" height="100%" bgcolor="#a9a5de" valign="top" align="left"> </td><td width="70" height="100%" valign="top" align="left"> </td><td width="120" height="100%" valign="top" align="left"> </td></tr><tr height="5"><td width="70" height="25" valign="top" align="left"> </td><td width="400" height="25" valign="bottom" align="left"><br><br><img src="images/line_light.gif" border="0" width="400" height="3"><br><p></p><span class="bodyGrey"><small><notice> Copyright ) 1999-2003 <a href="http://www.exolab.org">ExoLab Group</a>. 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 width="120" height="25" valign="top" align="left"> </td></tr></table></body></html>
