org.apache.manifoldcf.core.cachemanager
Class CacheManager

java.lang.Object
  org.apache.manifoldcf.core.cachemanager.CacheManager

All Implemented Interfaces:

ICacheManager

public class CacheManager
extends java.lang.Object
implements ICacheManager

This class implements the cache manager interface, and provides generic cache management services. See the interface for a description of how the services work. However, since this service requires the lock manager, and there is one lock manager per thread, there will be one of these service instances per thread as well.

Nested Class Summary

protected class	CacheManager.CacheCreateHandle This is the local implementation of ICacheCreateHandle
protected class	CacheManager.CacheHandle This is the local implementation of ICacheHandle.
protected class	CacheManager.CacheTransactionHandle This is the class the cache manager uses to keep track of transaction relationships and data.

Field Summary

static java.lang.String	_rcsid
protected static GeneralCache	cache
protected static java.lang.String	cacheLockPrefix
protected ILockManager	lockManager
protected java.util.HashMap	transactionHash

Constructor Summary

CacheManager(IThreadContext context)

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.
protected boolean	hasExpired(java.lang.String key, long createTime) Check if object has expired (by looking at file system).
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.
protected void	performInvalidation(StringSet keys) Perform an invalidation.
protected long	readSharedData(java.lang.String key) Read an invalidation file contents.
protected void	resetObjectExpiration(ICacheDescription objectDescription, long currentTime) Set object's expiration and LRU.
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.
protected void	writeSharedData(java.lang.String key, long value) Write the invalidation file contents.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_rcsid

public static final java.lang.String _rcsid

See Also:

Constant Field Values

cacheLockPrefix

protected static final java.lang.String cacheLockPrefix

See Also:

Constant Field Values

lockManager

protected ILockManager lockManager

cache

protected static GeneralCache cache

transactionHash

protected java.util.HashMap transactionHash

Constructor Detail

CacheManager

public CacheManager(IThreadContext context)
             throws ManifoldCFException

Throws:

ManifoldCFException

Method Detail

findObjectsAndExecute

public 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 the same object in both the locate set and the invalidate 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.

Specified by:

findObjectsAndExecute in interface ICacheManager

Parameters:

locateObjectDescriptions - is a set of description objects that uniquely describe the objects needed.

invalidateKeys - is the set of keys to invalidate at the end of the execution.

execObject - is the cache execution object whose create() or execute() methods will be called.

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

public 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.

Specified by:

enterCache in interface ICacheManager

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

public 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.

Specified by:

enterCreateSection in interface ICacheManager

Parameters:

handle - is the cache handle.

Throws:

ManifoldCFException

lookupObject

public 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.

Specified by:

lookupObject in interface ICacheManager

Parameters:

handle - is the handle to use for the create.

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

Returns:

the object, or null if not found.

Throws:

ManifoldCFException

hasExpired

protected boolean hasExpired(java.lang.String key,
                             long createTime)
                      throws ManifoldCFException

Check if object has expired (by looking at file system).

Parameters:

key - is the invalidation key.

createTime - is the creation time.

Returns:

true if expired, false otherwise.

Throws:

ManifoldCFException

resetObjectExpiration

protected void resetObjectExpiration(ICacheDescription objectDescription,
                                     long currentTime)

Set object's expiration and LRU.

Parameters:

objectDescription - is the description object.

currentTime - is the current time in milliseconds since epoch.

saveObject

public 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.

Specified by:

saveObject in interface ICacheManager

Parameters:

handle - is the create handle.

objectDescription - is the object description.

object - is the object.

Throws:

ManifoldCFException

leaveCreateSection

public void leaveCreateSection(ICacheCreateHandle handle)
                        throws ManifoldCFException

Leave the create section.

Specified by:

leaveCreateSection in interface ICacheManager

Parameters:

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

Throws:

ManifoldCFException

invalidateKeys

public void invalidateKeys(ICacheHandle handle)
                    throws ManifoldCFException

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

Specified by:

invalidateKeys in interface ICacheManager

Parameters:

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

Throws:

ManifoldCFException

performInvalidation

protected void performInvalidation(StringSet keys)
                            throws ManifoldCFException

Perform an invalidation. Assume all appropriate locks are in place.

Parameters:

keys - is the set of keys to invalidate.

Throws:

ManifoldCFException

leaveCache

public void leaveCache(ICacheHandle handle)
                throws ManifoldCFException

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

Specified by:

leaveCache in interface ICacheManager

Parameters:

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

Throws:

ManifoldCFException

startTransaction

public 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.

Specified by:

startTransaction in interface ICacheManager

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

public 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.

Specified by:

commitTransaction in interface ICacheManager

Parameters:

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

Throws:

ManifoldCFException

rollbackTransaction

public 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.

Specified by:

rollbackTransaction in interface ICacheManager

Parameters:

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

Throws:

ManifoldCFException

expireObjects

public void expireObjects(long currentTimestamp)
                   throws ManifoldCFException

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

Specified by:

expireObjects in interface ICacheManager

Parameters:

currentTimestamp - is the current time in milliseconds since epoch.

Throws:

ManifoldCFException

readSharedData

protected long readSharedData(java.lang.String key)
                       throws ManifoldCFException

Read an invalidation file contents.

Parameters:

key - is the cache key name.

Returns:

the invalidation time, or 0 if none.

Throws:

ManifoldCFException

writeSharedData

protected void writeSharedData(java.lang.String key,
                               long value)
                        throws ManifoldCFException

Write the invalidation file contents.

Parameters:

key - is the cache key name.

value - is the invalidation timestamp.

Throws:

ManifoldCFException