org.objectweb.perseus.persistence.api

Interface PersistenceManager

Known Subinterfaces:
TransactionalPersistenceManager
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(Object userObject)
creates a working set
WorkingSet
createWS(Object userObject, Object workingSetType)
creates a working set
boolean
evict(WorkingSet context, 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, Object obj)
Given an object, this method creates the corresponding copy in permanent support.
State
export(WorkingSet context, Object obj, 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.
State
readIntention(WorkingSet context, CacheEntry ce)
This method records an access intention to a data object in read mode.
State
readIntention(WorkingSet context, Object oid)
This method records an access intention to a data object in read mode.
void
refresh(WorkingSet ws, CacheEntry ce)
Forget modifications of a dirty persistent object.
void
refresh(WorkingSet ws, Object oid)
Forget modifications of a dirty persistent object.
void
unbind(WorkingSet ws, CacheEntry ce)
Detach a persistent object from the persistent support.
void
unbind(WorkingSet ws, Object oid)
Detach a persistent object from the persistent support.
State
unexport(WorkingSet context, CacheEntry ce)
Deletes the binding between an in main-memory object, and its corresponding copy in permanent support.
State
unexport(WorkingSet context, Object oid)
Deletes the binding between an in main-memory object, and its corresponding copy in permanent support.
State
writeIntention(WorkingSet context, CacheEntry ce)
This method records an access intention to a data object in write mode.
State
writeIntention(WorkingSet context, Object oid)
This method records an access intention to a data object in write mode.

Method Details

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 -


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.


createWS

public WorkingSet createWS(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(Object userObject,
                           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 -


evict

public boolean evict(WorkingSet context,
                     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)


export

public State export(WorkingSet context,
                    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

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,
                    Object obj,
                    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.


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.


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

Throws:
PersistenceException - if the context is not valid.


readIntention

public State readIntention(WorkingSet context,
                           CacheEntry ce)
            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.
ce - is the cache entry.

Throws:
PersistenceException -


readIntention

public State readIntention(WorkingSet context,
                           Object oid)
            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.

Throws:
PersistenceException -


refresh

public void refresh(WorkingSet ws,
                    CacheEntry ce)
            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
ce - is the cache entry of the persistent object

Throws:
PersistenceException -


refresh

public void refresh(WorkingSet ws,
                    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 -


unbind

public void unbind(WorkingSet ws,
                   CacheEntry ce)
            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
ce - is the cache entry of the persistent object

Throws:
PersistenceException -


unbind

public void unbind(WorkingSet ws,
                   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 -


unexport

public State unexport(WorkingSet context,
                      CacheEntry ce)
            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.
ce - The identifier of the corresponding object to be destroyed.

Throws:
PersistenceException -


unexport

public State unexport(WorkingSet context,
                      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.

Throws:
PersistenceException -


writeIntention

public State writeIntention(WorkingSet context,
                            CacheEntry ce)
            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.
ce - is the cache entry.

Throws:
PersistenceException -


writeIntention

public State writeIntention(WorkingSet context,
                            Object oid)
            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.

Throws:
PersistenceException -


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