org.objectweb.perseus.persistence.api
Interface PersistenceManager

All Known Subinterfaces:

TransactionalPersistenceManager

All Known Implementing Classes:

TransactionalPersistenceManagerImpl

public interface PersistenceManager

Author:

Luciano Garcia-Banuelos (Luciano.Garcia@imag.fr)

Method Summary

void	accessCompletion(WorkingSet context, State ce) This method can be used to mark the end of an access to a data object.
void	close(WorkingSet context) Closes and releases a context.
WorkingSet	createWS(java.lang.Object userObject) creates a working set
WorkingSet	createWS(java.lang.Object userObject, java.lang.Object workingSetType) creates a working set
boolean	evict(WorkingSet context, java.lang.Object oid, boolean force) This methods permits to force the cache eviction of a persistent object designed by its identifier.
int	evictAll(WorkingSet context, boolean force) This methods permits to try the cache eviction of all persistent object
State	export(WorkingSet context, java.lang.Object obj) Given an object, this method creates the corresponding copy in permanent support.
State	export(WorkingSet context, java.lang.Object obj, java.lang.Object hints) This method permits to given some information to build the identifier of the new persistent object.
void	flush(WorkingSet context, State state) This method permits to flush entries associated to a context.
void	flush(WorkingSet context, StateFilter statefilter) This method permits to flush entries associated to a context.
CacheEntry	getObjectById(WorkingSet context, java.lang.Object oid) This method retrieves a CacheEntry without checking if the persistent object, exists.
State	readIntention(WorkingSet context, java.lang.Object oid, java.lang.Object thinLock) This method records an access intention to a data object in read mode.
void	refresh(WorkingSet ws, java.lang.Object oid) Forget modifications of a dirty persistent object.
void	unbind(WorkingSet ws, java.lang.Object oid) Detach a persistent object from the persistent support.
State	unexport(WorkingSet context, java.lang.Object oid) Deletes the binding between an in main-memory object, and its corresponding copy in permanent support.
State	writeIntention(WorkingSet context, java.lang.Object oid, java.lang.Object thinLock) This method records an access intention to a data object in write mode.

Method Detail

export

public State export(WorkingSet context,
                    java.lang.Object obj)
             throws PersistenceException

Given an object, this method creates the corresponding copy in permanent support. At the same time, it establishes a binding between the object in main-memory and the permanent copy. Roughly, the internal tasks include: - Reserving space on permanent support, - Establishing a binding between the object in main memory and the permanent copy, - Marking the object as dirty, (internal or by the concurrency control module?) - Adding the object to the cache

Parameters:

context - is an identifier of the execution context. It can be a transaction handle.

obj - The object whose state is to be copied to

Returns:

the state associated to the working set

Throws:

PersistenceException - Whenever the object is invalid (e.g. NULL) or it has been previously bound to another oid.

export

public State export(WorkingSet context,
                    java.lang.Object obj,
                    java.lang.Object hints)
             throws PersistenceException

This method permits to given some information to build the identifier of the new persistent object.

Parameters:

context - is an identifier of the execution context. It can be a transaction handle.

obj - The object whose state is to be copied to

hints - can be used to build the identifier of the object.

Returns:

the state associated to the working set

Throws:

PersistenceException - Whenever the object is invalid (e.g. NULL) or it has been previously bound to another oid.

unexport

public State unexport(WorkingSet context,
                      java.lang.Object oid)
               throws PersistenceException

Deletes the binding between an in main-memory object, and its corresponding copy in permanent support. At the same time, it frees (may be) the space in the permanent support allocated to the permanent copy.

Parameters:

context - is an identifier of the execution context. It can be a transaction handle.

oid - The identifier of the corresponding object to be destroyed.

Returns:

the state associated to the working set

Throws:

PersistenceException

getObjectById

public CacheEntry getObjectById(WorkingSet context,
                                java.lang.Object oid)
                         throws PersistenceException

This method retrieves a CacheEntry without checking if the persistent object, exists. If the entry is already in the working or in the cache, the found entry is returned. Otherwise a new CacheEntry is returned. This method does not permit an access to persistent data, because no intention has been declared. Then a call to readIntention or writeIntention is required.

