Persistence (Castor JavaDoc)

All Known Implementing Classes:

SQLEngine
```
public interface Persistence
```
The persistence engine implements this interface in order to allow objects to be created, removed, loaded, stored, locked and checked for dirtyness.
The caller takes full responsibility to assure integrity of transactions and object caching and only relies on the engine to assist in assuring that through the mechanisms available to it.
All method calls provide an open connection into the persistence storage. The connection is opened by and maintained in the context of a transaction. The type of the connection depends on the persistence engine (JDBC, JNDI, etc).
All method calls provide the object fields and the object identity. The engine must always use the identity passed in the method call and never the identity contained in the object itself.
The stamp is an arbitrary object that is returned on object creation and loading and passed when performing a dirty check. The stamp can be used to detect object dirtyness in a more efficient manner in database that support a stamping mechanism (e.g. Oracle RAWID, Sybase TIMESTAMP).
An implementation of this object must be re-entrant and thread safe. It must depend on the connection passed in each method call and never hold a reference to a connection.

Version:

$Revision: 8752 $ $Date: 2006-04-26 16:24:34 -0600 (Wed, 26 Apr 2006) $

Author:

Assaf Arkin

See Also:

TransactionContext, PersistenceQuery

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method	Description
`Identity`	`create(Database database, java.lang.Object conn, ProposedEntity entity, Identity identity)`	Creates a new object in persistence storage.
`PersistenceQuery`	`createQuery(QueryExpression query, java.lang.Class<?>[] types, AccessMode accessMode)`	Creates and returns a new query object.
`SQLRelationLoader`	`createSQLRelationLoader(java.lang.String manyTable, java.lang.String[] idSQL, int[] idType, TypeConvertor[] idTo, TypeConvertor[] idFrom, java.lang.String[] relatedIdSQL, int[] relatedIdType, TypeConvertor[] ridTo, TypeConvertor[] ridFrom)`
`void`	`delete(java.lang.Object conn, Identity identity)`	Deletes the object from persistent storage, given the object' identity.
`void`	`load(java.lang.Object conn, ProposedEntity proposedObject, Identity identity, AccessMode accessMode)`	Loads the object from persistence storage.
`void`	`store(java.lang.Object conn, Identity identity, ProposedEntity newentity, ProposedEntity oldentity)`	Stores the object in persistent storage, given the object fields and its identity.

- Method Detail
  - create
```
Identity create(Database database,
                java.lang.Object conn,
                ProposedEntity entity,
                Identity identity)
         throws PersistenceException
```
    Creates a new object in persistence storage. Called for an object that was created during the transaction when the identity of that object is known. Creates a new record in persistence storage. Must detect an attempt to create an object with the same identity and must retain a lock on the object after creation. If the identity is null, an identity might be created and returned by this method.
    
    Parameters:
    
    conn - An open connection
    
    entity - The fields to store
    
    identity - The object's identity
    
    Returns:
    
    The object's identity
    
    Throws:
    
    PersistenceException - An object with the same identity already exists in persistent storage or any other persistence error occured.
  - load
```
void load(java.lang.Object conn,
          ProposedEntity proposedObject,
          Identity identity,
          AccessMode accessMode)
   throws PersistenceException
```
    Loads the object from persistence storage. This method will load the object fields from persistence storage based on the object's identity. This method may return a stamp which can be used at a later point to determine whether the copy of the object in persistence storage is newer than the cached copy (see store(java.lang.Object, org.exolab.castor.persist.spi.Identity, org.castor.persist.ProposedEntity, org.castor.persist.ProposedEntity)). If lock is true the object must be locked in persistence storage to prevent concurrent updates.
    
    Parameters:
    
    conn - An open connection
    
    proposedObject - The fields to load into
    
    identity - object's identity
    
    accessMode - The access mode (null equals shared)
    
    Throws:
    
    PersistenceException - The object was not found in persistent storage or any other persistence error occured.
  - store
```
void store(java.lang.Object conn,
           Identity identity,
           ProposedEntity newentity,
           ProposedEntity oldentity)
    throws PersistenceException
```
    Stores the object in persistent storage, given the object fields and its identity. The object has been loaded before or has been created through a call to create(org.exolab.castor.jdo.Database, java.lang.Object, org.castor.persist.ProposedEntity, org.exolab.castor.persist.spi.Identity). This method should detect whether the object has been modified in persistent storage since it was loaded. After this method returns all locks on the object must be retained until the transaction has completed. This method may return a new stamp to track further updates to the object.
    If the object was not retrieved for exclusive access, this method will be asked to perform dirty checking prior to storing the object. The original argument will contains the object's original fields as retrieved in the transaction, and stamp the object's stamp returned from a successful call to load(java.lang.Object, org.castor.persist.ProposedEntity, org.exolab.castor.persist.spi.Identity, org.exolab.castor.mapping.AccessMode). These arguments are null for objects retrieved with an exclusive lock.
    
    Parameters:
    
    conn - An open connection
    
    newentity - The fields to store
    
    identity - The object's identity
    
    oldentity - The original fields, or null
    
    Throws:
    
    PersistenceException - The object has been modified in persistence storage since it was last loaded or has been deleted from persitence storage or any other persistence error occored.
  - delete
```
void delete(java.lang.Object conn,
            Identity identity)
     throws PersistenceException
```
    Deletes the object from persistent storage, given the object' identity. The object has been loaded before or has been created through a call to create(org.exolab.castor.jdo.Database, java.lang.Object, org.castor.persist.ProposedEntity, org.exolab.castor.persist.spi.Identity). After this method returns all locks on the object must be retained until the transaction has completed.
    
    Parameters:
    
    conn - An open connection
    
    identity - The object's identity
    
    Throws:
    
    PersistenceException - A persistence error occured
  - createQuery
```
PersistenceQuery createQuery(QueryExpression query,
                             java.lang.Class<?>[] types,
                             AccessMode accessMode)
                      throws QueryException
```
    Creates and returns a new query object. The query object is used to execute a query against persistent storage and fetch the results of the query. The query parameter types are specified prehand. If a particular parameter type is unknown, null may be used and type checking will defer to query execution.
    
    Parameters:
    
    query - The query expression
    
    types - List of all parameter types, or null
    
    Returns:
    
    A new query object that can be executed
    
    Throws:
    
    QueryException - The query is invalid
  - createSQLRelationLoader
```
SQLRelationLoader createSQLRelationLoader(java.lang.String manyTable,
                                          java.lang.String[] idSQL,
                                          int[] idType,
                                          TypeConvertor[] idTo,
                                          TypeConvertor[] idFrom,
                                          java.lang.String[] relatedIdSQL,
                                          int[] relatedIdType,
                                          TypeConvertor[] ridTo,
                                          TypeConvertor[] ridFrom)
```

Interface Persistence

Method Summary

Method Detail

create

load

store

delete

createQuery

createSQLRelationLoader