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.


Copyright © 2000-2002 France Telecom S.A., INRIA, IMAG-LSR All Rights Reserved.