Package com.tangosol.net.cache

Class 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 Detail

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

      • 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

      • 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

      • 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

      • 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