org.apache.manifoldcf.core.interfaces
Interface ICacheManager

All Known Implementing Classes:

CacheManager

public interface ICacheManager

This interface describes the functionality in the cache manager. It is not meant to have multiple implementations, but merely to provide general abstract cross-cluster cache management services.

Field Summary

static java.lang.String

_rcsid

Method Summary

void	commitTransaction(java.lang.String transactionID) Commit a cache transaction.
ICacheHandle	enterCache(ICacheDescription[] locateObjectDescriptions, StringSet invalidateKeys, java.lang.String transactionID) Second way of doing cache management.
ICacheCreateHandle	enterCreateSection(ICacheHandle handle) Enter a creation critical section.
void	expireObjects(long currentTimestamp) Timed invalidation.
void	findObjectsAndExecute(ICacheDescription[] locateObjectDescriptions, StringSet invalidateKeys, ICacheExecutor execObject, java.lang.String transactionID) Locate or create a set of objects in the cached object pool, and/or destroy and invalidate the same or other objects.
void	invalidateKeys(ICacheHandle handle) Invalidate keys.
void	leaveCache(ICacheHandle handle) Leave the cache.
void	leaveCreateSection(ICacheCreateHandle handle) Leave the create section.
java.lang.Object	lookupObject(ICacheCreateHandle handle, ICacheDescription objectDescription) Lookup an object.
void	rollbackTransaction(java.lang.String transactionID) Roll back a cache transaction.
void	saveObject(ICacheCreateHandle handle, ICacheDescription objectDescription, java.lang.Object object) Save a newly created object.
void	startTransaction(java.lang.String startingTransactionID, java.lang.String enclosingTransactionID) Begin a cache transaction.

Field Detail

_rcsid

static final java.lang.String _rcsid

See Also:

Constant Field Values

Method Detail

findObjectsAndExecute

void findObjectsAndExecute(ICacheDescription[] locateObjectDescriptions,
                           StringSet invalidateKeys,
                           ICacheExecutor execObject,
                           java.lang.String transactionID)
                           throws ManifoldCFException

Locate or create a set of objects in the cached object pool, and/or destroy and invalidate the same or other objects. For each "locate" object described below, one of two things will happen: the execObject's exists() method will be called (if the object exists in the cache already), or the execObject's create*() family of methods will be called. When all objects have been declared to the execObject, finally the execute() method will be called. In both cases, all objects are considered to be locked, and cannot be invalidated until the lock is cleared (after the end of the called method). For the invalidation descriptions, the execObject's destroy() method will be called instead. The object will be invalidated from the cache at the end of the findObjectsAndExecute() operation. It is perfectly legal to include an object that will be invalidated in the locate set! If an error occurs during object creation, the execute() method will NOT be called. If the execute() method has an error, the objects that were created will still be recorded in the cache.

Parameters:

locateObjectDescriptions - is a set of description objects that uniquely describe the objects needed. May be null if no objects are desired.

invalidateKeys - are the keys to invalidate after successful execution. May be null.

execObject - is the cache execution object whose create() or execute() methods will be called. May be null if no in-section logic is desired, and no objects are specified.

transactionID - is the current transaction identifier, or null. Objects created within this call will be associated with this transaction; they will be purged from the cache should the transaction be rolled back.

Throws:

ManifoldCFException

enterCache

ICacheHandle enterCache(ICacheDescription[] locateObjectDescriptions,
                        StringSet invalidateKeys,
                        java.lang.String transactionID)
                        throws ManifoldCFException

Second way of doing cache management. Basically, this approach breaks the findObjectsAndExecute() method down into bite-sized chunks. The goal is additional flexibility, and an executor object does not need to be defined. Pretty much everything else is identical. The objects returned by the manager methods provide context control and enforce the proper ordering and nesting. This method enters the cacher and builds a cache handle. Once a cache handle is returned, the calling code MUST, under all circumstances, leave the cache using the same handle.

Parameters:

locateObjectDescriptions - is a set of description objects that uniquely describe the objects needed. May be null if no objects are desired.

invalidateKeys - are the keys to invalidate after successful execution. May be null.

transactionID - is the current transaction identifier, or null. Objects created within this block will be associated with this transaction; they will be purged from the cache should the transaction be rolled back.

Returns:

a cache handle.

Throws:

ManifoldCFException

enterCreateSection

ICacheCreateHandle enterCreateSection(ICacheHandle handle)
                                      throws ManifoldCFException

Enter a creation critical section. This insures that only one thread is creating the specified objects at a time. This MUST be paired with a leaveCreateSection() method call, whatever happens.

Parameters:

handle - is the cache handle.

Throws:

ManifoldCFException

lookupObject

java.lang.Object lookupObject(ICacheCreateHandle handle,
                              ICacheDescription objectDescription)
                              throws ManifoldCFException

Lookup an object. Returns null if object not found. If it is found, object's LRU and expiration info are updated. The objectDescription passed MUST be one of the ones specified in the enclosing enterCache() method.

Parameters:

handle - is the handle to use for the create.

objectDescription - is the description of the object to look up.

Throws:

ManifoldCFException

saveObject

void saveObject(ICacheCreateHandle handle,
                ICacheDescription objectDescription,
                java.lang.Object object)
                throws ManifoldCFException

Save a newly created object. The object MUST be one of those identified in the enterCache() method.

Parameters:

handle - is the create handle.

objectDescription - is the object description.

object - is the object.

Throws:

ManifoldCFException

leaveCreateSection

void leaveCreateSection(ICacheCreateHandle handle)
                        throws ManifoldCFException

Leave the create section.

Parameters:

handle - is the handle created by the corresponding enterCreateSection() method.

Throws:

ManifoldCFException

invalidateKeys

void invalidateKeys(ICacheHandle handle)
                    throws ManifoldCFException

Invalidate keys. The keys invalidated are what got passed to the enterCache() method.

Parameters:

handle - is the cache handle. Does nothing if a null set of keys was passed in.

Throws:

ManifoldCFException

leaveCache

void leaveCache(ICacheHandle handle)
                throws ManifoldCFException

Leave the cache. Must be paired with enterCache, above.

Parameters:

handle - is the handle of the cache we are leaving.

Throws:

ManifoldCFException

startTransaction

void startTransaction(java.lang.String startingTransactionID,
                      java.lang.String enclosingTransactionID)
                      throws ManifoldCFException

Begin a cache transaction. This keeps track of the relationship between objects cached within transactions.

Parameters:

startingTransactionID - is the id of the transaction that is starting.

enclosingTransactionID - is the id of the transaction that is in effect, or null.

Throws:

ManifoldCFException

commitTransaction

void commitTransaction(java.lang.String transactionID)
                       throws ManifoldCFException

Commit a cache transaction. This method MUST be called when a transaction successfully ends, or open locks will not be closed!!! All cache activity that has taken place inside the transaction will be resolved, and the cache locks held open will be released.

Parameters:

transactionID - is the id of the transaction that is ending.

Throws:

ManifoldCFException

rollbackTransaction

void rollbackTransaction(java.lang.String transactionID)
                         throws ManifoldCFException

Roll back a cache transaction. This method releases all objects cached against the ending transaction ID, and releases all locks held for the transaction.

Parameters:

transactionID - is the id of the transaction that is ending.

Throws:

ManifoldCFException

expireObjects

void expireObjects(long currentTimestamp)
                   throws ManifoldCFException

Timed invalidation. Call this periodically to get rid of all objects that have expired.

Parameters:

currentTimestamp - is the current time in milliseconds since epoch.

Throws:

ManifoldCFException