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

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

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, 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.
Object	get(Object oKey) Returns the value to which this map maps the specified key.
protected 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 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 Iterator	iterateBinaryStores() Obtain an iterator of all registered (not destroyed) BinaryStore objects being used by this cache.
protected void	lockInternal(Object oKey) Obtain a lock for the specified key.
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.
Object	put(Object oKey, Object oValue) Associates the specified value with the specified key in this map.
void	putAll(Map map) Copies all of the mappings from the specified map to this map.
Object	remove(Object oKey) Removes the mapping for this key from this map if present.
protected boolean	removeBlind(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(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.
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(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,
                               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

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