org.apache.derby.impl.services.cache
Class ConcurrentCache

java.lang.Object
  extended by org.apache.derby.impl.services.cache.ConcurrentCache
All Implemented Interfaces:
CacheManager

final class ConcurrentCache
extends java.lang.Object
implements CacheManager

A cache manager based on the utilities found in the java.util.concurrent package. It allows multiple threads to access the cache concurrently without blocking each other, given that they request different objects and the requested objects are present in the cache.

All methods of this class should be thread safe. When exclusive access to an entry is required, it is achieved by calling the lock() method on the CacheEntry object. To ensure that the entry is always unlocked, all calls to CacheEntry.lock() should be followed by a try block with a finally clause that unlocks the entry.


Field Summary
private  java.util.concurrent.ConcurrentHashMap<java.lang.Object,CacheEntry> cache
          Map with all the cached objects.
private  BackgroundCleaner cleaner
          Background cleaner which can be used to clean cached objects in a separate thread to avoid blocking the user threads.
private  CacheableFactory holderFactory
          Factory which creates Cacheables.
private  int maxSize
          The maximum size (number of elements) for this cache.
private  java.lang.String name
          Name of this cache.
private  ReplacementPolicy replacementPolicy
          Replacement policy to be used for this cache.
private  boolean stopped
          Flag that indicates whether this cache instance has been shut down.
 
Constructor Summary
ConcurrentCache(CacheableFactory holderFactory, java.lang.String name, int initialSize, int maxSize)
          Creates a new cache manager.
 
Method Summary
 void ageOut()
          Remove all objects that are not kept and not dirty.
 void clean(Matchable partialKey)
          Clean all dirty objects matching a partial key.
 void cleanAll()
          Clean all dirty objects in the cache.
(package private)  void cleanAndUnkeepEntry(CacheEntry entry, Cacheable item)
          Clean an entry in the cache and decrement its keep count.
private  void cleanCache(Matchable partialKey)
          Clean all dirty objects matching a partial key.
(package private)  void cleanEntry(CacheEntry entry)
          Clean an entry in the cache.
 Cacheable create(java.lang.Object key, java.lang.Object createParameter)
          Create an object in the cache.
 boolean discard(Matchable partialKey)
          Discard all unused objects that match a partial key.
(package private)  void evictEntry(java.lang.Object key)
          Evict an entry to make room for a new entry that is being inserted into the cache.
 Cacheable find(java.lang.Object key)
          Find an object in the cache.
 Cacheable findCached(java.lang.Object key)
          Find an object in the cache.
(package private)  BackgroundCleaner getBackgroundCleaner()
           
private  CacheEntry getEntry(java.lang.Object key)
          Get the entry associated with the specified key from the cache.
(package private)  ReplacementPolicy getReplacementPolicy()
          Return the ReplacementPolicy instance for this cache.
private  Cacheable insertIntoFreeSlot(java.lang.Object key, CacheEntry entry)
          Insert a CacheEntry into a free slot in the ReplacementPolicy's internal data structure, and return a Cacheable that the caller can reuse.
 void release(Cacheable item)
          Release an object that has been fetched from the cache with find(), findCached() or create().
 void remove(Cacheable item)
          Remove an object from the cache.
private  void removeEntry(java.lang.Object key)
          Remove an entry from the cache.
private  void settingIdentityComplete(java.lang.Object key, CacheEntry entry, Cacheable item)
          Complete the setting of the identity.
 void shutdown()
          Shut down the cache.
 void useDaemonService(DaemonService daemon)
          Specify a daemon service that can be used to perform operations in the background.
 java.util.Collection<Cacheable> values()
          Return a collection view of all the Cacheables in the cache.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

cache

private final java.util.concurrent.ConcurrentHashMap<java.lang.Object,CacheEntry> cache
Map with all the cached objects.


holderFactory

private final CacheableFactory holderFactory
Factory which creates Cacheables.


name

private final java.lang.String name
Name of this cache.


maxSize

private final int maxSize
The maximum size (number of elements) for this cache.


replacementPolicy

