Skip navigation links

Overview | Package | Class | Tree | Index | Help
| Oracle® Coherence Java API Reference Release 3.6.1.0 E18814-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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, java.util.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

Nested Class Summary
`static class` | `SerializationPagedCache.FakeBinaryStore` A lite BinaryStore implementation used when the real underlying BinaryStore gets destroyed.
`class` | `SerializationPagedCache.PagedBinaryStore` A virtual BinaryStore implementation that aggregates a sequence (newest to oldest) of periodic BinaryStore objects.
`class` | `SerializationPagedCache.WrapperBinaryStore` A wrapper BinaryStore implementation that keeps track of its size.

Nested classes/interfaces inherited from class com.tangosol.util.AbstractKeySetBasedMap
`AbstractKeySetBasedMap.EntrySet, AbstractKeySetBasedMap.KeyIterator, AbstractKeySetBasedMap.KeySet, AbstractKeySetBasedMap.ValuesCollection`

Nested classes/interfaces inherited from interface java.util.Map
`java.util.Map.Entry`

Constructor Summary
`SerializationPagedCache(BinaryStoreManager storemgr, int cPages, int cPageSecs)` Construct a SerializationPagedCache on top of a BinaryStoreManager.
`SerializationPagedCache(BinaryStoreManager storemgr, int cPages, int cPageSecs, boolean fBinaryMap, boolean fPassive)` Construct a SerializationPagedCache on top of a BinaryStoreManager.
`SerializationPagedCache(BinaryStoreManager storemgr, int cPages, int cPageSecs, java.lang.ClassLoader loader)` Construct a SerializationPagedCache on top of a BinaryStoreManager.

