org.jaffa.persistence.engines
Interface IPersistenceEngine

All Known Implementing Classes:

Engine

public interface IPersistenceEngine

The interface for a Persistence Engine.

Method Summary

void	acquireLock(IPersistent object) This will acquire a lock on the database row corrsponding to the input persistent object.
void	add(IPersistent object) Adds an object to the persistent store.
void	close() Frees up the connection to the database.
void	commit() Objects that have been added, objects that have been deleted, and objects that have been updated, will all be persisted via an invocation of this method.
void	delete(IPersistent object) Deletes an object from the persistent store.
Class	getActualPersistentClass(Object persistentObject) This is a helper method to determine the actual class which was used to create an IPersistent instance.
IPersistent	newPersistentInstance(Class persistentClass) Generates an appropriate instance for the input persistentClass.
Collection	query(Criteria criteria) Queries the underlying persistent store based on the search profile passed in the Criteria object.
void	rollback() Rollbacks all the additions, deletions, updations.
void	update(IPersistent object) Updates an object from the persistent store.

Method Detail

newPersistentInstance

public IPersistent newPersistentInstance(Class persistentClass)

Generates an appropriate instance for the input persistentClass. If the persistentClass is a 'Class', then it should implement the 'IPersistent' interface. The persistence engine will simply instantiate the class. If the persistentClass is an 'Interface', then the persistence engine will generate a dynamic proxy, to implement the IPersistent and the 'persistentClass' interfaces.

Parameters:

persistentClass - The actual persistentClass which can represent a 'Class' or an 'Interface'

Returns:

an instance implementing the IPersistent interface.

getActualPersistentClass

public Class getActualPersistentClass(Object persistentObject)

This is a helper method to determine the actual class which was used to create an IPersistent instance. It is quite possible that the input object is a dynamic proxy.

Returns:

The class which was used for instantiating the instance.

add

public void add(IPersistent object)
         throws AddFailedException

Adds an object to the persistent store. The persistence engine may choose to add the object(s) only on a commit.

Parameters:

object - The object to persist.

Throws:

AddFailedException - if any error occurs during the process.

update

public void update(IPersistent object)
            throws UpdateFailedException

Updates an object from the persistent store. The persistence engine may choose to update the object(s) only on a commit.

Parameters:

object - The object to update.

Throws:

UpdateFailedException - if any error occurs during the process.

delete

public void delete(IPersistent object)
            throws DeleteFailedException

Deletes an object from the persistent store. The persistence engine may choose to delete the object(s) only on a commit.

Parameters:

object - The object to delete from persistent storage.

Throws:

DeleteFailedException - if any error occurs during the process.

query

public Collection query(Criteria criteria)
                 throws QueryFailedException,
                        PostLoadFailedException

Queries the underlying persistent store based on the search profile passed in the Criteria object.

Parameters:

criteria - search profile for the query.

Returns:

a Collection of persistent objects.

Throws:

QueryFailedException - if any error occurs during the process.

PostLoadFailedException - if any error occurs during the invocation of the PostLoad trigger on the persistent object.

commit

public void commit()
            throws AddFailedException,
                   UpdateFailedException,
                   DeleteFailedException,
                   CommitFailedException

Objects that have been added, objects that have been deleted, and objects that have been updated, will all be persisted via an invocation of this method.

Throws:

AddFailedException - if any error occurs during the addition of objects to the persistent store.

UpdateFailedException - if any error occurs while updating the objects of the persistent store.

DeleteFailedException - if any error occurs while deleting the objects of the persistent store.

CommitFailedException - if any error occurs during the commit.

rollback

public void rollback()
              throws RollbackFailedException

Rollbacks all the additions, deletions, updations.

Throws:

RollbackFailedException - if any error occurs during the process.

close

public void close()

Frees up the connection to the database.

acquireLock

public void acquireLock(IPersistent object)
                 throws AlreadyLockedObjectException

This will acquire a lock on the database row corrsponding to the input persistent object.

Parameters:

object - The persistent object to be locked.

Throws:

AlreadyLockedObjectException - if the database row has been locked by another process.