private final ReplacementPolicy replacementPolicy
Replacement policy to be used for this cache.


stopped

private volatile boolean stopped
Flag that indicates whether this cache instance has been shut down. When it has been stopped, find(), findCached() and create() will return null. The flag is declared volatile so that no synchronization is needed when it is accessed by concurrent threads.


cleaner

private BackgroundCleaner cleaner
Background cleaner which can be used to clean cached objects in a separate thread to avoid blocking the user threads.

Constructor Detail

ConcurrentCache

ConcurrentCache(CacheableFactory holderFactory,
                java.lang.String name,
                int initialSize,
                int maxSize)
Creates a new cache manager.

Parameters:
holderFactory - factory which creates Cacheables
name - the name of the cache
initialSize - the initial capacity of the cache
maxSize - maximum number of elements in the cache
Method Detail

getReplacementPolicy

ReplacementPolicy getReplacementPolicy()
Return the ReplacementPolicy instance for this cache.

Returns:
replacement policy

getEntry

private CacheEntry getEntry(java.lang.Object key)
Get the entry associated with the specified key from the cache. If the entry does not exist, insert an empty one and return it. The returned entry is always locked for exclusive access by the current thread, but not kept. If another thread is currently setting the identity of this entry, this method will block until the identity has been set.

Parameters:
key - the identity of the cached object
Returns:
an entry for the specified key, always locked

removeEntry

private void removeEntry(java.lang.Object key)
Remove an entry from the cache. Its Cacheable is cleared and made available for other entries. This method should only be called if the entry is present in the cache and locked by the current thread.

Parameters:
key - the identity of the entry to remove

evictEntry

void evictEntry(java.lang.Object key)
Evict an entry to make room for a new entry that is being inserted into the cache. Clear the identity of its Cacheable and set it to null. When this method is called, the caller has already chosen the Cacheable for reuse. Therefore, this method won't call CacheEntry.free() as that would make the Cacheable free for reuse by other entries as well.

The caller must have locked the entry that is about to be evicted.

Parameters:
key - identity of the entry to remove

insertIntoFreeSlot

private Cacheable insertIntoFreeSlot(java.lang.Object key,
                                     CacheEntry entry)
                              throws StandardException
Insert a CacheEntry into a free slot in the ReplacementPolicy's internal data structure, and return a Cacheable that the caller can reuse. The entry must have been locked before this method is called.

Parameters:
key - the identity of the object being inserted
entry - the entry that is being inserted
Returns:
a Cacheable object that the caller can reuse
Throws:
StandardException - if an error occurs while inserting the entry or while allocating a new Cacheable

settingIdentityComplete

private void settingIdentityComplete(java.lang.Object key,
                                     CacheEntry entry,
                                     Cacheable item)
Complete the setting of the identity. This includes notifying the threads that are waiting for the setting of the identity to complete, so that they can wake up and continue. If setting the identity failed, the entry will be removed from the cache.

Parameters:
key - the identity of the object being inserted
entry - the entry which is going to hold the cached object
item - a Cacheable object with the identity set (if the identity was successfully set), or null if setting the identity failed

find

public Cacheable find(java.lang.Object key)
               throws StandardException
Find an object in the cache. If it is not present, add it to the cache. The returned object is kept until release() is called.

Specified by:
find in interface CacheManager
Parameters:
key - identity of the object to find
Returns:
the cached object, or null if it cannot be found
Throws:
StandardException - Standard Derby error policy.
See Also:
Cacheable.setIdentity(java.lang.Object)

findCached

public Cacheable findCached(java.lang.Object key)
                     throws StandardException
Find an object in the cache. If it is not present, return null. The returned object is kept until release() is called.

Specified by:
findCached in interface CacheManager
Parameters:
key - identity of the object to find
Returns:
the cached object, or null if it's not in the cache
Throws:
StandardException - Standard Derby error policy.

create

public Cacheable create(java.lang.Object key,
                        java.lang.Object createParameter)
                 throws StandardException
Create an object in the cache. The object is kept until release() is called.

