Package org.apache.commons.jcs3.engine.control

Class CompositeCache<K,V>

java.lang.Object
org.apache.commons.jcs3.engine.control.CompositeCache<K,V>
All Implemented Interfaces:
ICache<K,V>, ICacheType, IRequireScheduler
public class CompositeCache<K,V> extends Object implements ICache<K,V>, IRequireScheduler
This is the primary hub for a single cache/region. It controls the flow of items through the cache. The auxiliary and memory caches are plugged in here.

This is the core of a JCS region. Hence, this simple class is the core of JCS.

  • Constructor Details

  • Method Details

    • setElementEventQueue

      public void setElementEventQueue(IElementEventQueue queue)
      Injector for Element event queue
      Parameters:
      queue -

    • setCompositeCacheManager

      public void setCompositeCacheManager(CompositeCacheManager manager)
      Injector for cache manager
      Parameters:
      manager -

    • setScheduledExecutorService

      public void setScheduledExecutorService(ScheduledExecutorService scheduledExecutor)
      Description copied from interface: IRequireScheduler
      Inject an instance of a central ScheduledExecutorService
      Specified by:
      setScheduledExecutorService in interface IRequireScheduler
      See Also:

    • setAuxCaches

      public void setAuxCaches(List<AuxiliaryCache<K,V>> auxCaches)
      This sets the list of auxiliary caches for this region. It filters out null caches

      Parameters:
      auxCaches -
      Since:
      3.1

    • setAuxCaches

      @Deprecated public void setAuxCaches(AuxiliaryCache<K,V>[] auxCaches)
      Deprecated.
      Use List method
      This sets the list of auxiliary caches for this region.

      Parameters:
      auxCaches -

    • getAuxCacheList

      public List<AuxiliaryCache<K,V>> getAuxCacheList()
      Get the list of auxiliary caches for this region.

      Returns:
      a list of auxiliary caches, may be empty, never null
      Since:
      3.1

    • getAuxCaches

      @Deprecated public AuxiliaryCache<K,V>[] getAuxCaches()
      Deprecated.
      Use List method
      Get the list of auxiliary caches for this region.

      Returns:
      an array of auxiliary caches, may be empty, never null

    • update

      public void update(ICacheElement<K,V> ce) throws IOException
      Standard update method.

      Specified by:
      update in interface ICache<K,V>
      Parameters:
      ce -
      Throws:
      IOException

    • localUpdate

      public void localUpdate(ICacheElement<K,V> ce) throws IOException
      Standard update method.

      Parameters:
      ce -
      Throws:
      IOException

    • update

      protected void update(ICacheElement<K,V> cacheElement, boolean localOnly) throws IOException
      Put an item into the cache. If it is localOnly, then do no notify remote or lateral auxiliaries.

      Parameters:
      cacheElement - the ICacheElement<K, V>
      localOnly - Whether the operation should be restricted to local auxiliaries.
      Throws:
      IOException

    • updateAuxiliaries

      protected void updateAuxiliaries(ICacheElement<K,V> cacheElement, boolean localOnly) throws IOException
      This method is responsible for updating the auxiliaries if they are present. If it is local only, any lateral and remote auxiliaries will not be updated.

      Before updating an auxiliary it checks to see if the element attributes permit the operation.

      Disk auxiliaries are only updated if the disk cache is not merely used as a swap. If the disk cache is merely a swap, then items will only go to disk when they overflow from memory.

      This is called by update(cacheElement, localOnly) after it updates the memory cache.

      This is protected to make it testable.

      Parameters:
      cacheElement -
      localOnly -
      Throws:
      IOException

    • spoolToDisk

      public void spoolToDisk(ICacheElement<K,V> ce)
      Writes the specified element to any disk auxiliaries. Might want to rename this "overflow" in case the hub wants to do something else.

      If JCS is not configured to use the disk as a swap, that is if the CompositeCacheAttribute diskUsagePattern is not SWAP_ONLY, then the item will not be spooled.

      Parameters:
      ce - The CacheElement

    • get

      public ICacheElement<K,V> get(K key)
      Gets an item from the cache.

      Specified by:
      get in interface ICache<K,V>
      Parameters:
      key -
      Returns:
      element from the cache, or null if not present
      See Also:

    • localGet

      public ICacheElement<K,V> localGet(K key)
      Do not try to go remote or laterally for this get.

      Parameters:
      key -
      Returns:
      ICacheElement

    • get

      protected ICacheElement<K,V> get(K key, boolean localOnly)
      Look in memory, then disk, remote, or laterally for this item. The order is dependent on the order in the cache.ccf file.

      Do not try to go remote or laterally for this get if it is localOnly. Otherwise try to go remote or lateral if such an auxiliary is configured for this region.

      Parameters:
      key -
      localOnly -
      Returns:
      ICacheElement

    • doExpires

      protected void doExpires(ICacheElement<K,V> element)

    • getMultiple

      public Map<K,ICacheElement<K,V>> getMultiple(Set<K> keys)
      Gets multiple items from the cache based on the given set of keys.

      Specified by:
      getMultiple in interface ICache<K,V>
      Parameters:
      keys -
      Returns:
      a map of K key to ICacheElement<K, V> element, or an empty map if there is no data in cache for any of these keys

    • localGetMultiple

      public Map<K,ICacheElement<K,V>> localGetMultiple(Set<K> keys)
      Gets multiple items from the cache based on the given set of keys. Do not try to go remote or laterally for this data.

      Parameters:
      keys -
      Returns:
      a map of K key to ICacheElement<K, V> element, or an empty map if there is no data in cache for any of these keys

    • getMultiple

      protected Map<K,ICacheElement<K,V>> getMultiple(Set<K> keys, boolean localOnly)
      Look in memory, then disk, remote, or laterally for these items. The order is dependent on the order in the cache.ccf file. Keep looking in each cache location until either the element is found, or the method runs out of places to look.

      Do not try to go remote or laterally for this get if it is localOnly. Otherwise try to go remote or lateral if such an auxiliary is configured for this region.

      Parameters:
      keys -
      localOnly -
      Returns:
      ICacheElement

    • getMatching

      public Map<K,ICacheElement<K,V>> getMatching(String pattern)
      Build a map of all the matching elements in all of the auxiliaries and memory.

      Specified by:
      getMatching in interface ICache<K,V>
      Parameters:
      pattern -
      Returns:
      a map of K key to ICacheElement<K, V> element, or an empty map if there is no data in cache for any matching keys

    • localGetMatching

      public Map<K,ICacheElement<K,V>> localGetMatching(String pattern)
      Build a map of all the matching elements in all of the auxiliaries and memory. Do not try to go remote or laterally for this data.

      Parameters:
      pattern -
      Returns:
      a map of K key to ICacheElement<K, V> element, or an empty map if there is no data in cache for any matching keys

    • getMatching

      protected Map<K,ICacheElement<K,V>> getMatching(String pattern, boolean localOnly)
      Build a map of all the matching elements in all of the auxiliaries and memory. Items in memory will replace from the auxiliaries in the returned map. The auxiliaries are accessed in opposite order. It's assumed that those closer to home are better.

      Do not try to go remote or laterally for this get if it is localOnly. Otherwise try to go remote or lateral if such an auxiliary is configured for this region.

      Parameters:
      pattern -
      localOnly -
      Returns:
      a map of K key to ICacheElement<K, V> element, or an empty map if there is no data in cache for any matching keys

    • getMatchingFromMemory

      protected Map<K,ICacheElement<K,V>> getMatchingFromMemory(String pattern) throws IOException
      Gets the key array from the memcache. Builds a set of matches. Calls getMultiple with the set. Returns a map: key -> result.

      Parameters:
      pattern -
      Returns:
      a map of K key to ICacheElement<K, V> element, or an empty map if there is no data in cache for any matching keys
      Throws:
      IOException

    • getKeySet

      public Set<K> getKeySet()
      Get a set of the keys for all elements in the cache

      Returns:
      A set of the key type

    • getKeySet

      public Set<K> getKeySet(boolean localOnly)
      Get a set of the keys for all elements in the cache

      Parameters:
      localOnly - true if only memory keys are requested
      Returns:
      A set of the key type

    • remove

      public boolean remove(K key)
      Removes an item from the cache.

      Specified by:
      remove in interface ICache<K,V>
      Parameters:
      key -
      Returns:
      true is it was removed
      See Also:

    • localRemove

      public boolean localRemove(K key)
      Do not propagate removeall laterally or remotely.

      Parameters:
      key -
      Returns:
      true if the item was already in the cache.

    • remove

      protected boolean remove(K key, boolean localOnly)
      fromRemote: If a remove call was made on a cache with both, then the remote should have been called. If it wasn't then the remote is down. we'll assume it is down for all. If it did come from the remote then the cache is remotely configured and lateral removal is unnecessary. If it came laterally then lateral removal is unnecessary. Does this assume that there is only one lateral and remote for the cache? Not really, the initial removal should take care of the problem if the source cache was similarly configured. Otherwise the remote cache, if it had no laterals, would remove all the elements from remotely configured caches, but if those caches had some other weird laterals that were not remotely configured, only laterally propagated then they would go out of synch. The same could happen for multiple remotes. If this looks necessary we will need to build in an identifier to specify the source of a removal.

      Parameters:
      key -
      localOnly -
      Returns:
      true if the item was in the cache, else false

    • removeAll

      public void removeAll() throws IOException
      Clears the region. This command will be sent to all auxiliaries. Some auxiliaries, such as the JDBC disk cache, can be configured to not honor removeAll requests.

      Specified by:
      removeAll in interface ICache<K,V>
      Throws:
      IOException
      See Also:

    • localRemoveAll

      public void localRemoveAll() throws IOException
      Will not pass the remove message remotely.

      Throws:
      IOException

    • removeAll

      protected void removeAll(boolean localOnly) throws IOException
      Removes all cached items.

      Parameters:
      localOnly - must pass in false to get remote and lateral aux's updated. This prevents looping.
      Throws:
      IOException

    • dispose

      public void dispose()
      Flushes all cache items from memory to auxiliary caches and close the auxiliary caches.
      Specified by:
      dispose in interface ICache<K,V>

    • dispose

      public void dispose(boolean fromRemote)
      Invoked only by CacheManager. This method disposes of the auxiliaries one by one. For the disk cache, the items in memory are freed, meaning that they will be sent through the overflow channel to disk. After the auxiliaries are disposed, the memory cache is disposed.

      Parameters:
      fromRemote -

    • save

      public void save()
      Calling save cause the entire contents of the memory cache to be flushed to all auxiliaries. Though this put is extremely fast, this could bog the cache and should be avoided. The dispose method should call a version of this. Good for testing.

    • getSize

      public int getSize()
      Gets the size attribute of the Cache object. This return the number of elements, not the byte size.

      Specified by:
      getSize in interface ICache<K,V>
      Returns:
      The size value

    • getCacheType

      public ICacheType.CacheType getCacheType()
      Gets the cacheType attribute of the Cache object.

      Specified by:
      getCacheType in interface ICacheType
      Returns:
      The cacheType value

    • getStatus

      public CacheStatus getStatus()
      Gets the status attribute of the Cache object.

      Specified by:
      getStatus in interface ICache<K,V>
      Returns:
      The status value

    • getStats

      public String getStats()
      Gets stats for debugging.

      Specified by:
      getStats in interface ICache<K,V>
      Returns:
      String

    • getStatistics

      public ICacheStats getStatistics()
      This returns data gathered for this region and all the auxiliaries it currently uses.

      Returns:
      Statistics and Info on the Region.

    • getCacheName

      public String getCacheName()
      Gets the cacheName attribute of the Cache object. This is also known as the region name.

      Specified by:
      getCacheName in interface ICache<K,V>
      Returns:
      The cacheName value

    • getElementAttributes

      public IElementAttributes getElementAttributes()
      Gets the default element attribute of the Cache object This returns a copy. It does not return a reference to the attributes.

      Returns:
      The attributes value

    • setElementAttributes

      public void setElementAttributes(IElementAttributes attr)
      Sets the default element attribute of the Cache object.

      Parameters:
      attr -

    • getCacheAttributes

      public ICompositeCacheAttributes getCacheAttributes()
      Gets the ICompositeCacheAttributes attribute of the Cache object.

      Returns:
      The ICompositeCacheAttributes value

    • setCacheAttributes

      public void setCacheAttributes(ICompositeCacheAttributes cattr)
      Sets the ICompositeCacheAttributes attribute of the Cache object.

      Parameters:
      cattr - The new ICompositeCacheAttributes value

    • getElementAttributes

      public IElementAttributes getElementAttributes(K key) throws CacheException, IOException
      Gets the elementAttributes attribute of the Cache object.

      Parameters:
      key -
      Returns:
      The elementAttributes value
      Throws:
      CacheException
      IOException

    • isExpired

      public boolean isExpired(ICacheElement<K,V> element)
      Determine if the element is expired based on the values of the element attributes
      Parameters:
      element - the element
      Returns:
      true if the element is expired

    • isExpired

      public boolean isExpired(ICacheElement<K,V> element, long timestamp, ElementEventType eventMaxlife, ElementEventType eventIdle)
      Check if the element is expired based on the values of the element attributes
      Parameters:
      element - the element
      timestamp - the timestamp to compare to
      eventMaxlife - the event to fire in case the max life time is exceeded
      eventIdle - the event to fire in case the idle time is exceeded
      Returns:
      true if the element is expired

    • handleElementEvent

      public void handleElementEvent(ICacheElement<K,V> element, ElementEventType eventType)
      If there are event handlers for the item, then create an event and queue it up.

      This does not call handle directly; instead the handler and the event are put into a queue. This prevents the event handling from blocking normal cache operations.

      Parameters:
      element - the item
      eventType - the event type

    • getMemoryCache

      public IMemoryCache<K,V> getMemoryCache()
      Access to the memory cache for instrumentation.

      Returns:
      the MemoryCache implementation

    • getHitCountRam

      public long getHitCountRam()
      Number of times a requested item was found in the memory cache.

      Returns:
      number of hits in memory

    • getHitCountAux

      public long getHitCountAux()
      Number of times a requested item was found in and auxiliary cache.
      Returns:
      number of auxiliary hits.

    • getMissCountNotFound

      public long getMissCountNotFound()
      Number of times a requested element was not found.
      Returns:
      number of misses.

    • getMissCountExpired

      public long getMissCountExpired()
      Number of times a requested element was found but was expired.
      Returns:
      number of found but expired gets.

    • getUpdateCount

      public long getUpdateCount()
      Returns:
      Returns the updateCount.

    • setKeyMatcher

      public void setKeyMatcher(IKeyMatcher<K> keyMatcher)
      Sets the key matcher used by get matching.

      Specified by:
      setKeyMatcher in interface ICache<K,V>
      Parameters:
      keyMatcher -

    • getKeyMatcher

      public IKeyMatcher<K> getKeyMatcher()
      Returns the key matcher used by get matching.

      Returns:
      keyMatcher

    • toString

      public String toString()
      This returns the stats.

      Overrides:
      toString in class Object
      Returns:
      getStats()