Class ConcurrentCache

java.lang.Object
org.apache.derby.impl.services.cache.ConcurrentCache
All Implemented Interfaces:
CacheManager
final class ConcurrentCache extends 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 Details

    • cache

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

    • holderFactory

      private final CacheableFactory holderFactory
      Factory which creates Cacheables.

    • name

      private final 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 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 AtomicLong hits
      The number of cache hits.

    • misses

      private final AtomicLong misses
      The number of cache misses.

    • evictions

      private final 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 Details

    • ConcurrentCache

      ConcurrentCache(CacheableFactory holderFactory, 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 Details

    • getReplacementPolicy

      ReplacementPolicy getReplacementPolicy()
      Return the ReplacementPolicy instance for this cache.
      Returns:
      replacement policy

    • getEntry

      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 - the identity of the cached object
      Returns:
      an entry for the specified key, always locked

    • removeEntry

      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 - the identity of the entry to remove

    • evictEntry

      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 - identity of the entry to remove

    • insertIntoFreeSlot

      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 - 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(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(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:

    • findCached

      public Cacheable findCached(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(Object key, 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:

    • 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:

    • 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:

    • 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 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(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 Object getSystemModule(String factoryInterface)
      Privileged module lookup. Must be private so that user code can't call this entry point.