Specified by:
create in interface CacheManager
Parameters:
key - identity of the object to create
createParameter - parameters passed to Cacheable.createIdentity()
Returns:
a reference to the cached object, or null if the object cannot be created
Throws:
StandardException - if the object is already in the cache, or if some other error occurs
See Also:
Cacheable.createIdentity(Object,Object)

release

public void release(Cacheable item)
Release an object that has been fetched from the cache with find(), findCached() or create().

Specified by:
release in interface CacheManager
Parameters:
item - a Cacheable value

remove

public void remove(Cacheable item)
            throws StandardException
Remove an object from the cache. The object must previously have been fetched from the cache with find(), findCached() or create(). The user of the cache must make sure that only one caller executes this method on a cached object. This method will wait until the object has been removed (its keep count must drop to zero before it can be removed).

Specified by:
remove in interface CacheManager
Parameters:
item - the object to remove from the cache
Throws:
StandardException - Standard Derby error policy.

cleanAll

public void cleanAll()
              throws StandardException
Clean all dirty objects in the cache. All objects that existed in the cache at the time of the call will be cleaned. Objects added later may or may not be cleaned.

Specified by:
cleanAll in interface CacheManager
Throws:
StandardException - Standard Derby error policy.
See Also:
Cacheable.clean(boolean), Cacheable.isDirty()

clean

public void clean(Matchable partialKey)
           throws StandardException
Clean all dirty objects matching a partial key.

Specified by:
clean in interface CacheManager
Parameters:
partialKey - the partial (or exact) key to match
Throws:
StandardException - Standard Derby error policy.

cleanCache

private void cleanCache(Matchable partialKey)
                 throws StandardException
Clean all dirty objects matching a partial key. If no key is specified, clean all dirty objects in the cache.

Parameters:
partialKey - the partial (or exact) key to match, or null to match all keys
Throws:
StandardException

cleanEntry

void cleanEntry(CacheEntry entry)
          throws StandardException
Clean an entry in the cache.

Parameters:
entry - the entry to clean
Throws:
StandardException - if an error occurs while cleaning

cleanAndUnkeepEntry

void cleanAndUnkeepEntry(CacheEntry entry,
                         Cacheable item)
                   throws StandardException
Clean an entry in the cache and decrement its keep count. The entry must be kept before this method is called, and it must contain the specified Cacheable.

Parameters:
entry - the entry to clean
item - the cached object contained in the entry
Throws:
StandardException - if an error occurs while cleaning

ageOut

public void ageOut()
Remove all objects that are not kept and not dirty.

Specified by:
ageOut in interface CacheManager
See Also:
Cacheable.clean(boolean), Cacheable.clearIdentity()

shutdown

public void shutdown()
              throws StandardException
Shut down the cache.

Specified by:
shutdown in interface CacheManager
Throws:
StandardException - Standard Derby error policy.

useDaemonService

public void useDaemonService(DaemonService daemon)
Specify a daemon service that can be used to perform operations in the background. Callers must provide enough synchronization so that they have exclusive access to the cache when this method is called.

Specified by:
useDaemonService in interface CacheManager
Parameters:
daemon - the daemon service to use

getBackgroundCleaner

BackgroundCleaner getBackgroundCleaner()

discard

public boolean discard(Matchable partialKey)
Discard all unused objects that match a partial key. Dirty objects will not be cleaned before their removal.

Specified by:
discard in interface CacheManager
Parameters:
partialKey - the partial (or exact) key, or null to match all keys
Returns:
true if all matching objects were removed, false otherwise

values

public java.util.Collection<Cacheable> values()
Return a collection view of all the Cacheables in the cache. There is no guarantee that the objects in the collection can be accessed in a thread-safe manner once this method has returned, so it should only be used for diagnostic purposes. (Currently, it is only used by the StatementCache VTI.)

Specified by:
values in interface CacheManager
Returns:
a collection view of the objects in the cache

Built on Thu 2010-12-23 20:49:13+0000, from revision ???

Apache Derby V10.6 Internals - Copyright © 2004,2007 The Apache Software Foundation. All Rights Reserved.