org.exolab.castor.persist.spi
public interface Persistence
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: 1.1.1.1 $ $Date: 2003/03/03 07:08:51 $
See Also: TransactionContext PersistenceQuery
Nested Class Summary | |
---|---|
static interface | Persistence.FieldInfo |
Method Summary | |
---|---|
Object | create(Database database, Object conn, Object[] fields, Object identity)
Creates a new object in persistence storage. |
PersistenceQuery | createQuery(QueryExpression query, Class[] types, AccessMode accessMode)
Creates and returns a new query object. |
void | delete(Object conn, Object identity)
Deletes the object from persistent storage, given the object'
identity. |
Persistence.FieldInfo[] | getInfo() |
Object | load(Object conn, Object[] fields, Object identity, AccessMode accessMode)
Loads the object from persistence storage. |
Object | store(Object conn, Object[] fields, Object identity, Object[] original, Object stamp)
Stores the object in persistent storage, given the object fields
and its identity. |
void | writeLock(Object conn, Object identity)
Obtains a write lock on the object. |
Parameters: conn An open connection fields The fields to store identity The object's identity
Returns: The object's identity
Throws: DuplicateIdentityException An object with the same identity already exists in persistent storage PersistenceException A persistence error occured
Parameters: query The query expression type List of all parameter types, or null
Returns: A new query object that can be executed
Throws: QueryException The query is invalid
Parameters: conn An open connection identity The object's identity
Throws: PersistenceException A persistence error occured
Parameters: conn An open connection fields The fields to load into identity object's identity accessMode The access mode (null equals shared)
Returns: The object's stamp, or null
Throws: ObjectNotFoundException The object was not found in persistent storage PersistenceException A persistence error occured
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 Persistence. These arguments are null for objects retrieved with an exclusive lock.
Parameters: conn An open connection fields The fields to store identity The object's identity original The original fields, or null stamp The object's stamp, or null
Returns: The object's stamp, or null
Throws: ObjectModifiedException The object has been modified in persistence storage since it was last loaded ObjectDeletedException Indicates the object has been deleted from persistence storage PersistenceException A persistence error occured
Parameters: conn An open connection identity The object's identity
Throws: ObjectDeletedException Indicates the object has been deleted from persistence storage PersistenceException A persistence error occured