Package org.apache.derby.impl.services.cache

Class 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 Cacheables.
      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 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.

      • 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

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

      • 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

      • 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

      • 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

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