Parameters:

context - is an identifier of the execution context. It can be a transaction handle.

oid - The identifier of the corresponding object to find

Throws:

PersistenceException

readIntention

public State readIntention(WorkingSet context,
                           java.lang.Object oid,
                           java.lang.Object thinLock)
                    throws PersistenceException

This method records an access intention to a data object in read mode.

Parameters:

context - is an identifier of the execution context. It can be a transaction handle.

oid - is the object identifier.

Returns:

the state associated to the working set

Throws:

PersistenceException

writeIntention

public State writeIntention(WorkingSet context,
                            java.lang.Object oid,
                            java.lang.Object thinLock)
                     throws PersistenceException

This method records an access intention to a data object in write mode.

Parameters:

context - is an identifier of the execution context. It can be a transaction handle.

oid - is the object identifier.

Returns:

the state associated to the working set

Throws:

PersistenceException

accessCompletion

public void accessCompletion(WorkingSet context,
                             State ce)
                      throws PersistenceException

This method can be used to mark the end of an access to a data object.

Parameters:

context - is an identifier of the execution context. It can be a transaction handle.

ce - is the cache entry on which the access is finished.

Throws:

PersistenceException

flush

public void flush(WorkingSet context,
                  StateFilter statefilter)
           throws PersistenceException

This method permits to flush entries associated to a context.

Parameters:

context - is an identifier of the execution context. It can be a transaction handle.

statefilter - is a filter of the cache entry which must be flushed. A null StateFilter means all entries associated to the context has to be flushed.

Throws:

PersistenceException - if the context is not valid.

flush

public void flush(WorkingSet context,
                  State state)
           throws PersistenceException

This method permits to flush entries associated to a context.

Parameters:

context - is an identifier of the execution context. It can be a transaction handle.

state - is the state taht must be flushed

Throws:

PersistenceException - if the context is not valid.

evict

public boolean evict(WorkingSet context,
                     java.lang.Object oid,
                     boolean force)
              throws PersistenceException

This methods permits to force the cache eviction of a persistent object designed by its identifier.

Parameters:

context - is the working set asking the eviction.

oid - is the identifier of the persistent object to evict from the cache

force - indicates if the entry MUST be evicted (true) or TRIES to be evicted (false).

Returns:

true if the entry has been evicted from the cache, otherwise false

Throws:

PersistenceException - if the instance is dirty or used by other working set.

evictAll

public int evictAll(WorkingSet context,
                    boolean force)
             throws PersistenceException

This methods permits to try the cache eviction of all persistent object

Returns:

the number of entry staying in the cache (not evicted)

Throws:

PersistenceException

unbind

public void unbind(WorkingSet ws,
                   java.lang.Object oid)
            throws PersistenceException

Detach a persistent object from the persistent support. After calling this method the persistent object is no more associated to the context and this instance is no more in the cache. If the persistent object has been modified, it is flushed. Be carefull the lock for the concurrency (read | write) is kept until the end of the context.

Parameters:

ws - is the current working set

oid - is the identifier of the persistent object

Throws:

PersistenceException

refresh

public void refresh(WorkingSet ws,
                    java.lang.Object oid)
             throws PersistenceException

Forget modifications of a dirty persistent object. The state is re-read from the cache or later from the database. Be carefull the lock for the concurrency (read | write) is kept until the end of the context.

Parameters:

ws - is the current working set

oid - is the identifier of the persistent object

Throws:

PersistenceException

createWS

public WorkingSet createWS(java.lang.Object userObject)
                    throws PersistenceException

creates a working set

Parameters:

userObject - can be an external user depending on the personnality.

Returns:

a new WorkingSet

Throws:

PersistenceException

createWS

public WorkingSet createWS(java.lang.Object userObject,
                           java.lang.Object workingSetType)
                    throws PersistenceException

creates a working set

Parameters:

userObject - can be an external user depending on the personnality.

workingSetType - is a type of the working set.

Returns:

a new WorkingSet

Throws:

PersistenceException

close

public void close(WorkingSet context)
           throws PersistenceException

Closes and releases a context.

Parameters:

context - which must be closed

Throws:

PersistenceException - if the context is a transactional context which has not been commited or aborted.