Package com.tangosol.net.cache

Class SerializationPagedCache

java.lang.Object
com.tangosol.util.Base
com.tangosol.util.AbstractKeyBasedMap
com.tangosol.util.AbstractKeySetBasedMap
com.tangosol.net.cache.SerializationMap
com.tangosol.net.cache.AbstractSerializationCache
com.tangosol.net.cache.SerializationPagedCache
All Implemented Interfaces:
ObservableMap, Map
public class SerializationPagedCache extends AbstractSerializationCache
A version of SerializationMap that implements an LRU policy using time-based paging of the cache. This implementation uses a BinaryStoreManager to create a current BinaryStore which is used to store all objects being placed into the cache. Once the specified "current" time period has elapsed, a new current BinaryStore is created, and the previously current page is closed, which means that it will no longer be used to store objects that are being placed into the cache. This continues until the total number of pages (the one current plus all of the previously current pages) exceeds the maximum number of pages defined for the cache. When that happens, the oldest page is evicted, triggering the related events, and the BinaryStore for that page is destroyed. Note that cache items can be accessed out of and removed from closed pages, but cache items are never written to closed pages.

To avoid a massive number of simultaneous events, the eviction of a closed page can be performed asynchronously on a daemon thread.

Since:
Coherence 2.4
Author:
cp 2004.05.05

  • Constructor Details

    • SerializationPagedCache

      public SerializationPagedCache(BinaryStoreManager storemgr, int cPages, int cPageSecs)
      Construct a SerializationPagedCache on top of a BinaryStoreManager.
      Parameters:
      storemgr - the BinaryStoreManager that provides BinaryStore objects that the serialized objects are written to
      cPages - the maximum number of pages to have active at a time
      cPageSecs - the length of time, in seconds, that a 'page' is current

    • SerializationPagedCache

      public SerializationPagedCache(BinaryStoreManager storemgr, int cPages, int cPageSecs, ClassLoader loader)
      Construct a SerializationPagedCache on top of a BinaryStoreManager.
      Parameters:
      storemgr - the BinaryStoreManager that provides BinaryStore objects that the serialized objects are written to
      cPages - the maximum number of pages to have active at a time
      cPageSecs - the length of time, in seconds, that a 'page' is current
      loader - the ClassLoader to use for deserialization

    • SerializationPagedCache

      public SerializationPagedCache(BinaryStoreManager storemgr, int cPages, int cPageSecs, boolean fBinaryMap, boolean fPassive)
      Construct a SerializationPagedCache on top of a BinaryStoreManager.
      Parameters:
      storemgr - the BinaryStoreManager that provides BinaryStore objects that the serialized objects are written to
      cPages - the maximum number of pages to have active at a time
      cPageSecs - the length of time, in seconds, that a 'page' is current
      fBinaryMap - true indicates that this map will only manage binary keys and values
      fPassive - true indicates that this map is a passive cache, which means that it is just a backup of the cache and does not actively expire data

  • Method Details

    • getConfig

      public XmlElement getConfig()
      Determine the current configuration of the object.
      Returns:
      the XML configuration or null

    • setConfig

      public void setConfig(XmlElement xml)
      Specify the configuration for the object.
      Parameters:
      xml - the XML configuration for the object
      Throws:
      IllegalStateException - if the object is not in a state that allows the configuration to be set; for example, if the object has already been configured and cannot be reconfigured

    • clear

      public void clear()
      Clear all key/value mappings.
      Specified by:
      clear in interface Map
      Overrides:
      clear in class AbstractSerializationCache

    • get

      public Object get(Object oKey)
      Returns the value to which this map maps the specified key.
      Specified by:
      get in interface Map
      Overrides:
      get in class SerializationMap
      Parameters:
      oKey - the key object
      Returns:
      the value to which this map maps the specified key, or null if the map contains no mapping for this key

    • put

      public Object put(Object oKey, Object oValue)
      Associates the specified value with the specified key in this map.
      Specified by:
      put in interface Map
      Overrides:
      put in class AbstractSerializationCache
      Parameters:
      oKey - key with which the specified value is to be associated
      oValue - value to be associated with the specified key
      Returns:
      previous value associated with specified key, or null if there was no mapping for key

    • putAll

      public void putAll(Map map)
      Copies all of the mappings from the specified map to this map. These mappings will replace any mappings that this map had for any of the keys currently in the specified map.
      Specified by:
      putAll in interface Map
      Overrides:
      putAll in class AbstractSerializationCache
      Parameters:
      map - map of entries to be stored in this map

    • remove

      public Object remove(Object oKey)
      Removes the mapping for this key from this map if present. Expensive: updates both the underlying cache and the local cache.
      Specified by:
      remove in interface Map
      Overrides:
      remove in class AbstractSerializationCache
      Parameters:
      oKey - key whose mapping is to be removed from the map
      Returns:
      previous value associated with specified key, or null if there was no mapping for key. A null return can also indicate that the map previously associated null with the specified key, if the implementation supports null values.

    • removeBlind

      protected boolean removeBlind(Object oKey)
      Removes the mapping for this key from this map if present. This method exists to allow sub-classes to optimize remove functionality for situations in which the original value is not required.
      Overrides:
      removeBlind in class AbstractSerializationCache
      Parameters:
      oKey - key whose mapping is to be removed from the map
      Returns:
      true iff the Map changed as the result of this operation

    • eraseStore

      protected void eraseStore()
      Erase all entries from the underlying store.
      Overrides:
      eraseStore in class SerializationMap

    • evict

      public void evict()
      Flush items that have expired. This may occur asynchronously, depending on the AsynchronousPageDeactivation property.
      Specified by:
      evict in class AbstractSerializationCache
      Since:
      Coherence 3.2

    • toString

      public String toString()
      Returns a string representation of this Map. The string representation consists of a list of key-value mappings in the order returned by the Map's entrySet view's iterator, enclosed in braces ("{}"). Adjacent mappings are separated by the characters ", " (comma and space). Each key-value mapping is rendered as the key followed by an equals sign ("=") followed by the associated value. Keys and values are converted to strings as by String.valueOf(Object).
      Overrides:
      toString in class SerializationMap
      Returns:
      a String representation of this Map

    • getDescription

      protected String getDescription()
      Assemble a human-readable description.
      Overrides:
      getDescription in class AbstractSerializationCache
      Returns:
      a description of this Map

    • isVirtualErase

      public boolean isVirtualErase()
      Determine if BinaryStore erase commands will be done only in memory (to the cached list of keys) and not passsed to the underlying BinaryStore, thus improving performance and cutting I/O, but potentially wasting disk space (or whatever resource the paged data are stored on.)
      Returns:
      true if the erase should not go to the underlying store, but simply remove the key from the cached list of keys managed by that store

    • setVirtualErase

      protected void setVirtualErase(boolean fVirtualErase)
      Specify whether BinaryStore erase commands will be done only in memory to the cached list of keys.
      Parameters:
      fVirtualErase - true if the erase should not go to the underlying store, but simply remove the key from the cached list of keys managed by that store; false to pass all erase requests down to the underlying store

    • getLockDelaySeconds

      public int getLockDelaySeconds()
      Determine the number of seconds to wait for a lock in debug mode. This is only applicable to debug mode; in normal mode, a lock is queued for indefinitely.
      Returns:
      the number of seconds to wait for a lock

    • setLockDelaySeconds

      public void setLockDelaySeconds(int cSecondsLockDelay)
      Specify the number of seconds to wait for a lock in debug mode. This is only applicable to debug mode; in normal mode, a lock is queued for indefinitely.

      This will not take effect until the next lock is requested and unless debug mode is turned on.

      Parameters:
      cSecondsLockDelay - the number of seconds to wait for a lock

    • getLockMap

      protected ConcurrentMap getLockMap()
      Obtain the map used for managing key- and map-level locks to ensure data consistency.
      Returns:
      the ConcurrentMap used to manage thread access to keys and to the entire map

    • getBinaryStoreManager

      protected BinaryStoreManager getBinaryStoreManager()
      Returns the BinaryStoreManager that provides BinaryStore objects this cache uses for its storage.

      This object is intended for use only by the createBinaryStore, and destroyBinaryStore methods.

      Returns:
      the BinaryStoreManager for this cache

    • setBinaryStore

      protected void setBinaryStore(BinaryStore store)
      Configures the BinaryStore that this map will use for its storage.
      Overrides:
      setBinaryStore in class SerializationMap
      Parameters:
      store - the BinaryStore to use

    • getPagedBinaryStore

      protected SerializationPagedCache.PagedBinaryStore getPagedBinaryStore()
      Returns the BinaryStore that this map uses for its storage.

      Note: This implementation assumes that the BinaryStore is only being modified by this Map instance. If you modify the BinaryStore contents, the behavior of this Map is undefined.

      Returns:
      the BinaryStore

    • getBinaryStoreList

      protected List getBinaryStoreList()
      Get the list of registered BinaryStore objects. This list is intended for use only by the createBinaryStore, destroyBinaryStore and iterateBinaryStores methods.
      Returns:
      the list of BinaryStore objects returned previously from createBinaryStore that have not yet been destroyed by destroyBinaryStore

    • iterateBinaryStores

      protected Iterator iterateBinaryStores()
      Obtain an iterator of all registered (not destroyed) BinaryStore objects being used by this cache.
      Returns:
      a read-only iterator of BinaryStore objects used by this cache

    • getMaximumPages

      public int getMaximumPages()
      Determine the maximum number of pages that the cache will manage, beyond which the oldest pages are destroyed.
      Returns:
      the maximum number of pages that the cache will manage

    • getPageDuration

      public long getPageDuration()
      Determine the length of time that the most recently created page is kept as the current page.
      Returns:
      the time in milliseconds that a page remains current

    • setPageDuration

      protected void setPageDuration(long cPageMillis)
      Specify the length of time that the most recently created page is kept as the current page.
      Parameters:
      cPageMillis - the time in milliseconds that a page remains current

    • getCurrentPageTime

      protected long getCurrentPageTime()
      Determine the time that the current page was created.
      Returns:
      the time that the current page was created or 0L if no page has been created yet

    • getPageAdvanceTime

      protected long getPageAdvanceTime()
      Determine the time that the next page should be created. If the time returned from this method is in the past, then the implication is that a new page should be created to replace the current page.
      Returns:
      the time that the next page should be created or 0L if no page has been created yet

    • isPassivePagedBackup

      public boolean isPassivePagedBackup()
      Determine if this is just a passive backup for a paged cache.
      Returns:
      true if this cache has been configured as a backup for a paged cache

    • setPassivePagedBackup

      protected void setPassivePagedBackup(boolean fPassiveBackup)
      Specify whether this is just a passive backup for a paged cache. A backup will not deactivate pages on its own, but simply waits for pages to empty and then destroys them as soon as they empty.
      Parameters:
      fPassiveBackup - true if this cache is just a backup for a paged cache

    • isAsynchronousPageDeactivation

      public boolean isAsynchronousPageDeactivation()
      Determine if a daemon should evict the items from a deactivated page to avoid blocking other work from being done.
      Returns:
      true if a daemon should be used for page deactivation

    • setAsynchronousPageDeactivation

      public void setAsynchronousPageDeactivation(boolean fAsync)
      Specify whether a daemon should evict the items from a deactivated page to avoid blocking other work from being done. The deactivation of a page involves evicting every entry from that page, so with a large page of data, it is possible that the cache would be "frozen" for a period of time while the entries are evicted (events being generated, etc.)

      This will not take effect until the next page is deactivated.

      Parameters:
      fAsync - pass true to specify that a daemon should be used for page deactivation, or false to block all other threads while a page is fully deactivated

    • isDebug

      public static boolean isDebug()
      Determine the status of the internal debug flag.
      Returns:
      true if the cache is in debug mode, false otherwise

    • setDebug

      public static void setDebug(boolean fDebug)
      Set the status of the internal debug flag.
      Parameters:
      fDebug - true to set the cache into debug mode, false to set it into normal runtime mode

    • lockInternal

      protected void lockInternal(Object oKey)
      Obtain a lock for the specified key.
      Parameters:
      oKey - the key to lock

    • lockInternalNoWait

      protected boolean lockInternalNoWait(Object oKey)
      Obtain a lock for the specified key, but only if no other thread has the lock at the point in time that this method is invoked.
      Parameters:
      oKey - the key to lock
      Returns:
      true if the lock was available and the key is now locked by this thread; false otherwise

    • unlockInternal

      protected void unlockInternal(Object oKey)
      Release the lock on the specified key.
      Parameters:
      oKey - the key to unlock

    • createBinaryStore

      protected BinaryStore createBinaryStore()
      Create and register a new BinaryStore object, using this cache's BinaryStoreManager.
      Returns:
      a new BinaryStore

    • destroyBinaryStore

      protected void destroyBinaryStore(BinaryStore store)
      Destroy and unregister a BinaryStore object that was previously created using this cache's BinaryStoreManager by the createBinaryStore method.
      Parameters:
      store - a BinaryStore returned previously from createBinaryStore

    • checkPage

      protected void checkPage()
      Determine if the time has come to set up a new page for storing current cache data. This potentially destroys the oldest page, if the maximum number of active pages has been reached.

    • advancePage

      protected void advancePage()
      Advance to a new current page, and deactivate the oldest page is the maximum number of active pages has been reached.

    • runTask

      protected void runTask(Runnable task)
      Run the passed task on a separate thread.
      Parameters:
      task - the Runnable object to run on a separate thread

    • deactivatePage

      protected void deactivatePage(SerializationPagedCache.WrapperBinaryStore store)
      Deactivate a page that is no longer active. This means expiring any remaining entries on that page. By splitting this method out, it makes it easier for sub-classes to provide this functionality in an asynchronous manner.
      Parameters:
      store - the "page" to deactivate

    • instantiatePagedStore

      protected SerializationPagedCache.PagedBinaryStore instantiatePagedStore(int cPages)
      Factory method: Instantiate a PagedBinaryStore.
      Parameters:
      cPages - the maximum number of pages to have active at a time
      Returns:
      a new PagedBinaryStore object

    • instantiateWrapperStore

      protected SerializationPagedCache.WrapperBinaryStore instantiateWrapperStore(BinaryStore store)
      Factory method: Instantiate a WrapperBinaryStore.
      Parameters:
      store - the BinaryStore to wrap
      Returns:
      a new WrapperBinaryStore object

    • instantiateFakeBinaryStore

      protected SerializationPagedCache.FakeBinaryStore instantiateFakeBinaryStore()
      Factory method: Instantiate a FakeBinaryStore.
      Returns:
      a new FakeBinaryStore object