Skip navigation links

Oracle® Coherence Java API Reference
Release 3.7.0.0

E18683-01


com.tangosol.net.cache
Class SerializationPagedCache

java.lang.Object
  extended by com.tangosol.util.Base
      extended by com.tangosol.util.AbstractKeyBasedMap
          extended by com.tangosol.util.AbstractKeySetBasedMap
              extended by com.tangosol.net.cache.SerializationMap
                  extended by com.tangosol.net.cache.AbstractSerializationCache
                      extended by 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.
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.
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, instantiateKeyMap, 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

Oracle® Coherence Java API Reference
Release 3.7.0.0

E18683-01


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