Top Description Fields Constructors Methods
org.apache.derby.impl.services.cache

pack-priv final Class ConcurrentCache

extends Object
implements CacheManager
Class Inheritance
All Implemented Interfaces
org.apache.derby.iapi.services.cache.CacheManager
Imports
java.util.ArrayList, .Collection, java.util.concurrent.ConcurrentHashMap, java.util.concurrent.atomic.AtomicLong, org.apache.derby.shared.common.error.StandardException, org.apache.derby.shared.common.reference.Module, .SQLState, org.apache.derby.iapi.services.cache.CacheManager, .Cacheable, .CacheableFactory, org.apache.derby.iapi.services.daemon.DaemonService, org.apache.derby.iapi.services.jmx.ManagementService, org.apache.derby.iapi.services.monitor.Monitor, org.apache.derby.shared.common.sanity.SanityManager, org.apache.derby.iapi.util.Matchable, org.apache.derby.mbeans.CacheManagerMBean

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

Modifier and TypeField and Description
private final ConcurrentHashMap<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 volatile boolean
collectAccessCounts

Flag that tells if hit/miss/eviction counts should be collected.

private final AtomicLong
evictions

The number of evictions from the cache.

private final AtomicLong
hits

The number of cache hits.

private final CacheableFactory
holderFactory

Factory which creates Cacheables.

private final int
maxSize

The maximum size (number of elements) for this cache.

private Object
mbean

The identifier of the MBean that allows monitoring of this instance.

private final AtomicLong
misses

The number of cache misses.

private final String
name

Name of this cache.

private final ReplacementPolicy
replacementPolicy

Replacement policy to be used for this cache.

private volatile boolean
stopped

Flag that indicates whether this cache instance has been shut down.

Constructor Summary

AccessConstructor and Description
pack-priv
ConcurrentCache(CacheableFactory
factory which creates Cacheables
holderFactory
,
String
the name of the cache
name
,
int
the initial capacity of the cache
initialSize
,
int
maximum number of elements in the cache
maxSize
)

Creates a new cache manager.

Method Summary

Modifier and TypeMethod and Description
public void
ageOut()

Implements org.apache.derby.iapi.services.cache.CacheManager.ageOut.

Remove all objects that are not kept and not dirty.
public void
clean(Matchable
the partial (or exact) key to match
partialKey
)

Implements org.apache.derby.iapi.services.cache.CacheManager.clean.

Clean all dirty objects matching a partial key.
public void
cleanAll()

Implements org.apache.derby.iapi.services.cache.CacheManager.cleanAll.

Clean all dirty objects in the cache.
pack-priv void
cleanAndUnkeepEntry(CacheEntry
the entry to clean
entry
,
Cacheable
the cached object contained in the entry
item
)

Clean an entry in the cache and decrement its keep count.

private void
cleanCache(Matchable
the partial (or exact) key to match, or null to match all keys
partialKey
)

Clean all dirty objects matching a partial key.