Method Summary
`protected void` | `advancePage()` Advance to a new current page, and deactivate the oldest page is the maximum number of active pages has been reached.
`protected void` | `checkPage()` Determine if the time has come to set up a new page for storing current cache data.
`void` | `clear()` Clear all key/value mappings.
`protected BinaryStore` | `createBinaryStore()` Create and register a new BinaryStore object, using this cache's BinaryStoreManager.
`protected void` | `deactivatePage(SerializationPagedCache.WrapperBinaryStore store)` Deactivate a page that is no longer active.
`protected void` | `destroyBinaryStore(BinaryStore store)` Destroy and unregister a BinaryStore object that was previously created using this cache's BinaryStoreManager by the createBinaryStore method.
`protected void` | `eraseStore()` Erase all entries from the underlying store.
`void` | `evict()` Flush items that have expired.
`java.lang.Object` | `get(java.lang.Object oKey)` Returns the value to which this map maps the specified key.
`protected java.util.List` | `getBinaryStoreList()` Get the list of registered BinaryStore objects.
`protected BinaryStoreManager` | `getBinaryStoreManager()` Returns the BinaryStoreManager that provides BinaryStore objects this cache uses for its storage.
`XmlElement` | `getConfig()` Determine the current configuration of the object.
`protected long` | `getCurrentPageTime()` Determine the time that the current page was created.
`protected java.lang.String` | `getDescription()` Assemble a human-readable description.
`int` | `getLockDelaySeconds()` Determine the number of seconds to wait for a lock in debug mode.
`protected ConcurrentMap` | `getLockMap()` Obtain the map used for managing key- and map-level locks to ensure data consistency.
`int` | `getMaximumPages()` Determine the maximum number of pages that the cache will manage, beyond which the oldest pages are destroyed.
`protected long` | `getPageAdvanceTime()` Determine the time that the next page should be created.
`protected SerializationPagedCache.PagedBinaryStore` | `getPagedBinaryStore()` Returns the BinaryStore that this map uses for its storage.
`long` | `getPageDuration()` Determine the length of time that the most recently created page is kept as the current page.
`protected SerializationPagedCache.FakeBinaryStore` | `instantiateFakeBinaryStore()` Factory method: Instantiate a FakeBinaryStore.
`protected SerializationPagedCache.PagedBinaryStore` | `instantiatePagedStore(int cPages)` Factory method: Instantiate a PagedBinaryStore.
`protected SerializationPagedCache.WrapperBinaryStore` | `instantiateWrapperStore(BinaryStore store)` Factory method: Instantiate a WrapperBinaryStore.
`boolean` | `isAsynchronousPageDeactivation()` Determine if a daemon should evict the items from a deactivated page to avoid blocking other work from being done.
`static boolean` | `isDebug()` Determine the status of the internal debug flag.
`boolean` | `isPassivePagedBackup()` Determine if this is just a passive backup for a paged cache.
`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.)
`protected java.util.Iterator` | `iterateBinaryStores()` Obtain an iterator of all registered (not destroyed) BinaryStore objects being used by this cache.
`protected void` | `lockInternal(java.lang.Object oKey)` Obtain a lock for the specified key.
`protected boolean` | `lockInternalNoWait(java.lang.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.
`java.lang.Object` | `put(java.lang.Object oKey, java.lang.Object oValue)` Associates the specified value with the specified key in this map.
`void` | `putAll(java.util.Map map)` Copies all of the mappings from the specified map to this map.
`java.lang.Object` | `remove(java.lang.Object oKey)` Removes the mapping for this key from this map if present.
`protected boolean` | `removeBlind(java.lang.Object oKey)` Removes the mapping for this key from this map if present. This method exists to allow sub-classes to optmiize remove functionalitly for situations in which the original value is not required.
`protected void` | `runTask(java.lang.Runnable task)` Run the passed task on a separate thread.
`void` | `setAsynchronousPageDeactivation(boolean fAsync)` Specify whether a daemon should evict the items from a deactivated page to avoid blocking other work from being done.
`protected void` | `setBinaryStore(BinaryStore store)` Configures the BinaryStore that this map will use for its storage.
`void` | `setConfig(XmlElement xml)` Specify the configuration for the object.
`static void` | `setDebug(boolean fDebug)` Set the status of the internal debug flag.
`void` | `setLockDelaySeconds(int cSecondsLockDelay)` Specify the number of seconds to wait for a lock in debug mode.
`protected void` | `setPageDuration(long cPageMillis)` Specify the length of time that the most recently created page is kept as the current page.
`protected void` | `setPassivePagedBackup(boolean fPassiveBackup)` Specify whether this is just a passive backup for a paged cache.
`protected void` | `setVirtualErase(boolean fVirtualErase)` Specify whether BinaryStore erase commands will be done only in memory to the cached list of keys.
`java.lang.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)`.
`protected void` | `unlockInternal(java.lang.Object oKey)` Release the lock on the specified key.

Methods inherited from class com.tangosol.net.cache.AbstractSerializationCache
`addMapListener, addMapListener, addMapListener, dispatchEvent, dispatchPendingEvent, getMapListenerSupport, hasListeners, removeMapListener, removeMapListener, removeMapListener`

Methods inherited from class com.tangosol.net.cache.SerializationMap
`containsValue, fromBinary, getBinaryStore, getCacheStatistics, getClassLoader, getInternalKeySet, getKeyMap, isBinaryMap, registerKey, setBinaryMap, setClassLoader, toBinary, unregisterKey`

Methods inherited from class com.tangosol.util.AbstractKeySetBasedMap
`containsKey, instantiateEntrySet, instantiateKeyIterator, instantiateKeySet, instantiateValues, isEmpty, isInternalKeySetIteratorMutable, iterateKeys, size`

Methods inherited from class com.tangosol.util.AbstractKeyBasedMap
`clone, entrySet, equals, getAll, hashCode, keySet, values`

Methods inherited from interface java.util.Map
`containsKey, containsValue, entrySet, equals, hashCode, isEmpty, keySet, size, values`

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,
                                   java.lang.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:
    `java.lang.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 `java.util.Map`
  Overrides:
    `clear` in class `AbstractSerializationCache`

### get

    public java.lang.Object get(java.lang.Object oKey)

  Returns the value to which this map maps the specified key.
  Specified by:
    `get` in interface `java.util.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
  See Also:
    `Map.containsKey(Object)`

### put

    public java.lang.Object put(java.lang.Object oKey,
                                java.lang.Object oValue)

  Associates the specified value with the specified key in this map.
  Specified by:
    `put` in interface `java.util.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(java.util.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 `java.util.Map`
  Overrides:
    `putAll` in class `AbstractSerializationCache`
  Parameters:
    `map` - map of entries to be stored in this map

### remove

    public java.lang.Object remove(java.lang.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 `java.util.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(java.lang.Object oKey)

  Removes the mapping for this key from this map if present. This method exists to allow sub-classes to optmiize remove functionalitly 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 java.lang.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 java.lang.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 java.util.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 java.util.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(java.lang.Object oKey)

  Obtain a lock for the specified key.
  Parameters:
    `oKey` - the key to lock

### lockInternalNoWait

    protected boolean lockInternalNoWait(java.lang.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(java.lang.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(java.lang.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

Skip navigation links

Overview | Package | Class | Tree | Index | Help
| Oracle® Coherence Java API Reference Release 3.6.1.0 E18814-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.