Class FarragoObjectCache

  extended by net.sf.farrago.util.FarragoObjectCache
All Implemented Interfaces:
FarragoAllocation, ClosableAllocation

public class FarragoObjectCache
extends Object
implements FarragoAllocation

FarragoObjectCache implements generic object caching. It doesn't use SoftReferences since those don't provide enough programmatic control over memory-sensitive caching policies.

Key objects must implement hashCode/equals properly since FarragoObjectCache is based on a HashMap internally.

See FarragoObjectCacheTest for examples of usage patterns.

Note that closeAllocation() should only be called with no entries pinned, no calls in progress, and no further calls planned.

$Id: //open/dev/farrago/src/net/sf/farrago/util/ $
John V. Sichi

Nested Class Summary
static interface FarragoObjectCache.CachedObjectFactory
          Factory interface for producing cached objects.
static interface FarragoObjectCache.Entry
          Interface for a cache entry; same as Map.Entry except that there is no requirement on equals/hashCode.
static interface FarragoObjectCache.UninitializedEntry
          Callback interface for entry initialization.
Field Summary
private  long bytesMax
private  long bytesUsed
          Number of bytes currently in use by cached objects.
protected  MultiMap<Object,FarragoCacheEntry> mapKeyToEntry
          Map from cache key to EntryImpl.
private static Logger tracer
private  FarragoCacheVictimPolicy victimPolicy
          Victimization policy for this cache
Constructor Summary
FarragoObjectCache(FarragoAllocationOwner owner, long bytesMax, FarragoCacheVictimPolicy victimPolicy)
          Creates an empty cache.
Method Summary
private  void adjustMemoryUsage(long incBytes)
 void closeAllocation()
          Closes this object.
 void discard(Object key)
          Discards any entries associated with a key.
 void discardAll()
          Discards all entries.
private  void discardEntry(FarragoCacheEntry entry)
private  FarragoCacheEntry findOrCreateEntry(Thread currentThread, Object key, FarragoObjectCache.CachedObjectFactory factory, boolean exclusive)
 long getBytesCached()
 long getBytesMax()
 FarragoObjectCache.Entry pin(Object key, FarragoObjectCache.CachedObjectFactory factory, boolean exclusive)
          Pins an entry in the cache.
 void setMaxBytes(long bytesMaxNew)
          Changes the cache size limit, discarding entries if necessary.
private  FarragoObjectCache.Entry tryPin(Object key, FarragoObjectCache.CachedObjectFactory factory, boolean exclusive)
 void tryUnpin(String key)
          Just like unpin except that it takes only the key to the cache entry and doesn't call adjustMemoryUsage.
 void unpin(FarragoObjectCache.Entry pinnedEntry)
          Unpins an entry returned by pin.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail


private static final Logger tracer


protected MultiMap<Object,FarragoCacheEntry> mapKeyToEntry
Map from cache key to EntryImpl. To avoid deadlock, synchronize on either map or entry but not both at once. See code comments in tryPin for more info on this.


private long bytesMax


private long bytesUsed
Number of bytes currently in use by cached objects. This and bytesMax are synchronized via mapKeyToEntry monitor.


private FarragoCacheVictimPolicy victimPolicy
Victimization policy for this cache

Constructor Detail


public FarragoObjectCache(FarragoAllocationOwner owner,
                          long bytesMax,
                          FarragoCacheVictimPolicy victimPolicy)
Creates an empty cache.

owner - FarragoAllocationOwner for this cache, to make sure everything gets discarded eventually
bytesMax - maximum number of bytes to cache
victimPolicy - victimization policy to use when the cache is full
Method Detail


public FarragoObjectCache.Entry pin(Object key,
                                    FarragoObjectCache.CachedObjectFactory factory,
                                    boolean exclusive)
Pins an entry in the cache. When the caller is done with it, the returned entry must be unpinned, otherwise the entry can never be discarded from the cache.

Note that for a cache miss with exclusive=false, other callers requesting to pin the same key near-simultaneously will wait for the initialization of the new object to complete. If it completes successfully, AND it is initialized as reusable, then the new object will be shared. If it completes unsuccessfully, the first caller will receive the thrown exception, and subsequent callers will retry the attempt themselves. If it completes successfully, but turns out to be non-reusable, then subsequent callers will give up on it and create their own private copies instead.

key - key of the entry to pin
factory - CachedObjectFactory to call if an existing entry can't be used (cache miss), in which case a new entry will be created and initialized by calling the factory's initializeEntry method
exclusive - if true, only reuse unpinned entries; note that this flag is not remembered along with the entry, so callers must be consistent in setting this flag for objects in the same keyspace
pinned entry


private FarragoObjectCache.Entry tryPin(Object key,
                                        FarragoObjectCache.CachedObjectFactory factory,
                                        boolean exclusive)


private FarragoCacheEntry findOrCreateEntry(Thread currentThread,
                                            Object key,
                                            FarragoObjectCache.CachedObjectFactory factory,
                                            boolean exclusive)


private void adjustMemoryUsage(long incBytes)


public void setMaxBytes(long bytesMaxNew)
Changes the cache size limit, discarding entries if necessary.

bytesMaxNew - new limit


public long getBytesMax()
cache size limit


public long getBytesCached()
current number of bytes cached (regardless of whether they are pinned or not)


public void unpin(FarragoObjectCache.Entry pinnedEntry)
Unpins an entry returned by pin. After unpin, the caller should immediately nullify its reference to the entry, its key, its value, and any sub-objects so that they can be garbage collected.

pinnedEntry - pinned Entry


public void tryUnpin(String key)
Just like unpin except that it takes only the key to the cache entry and doesn't call adjustMemoryUsage. It is used just like unpin but it is a bit more forgiving and calls closeAllocation on the cache entry if it is truely unpinned. It is currently used only by a specific extention to Farrago and not Farrago itself.

key - the key to the pinned Entry


public void discard(Object key)
Discards any entries associated with a key. If the bound value of an entry is a ClosableObject, it will be closed.

REVIEW jvs 10-Jun-2007: This method is unsafe since the associated entries may still be pinned. Code which is relying on it (such as FarragoDataWrapperCache) should probably be changed to use either a staleness test or a different key scheme.

key - key of the Entry to discard


public void discardAll()
Discards all entries. May only be called at a time when no entries are currently pinned (otherwise assertion failures may result).


private void discardEntry(FarragoCacheEntry entry)


public void closeAllocation()
Description copied from interface: ClosableAllocation
Closes this object.

Specified by:
closeAllocation in interface ClosableAllocation