pack-priv void
cleanEntry(CacheEntry
the entry to clean
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.

public Cacheable

Returns:

a reference to the cached object, or null if the object cannot be created
create
(Object
identity of the object to create
key
,
Object
parameters passed to Cacheable.createIdentity()
createParameter
)

Implements org.apache.derby.iapi.services.cache.CacheManager.create.

Create an object in the cache.
public void
deregisterMBean()

Implements org.apache.derby.iapi.services.cache.CacheManager.deregisterMBean.

Deregister the MBean that monitors this cache.
public boolean

Returns:

true if all matching objects were removed, false otherwise
discard
(Matchable
the partial (or exact) key, or null to match all keys
partialKey
)

Implements org.apache.derby.iapi.services.cache.CacheManager.discard.

Discard all unused objects that match a partial key.
pack-priv void
evictEntry(Object
identity of the entry to remove
key
)

Evict an entry to make room for a new entry that is being inserted into the cache.

public Cacheable

Returns:

the cached object, or null if it cannot be found
find
(Object
identity of the object to find
key
)

Implements org.apache.derby.iapi.services.cache.CacheManager.find.

Find an object in the cache.
public Cacheable

Returns:

the cached object, or null if it's not in the cache
findCached
(Object
identity of the object to find
key
)

Implements org.apache.derby.iapi.services.cache.CacheManager.findCached.

Find an object in the cache.
pack-priv long
getAllocatedEntries()

Get the number of allocated entries in the cache.

pack-priv BackgroundCleaner
pack-priv boolean
getCollectAccessCounts()

Check if collection of hit/miss/eviction counts is enabled.

private CacheEntry

Returns:

an entry for the specified key, always locked
getEntry
(Object
the identity of the cached object
key
)

Get the entry associated with the specified key from the cache.

pack-priv long
getEvictionCount()

Get the number of evictions from the cache.

pack-priv long
getHitCount()

Get the number of cache hits.

pack-priv long
getMaxEntries()

Get the maximum number of entries in the cache.

pack-priv long
getMissCount()

Get the number of cache misses.

pack-priv ReplacementPolicy

Returns:

replacement policy
getReplacementPolicy
()

Return the ReplacementPolicy instance for this cache.

private static Object
getSystemModule(final String factoryInterface)

Must be private so that user code can't call this entry point.

pack-priv long
getUsedEntries()

Get the number of cached objects.

private Cacheable

Returns:

a Cacheable object that the caller can reuse
insertIntoFreeSlot
(Object
the identity of the object being inserted
key
,
CacheEntry
the entry that is being inserted
entry
)

Insert a CacheEntry into a free slot in the ReplacementPolicy's internal data structure, and return a Cacheable that the caller can reuse.

public void
registerMBean(String
the unique name of the database to which the cache belongs
dbName
)

Implements org.apache.derby.iapi.services.cache.CacheManager.registerMBean.

Register an MBean that allows user to monitor this cache instance.

public void
release(Cacheable
a Cacheable value
item
)

Implements org.apache.derby.iapi.services.cache.CacheManager.release.

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

Implements org.apache.derby.iapi.services.cache.CacheManager.remove.

Remove an object from the cache.
private void
removeEntry(Object
the identity of the entry to remove
key
)

Remove an entry from the cache.

pack-priv void
setCollectAccessCounts(boolean collect)

Enable or disable collection of hit/miss/eviction counts.

private void
settingIdentityComplete(Object
the identity of the object being inserted
key
,
CacheEntry
the entry which is going to hold the cached object
entry
,
Cacheable
a Cacheable object with the identity set (if the identity was successfully set), or null if setting the identity failed
item
)

Complete the setting of the identity.

public void
public void
useDaemonService(DaemonService
the daemon service to use
daemon
)

Implements org.apache.derby.iapi.services.cache.CacheManager.useDaemonService.

Specify a daemon service that can be used to perform operations in the background.
public Collection<Cacheable>

Returns:

a collection view of the objects in the cache
values
()

Implements org.apache.derby.iapi.services.cache.CacheManager.values.

Return a collection view of all the Cacheables in the cache.
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

cacheback to summary
private final ConcurrentHashMap<Object, CacheEntry> cache

Map with all the cached objects.

cleanerback to summary
private BackgroundCleaner cleaner

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

collectAccessCountsback to summary
private volatile boolean collectAccessCounts

Flag that tells if hit/miss/eviction counts should be collected.

evictionsback to summary
private final AtomicLong evictions

The number of evictions from the cache.

hitsback to summary
private final AtomicLong hits

The number of cache hits.

holderFactoryback to summary
private final CacheableFactory holderFactory

Factory which creates Cacheables.

maxSizeback to summary
private final int maxSize

The maximum size (number of elements) for this cache.

mbeanback to summary
private Object mbean

The identifier of the MBean that allows monitoring of this instance.

missesback to summary
private final AtomicLong misses

The number of cache misses.

nameback to summary
private final String name

Name of this cache.

replacementPolicyback to summary
private final ReplacementPolicy replacementPolicy

Replacement policy to be used for this cache.

stoppedback to summary
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.

Constructor Detail

ConcurrentCacheback to summary
pack-priv ConcurrentCache(CacheableFactory holderFactory, String name, int initialSize, int maxSize)

Creates a new cache manager.

Parameters
holderFactory:CacheableFactory

factory which creates Cacheables

name:String

the name of the cache

initialSize:int

the initial capacity of the cache

maxSize:int

maximum number of elements in the cache

Method Detail

ageOutback to summary
public void ageOut()

Implements org.apache.derby.iapi.services.cache.CacheManager.ageOut.

Remove all objects that are not kept and not dirty.

cleanback to summary
public void clean(Matchable partialKey) throws StandardException

Implements org.apache.derby.iapi.services.cache.CacheManager.clean.

Clean all dirty objects matching a partial key.

Parameters
partialKey:Matchable

the partial (or exact) key to match

Exceptions
StandardException:

Doc from org.apache.derby.iapi.services.cache.CacheManager.clean.

Standard Derby error policy.

cleanAllback to summary
public void cleanAll() throws StandardException

Implements org.apache.derby.iapi.services.cache.CacheManager.cleanAll.

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.

Exceptions
StandardException:

Doc from org.apache.derby.iapi.services.cache.CacheManager.cleanAll.

Standard Derby error policy.

cleanAndUnkeepEntryback to summary
pack-priv 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:CacheEntry

the entry to clean

item:Cacheable

the cached object contained in the entry

Exceptions
StandardException:
if an error occurs while cleaning
cleanCacheback to summary
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:Matchable

the partial (or exact) key to match, or null to match all keys

cleanEntryback to summary
pack-priv void cleanEntry(CacheEntry entry) throws StandardException

Clean an entry in the cache.

Parameters
entry:CacheEntry

the entry to clean

Exceptions
StandardException:
if an error occurs while cleaning
countEvictionback to summary
private void countEviction()

Count an eviction from the cache.

countHitback to summary
private void countHit()

Count a cache hit.

countMissback to summary
private void countMiss()

Count a cache miss.

createback to summary
public Cacheable create(Object key, Object createParameter) throws StandardException

Implements org.apache.derby.iapi.services.cache.CacheManager.create.

Create an object in the cache. The object is kept until release() is called.

Parameters
key:Object

identity of the object to create

createParameter:Object

parameters passed to Cacheable.createIdentity()

Returns:Cacheable

a reference to the cached object, or null if the object cannot be created

Exceptions
StandardException:
if the object is already in the cache, or if some other error occurs
See Also
Cacheable#createIdentity(Object, Object)
deregisterMBeanback to summary
public void deregisterMBean()

Implements org.apache.derby.iapi.services.cache.CacheManager.deregisterMBean.

Doc from org.apache.derby.iapi.services.cache.CacheManager.deregisterMBean.

Deregister the MBean that monitors this cache. If there is no MBean for this instance, this is a no-op.

Annotations
@Override
discardback to summary
public boolean discard(Matchable partialKey)

Implements org.apache.derby.iapi.services.cache.CacheManager.discard.

Discard all unused objects that match a partial key. Dirty objects will not be cleaned before their removal.

Parameters
partialKey:Matchable

the partial (or exact) key, or null to match all keys

Returns:boolean

true if all matching objects were removed, false otherwise

evictEntryback to summary
pack-priv void evictEntry(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:Object

identity of the entry to remove

findback to summary
public Cacheable find(Object key) throws StandardException

Implements org.apache.derby.iapi.services.cache.CacheManager.find.

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.

Parameters
key:Object

identity of the object to find

Returns:Cacheable

the cached object, or null if it cannot be found

Exceptions
StandardException:

Doc from org.apache.derby.iapi.services.cache.CacheManager.find.

Standard Derby error policy.

findCachedback to summary
public Cacheable findCached(Object key) throws StandardException

Implements org.apache.derby.iapi.services.cache.CacheManager.findCached.

Find an object in the cache. If it is not present, return null. The returned object is kept until release() is called.

Parameters
key:Object

identity of the object to find

Returns:Cacheable

the cached object, or null if it's not in the cache

Exceptions
StandardException:

Doc from org.apache.derby.iapi.services.cache.CacheManager.findCached.

Standard Derby error policy.

getAllocatedEntriesback to summary
pack-priv long getAllocatedEntries()

Get the number of allocated entries in the cache.

getBackgroundCleanerback to summary
pack-priv BackgroundCleaner getBackgroundCleaner()
getCollectAccessCountsback to summary
pack-priv boolean getCollectAccessCounts()

Check if collection of hit/miss/eviction counts is enabled.

getEntryback to summary
private CacheEntry getEntry(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:Object

the identity of the cached object

Returns:CacheEntry

an entry for the specified key, always locked

getEvictionCountback to summary
pack-priv long getEvictionCount()

Get the number of evictions from the cache.

getHitCountback to summary
pack-priv long getHitCount()

Get the number of cache hits.

getMaxEntriesback to summary
pack-priv long getMaxEntries()

Get the maximum number of entries in the cache.

getMissCountback to summary
pack-priv long getMissCount()

Get the number of cache misses.

getReplacementPolicyback to summary
pack-priv ReplacementPolicy getReplacementPolicy()

Return the ReplacementPolicy instance for this cache.

Returns:ReplacementPolicy

replacement policy

getSystemModuleback to summary
private static Object getSystemModule(final String factoryInterface)

Must be private so that user code can't call this entry point.

getUsedEntriesback to summary
pack-priv long getUsedEntries()

Get the number of cached objects.

insertIntoFreeSlotback to summary
private Cacheable insertIntoFreeSlot(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:Object

the identity of the object being inserted

entry:CacheEntry

the entry that is being inserted

Returns:Cacheable

a Cacheable object that the caller can reuse

Exceptions
StandardException:
if an error occurs while inserting the entry or while allocating a new Cacheable
registerMBeanback to summary
public void registerMBean(String dbName) throws StandardException

Implements org.apache.derby.iapi.services.cache.CacheManager.registerMBean.

Doc from org.apache.derby.iapi.services.cache.CacheManager.registerMBean.

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 shutdown() is called, or it can be manually deregistered by calling deregisterMBean().

Parameters
dbName:String

the unique name of the database to which the cache belongs

Annotations
@Override
Exceptions
StandardException:
if an error occurs when registering the MBean
releaseback to summary
public void release(Cacheable item)

Implements org.apache.derby.iapi.services.cache.CacheManager.release.

Release an object that has been fetched from the cache with find(), findCached() or create().

Parameters
item:Cacheable

a Cacheable value

removeback to summary
public void remove(Cacheable item) throws StandardException

Implements org.apache.derby.iapi.services.cache.CacheManager.remove.

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

Parameters
item:Cacheable

the object to remove from the cache

Exceptions
StandardException:

Doc from org.apache.derby.iapi.services.cache.CacheManager.remove.

Standard Derby error policy.

removeEntryback to summary
private void removeEntry(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:Object

the identity of the entry to remove

setCollectAccessCountsback to summary
pack-priv void setCollectAccessCounts(boolean collect)

Enable or disable collection of hit/miss/eviction counts.

settingIdentityCompleteback to summary
private void settingIdentityComplete(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:Object

the identity of the object being inserted

entry:CacheEntry

the entry which is going to hold the cached object

item:Cacheable

a Cacheable object with the identity set (if the identity was successfully set), or null if setting the identity failed

shutdownback to summary
public void shutdown() throws StandardException

Implements org.apache.derby.iapi.services.cache.CacheManager.shutdown.

Shut down the cache.

Exceptions
StandardException:

Doc from org.apache.derby.iapi.services.cache.CacheManager.shutdown.

Standard Derby error policy.

useDaemonServiceback to summary
public void useDaemonService(DaemonService daemon)

Implements org.apache.derby.iapi.services.cache.CacheManager.useDaemonService.

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.

Parameters
daemon:DaemonService

the daemon service to use

valuesback to summary
public Collection<Cacheable> values()

Implements org.apache.derby.iapi.services.cache.CacheManager.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.)

Returns:Collection<Cacheable>

a collection view of the objects in the cache