ConcurrentCache (Apache Derby V10.14 Internals)

java.lang.Object
- 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

Fields
Modifier and Type	Field	Description
`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 boolean`	`collectAccessCounts`	Flag that tells if hit/miss/eviction counts should be collected.
`private java.util.concurrent.atomic.AtomicLong`	`evictions`	The number of evictions from the cache.
`private java.util.concurrent.atomic.AtomicLong`	`hits`	The number of cache hits.
`private CacheableFactory`	`holderFactory`	Factory which creates `Cacheable`s.
`private int`	`maxSize`	The maximum size (number of elements) for this cache.
`private java.lang.Object`	`mbean`	The identifier of the MBean that allows monitoring of this instance.
`private java.util.concurrent.atomic.AtomicLong`	`misses`	The number of cache misses.
`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

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

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`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.
`private void`	`countEviction()`	Count an eviction from the cache.
`private void`	`countHit()`	Count a cache hit.
`private void`	`countMiss()`	Count a cache miss.
`Cacheable`	`create(java.lang.Object key, java.lang.Object createParameter)`	Create an object in the cache.
`void`	`deregisterMBean()`	Deregister the MBean that monitors this 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) long`	`getAllocatedEntries()`	Get the number of allocated entries in the cache.
`(package private) BackgroundCleaner`	`getBackgroundCleaner()`
`(package private) boolean`	`getCollectAccessCounts()`	Check if collection of hit/miss/eviction counts is enabled.
`private CacheEntry`	`getEntry(java.lang.Object key)`	Get the entry associated with the specified key from the cache.
`(package private) long`	`getEvictionCount()`	Get the number of evictions from the cache.
`(package private) long`	`getHitCount()`	Get the number of cache hits.
`(package private) long`	`getMaxEntries()`	Get the maximum number of entries in the cache.
`(package private) long`	`getMissCount()`	Get the number of cache misses.
`(package private) ReplacementPolicy`	`getReplacementPolicy()`	Return the `ReplacementPolicy` instance for this cache.
`private static java.lang.Object`	`getSystemModule(java.lang.String factoryInterface)`	Privileged module lookup.
`(package private) long`	`getUsedEntries()`	Get the number of cached objects.
`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`	`registerMBean(java.lang.String dbName)`	Register an MBean that allows user to monitor this cache instance.
`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.
`(package private) void`	`setCollectAccessCounts(boolean collect)`	Enable or disable collection of hit/miss/eviction counts.
`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 `Cacheable`s 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.
  - mbean
```
private java.lang.Object mbean
```
    The identifier of the MBean that allows monitoring of this instance.
  - collectAccessCounts
```
private volatile boolean collectAccessCounts
```
    Flag that tells if hit/miss/eviction counts should be collected.
  - hits
```
private final java.util.concurrent.atomic.AtomicLong hits
```
    The number of cache hits.
  - misses
```
private final java.util.concurrent.atomic.AtomicLong misses
```
    The number of cache misses.
  - evictions
```
private final java.util.concurrent.atomic.AtomicLong evictions
```
    The number of evictions from the 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
  - registerMBean
```
public void registerMBean(java.lang.String dbName)
                   throws StandardException
```
    Description copied from interface: CacheManager
    
    Register an MBean that allows user to monitor this cache instance. This is a no-op if the platform does not support Java Management Extensions (JMX).
    
    The MBean will be automatically deregistered when CacheManager.shutdown() is called, or it can be manually deregistered by calling CacheManager.deregisterMBean().
    
    Specified by:
    
    registerMBean in interface CacheManager
    
    Parameters:
    
    dbName - the unique name of the database to which the cache belongs
    
    Throws:
    
    StandardException - if an error occurs when registering the MBean
  - deregisterMBean
```
public void deregisterMBean()
```
    Description copied from interface: CacheManager
    
    Deregister the MBean that monitors this cache. If there is no MBean for this instance, this is a no-op.
    
    Specified by:
    
    deregisterMBean in interface CacheManager
  - countHit
```
private void countHit()
```
    Count a cache hit.
  - countMiss
```
private void countMiss()
```
    Count a cache miss.
  - countEviction
```
private void countEviction()
```
    Count an eviction from the cache.
  - setCollectAccessCounts
```
void setCollectAccessCounts(boolean collect)
```
    Enable or disable collection of hit/miss/eviction counts.
  - getCollectAccessCounts
```
boolean getCollectAccessCounts()
```
    Check if collection of hit/miss/eviction counts is enabled.
  - getHitCount
```
long getHitCount()
```
    Get the number of cache hits.
  - getMissCount
```
long getMissCount()
```
    Get the number of cache misses.
  - getEvictionCount
```
long getEvictionCount()
```
    Get the number of evictions from the cache.
  - getMaxEntries
```
long getMaxEntries()
```
    Get the maximum number of entries in the cache.
  - getAllocatedEntries
```
long getAllocatedEntries()
```
    Get the number of allocated entries in the cache.
  - getUsedEntries
```
long getUsedEntries()
```
    Get the number of cached objects.
  - getSystemModule
```
private static java.lang.Object getSystemModule(java.lang.String factoryInterface)
```
    Privileged module lookup. Must be private so that user code can't call this entry point.

Class ConcurrentCache

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

cache

holderFactory

name

maxSize

replacementPolicy

mbean

collectAccessCounts

hits

misses

evictions

stopped

cleaner

Constructor Detail

ConcurrentCache

Method Detail

getReplacementPolicy

getEntry

removeEntry

evictEntry

insertIntoFreeSlot

settingIdentityComplete

find

findCached

create

release

remove

cleanAll

clean

cleanCache

cleanEntry

cleanAndUnkeepEntry

ageOut

shutdown

useDaemonService

getBackgroundCleaner

discard

values

registerMBean

deregisterMBean

countHit

countMiss

countEviction

setCollectAccessCounts

getCollectAccessCounts

getHitCount

getMissCount

getEvictionCount

getMaxEntries

getAllocatedEntries

getUsedEntries

getSystemModule