org.exolab.castor.persist.spi
Interface Persistence
- 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.
$Revision: 1.1.1.1 $ $Date: 2003/03/03 07:08:51 $
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.
|
create
public Object create(Database database,
Object conn,
Object[] fields,
Object identity)
throws DuplicateIdentityException,
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.
conn
- An open connectionfields
- The fields to storeidentity
- The object's identity
createQuery
public PersistenceQuery createQuery(QueryExpression query,
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.
query
- The query expression
- A new query object that can be executed
delete
public void delete(Object conn,
Object 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(Database,Object,Object[],Object)
. After this method returns all
locks on the object must be retained until the transaction has
completed.
conn
- An open connectionidentity
- The object's identity
load
public Object load(Object conn,
Object[] fields,
Object identity,
AccessMode accessMode)
throws ObjectNotFoundException,
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(Object,Object[],Object,Object[],Object)
). If
lock is true the object must be
locked in persistence storage to prevent concurrent updates.
conn
- An open connectionfields
- The fields to load intoidentity
- object's identityaccessMode
- The access mode (null equals shared)
- The object's stamp, or null
store
public Object store(Object conn,
Object[] fields,
Object identity,
Object[] original,
Object stamp)
throws ObjectModifiedException,
ObjectDeletedException,
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(Database,Object,Object[],Object)
. 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(Object,Object[],Object,AccessMode)
. These arguments are null for objects
retrieved with an exclusive lock.
conn
- An open connectionfields
- The fields to storeidentity
- The object's identityoriginal
- The original fields, or nullstamp
- The object's stamp, or null
- The object's stamp, or null
writeLock
public void writeLock(Object conn,
Object identity)
throws ObjectDeletedException,
PersistenceException
Obtains a write lock on the object. This method is called in
order to lock the object and prevent concurrent access from
other transactions. The object is known to have been loaded
before either in this or another transaction. This method is
used to assure that updates or deletion of the object will
succeed when the transaction completes, without attempting to
reload the object.
conn
- An open connectionidentity
- The object's identity
Intalio Inc. (C) 1999-2003. All rights reserved http://www.intalio.com