CoherenceTM v3.3
Copyright© 2000-2007 by Oracle Corporation

com.tangosol.net.cache
Class ReadWriteBackingMap

java.lang.Object
  extended by java.util.AbstractMap
      extended by com.tangosol.net.cache.ReadWriteBackingMap
All Implemented Interfaces:
ObservableMap, Map
Direct Known Subclasses:
VersionedBackingMap

public class ReadWriteBackingMap
extends AbstractMap
implements ObservableMap

Backing Map implementation that provides a size-limited cache of a persistent store and supports configurable write-behind and refresh- ahead caching. This implementation is not intended to support null keys or null values.

Author:
cp 2002.11.25, jh 2005.02.08

Nested Class Summary
 class ReadWriteBackingMap.CacheLoaderCacheStore
          A CacheStore wrapped around a CacheLoader.
 class ReadWriteBackingMap.CacheStoreWrapper
          A wrapper around the original CacheStore to allow operations to be overridden and extended.
protected  class ReadWriteBackingMap.EntrySet
          A set of entries corresponding to this backing map.
protected  class ReadWriteBackingMap.InternalMapListener
          A MapListener implementation that listens to the internal cache and routes those events to anyone listening to this ReadWriteBackingMap.
protected  class ReadWriteBackingMap.KeySet
          A set of entries backed by this backing map.
protected  class ReadWriteBackingMap.ReadLatch
          A synchronization construct used to coordinate asynchronous loads by the refresh-ahead thread with cache accesses by other threads.
 class ReadWriteBackingMap.ReadQueue
          A queue of keys that should be read from the underlying CacheStore.
 class ReadWriteBackingMap.ReadThread
          A thread that removes keys from a ReadWriteBackingMap.ReadQueue, reads the value for the key from the underlying CacheStore, and caches the value in the internal ReadWriteBackingMap cache.
protected  class ReadWriteBackingMap.ValuesCollection
          A collection of values backed by this map.
 class ReadWriteBackingMap.WriteQueue
          A queue that only releases entries after a configurable period of time.
 class ReadWriteBackingMap.WriteThread
          This is the write-behind thread that pulls things from the write-behind queue and writes them to the CacheStore that the backing map uses.
 
Nested classes/interfaces inherited from interface java.util.Map
Map.Entry
 
Field Summary
protected  MapListenerSupport m_listenerSupport
          MapListenerSupport object.
protected static Object NO_VALUE
          Marker object used to indicate to the write-behind thread that an entry has been removed from the queue.
 
Constructor Summary
ReadWriteBackingMap(BackingMapManagerContext ctxService, ObservableMap mapInternal, Map mapMisses, CacheLoader loader)
          Construct a ReadWriteBackingMap using a CacheLoader object.
ReadWriteBackingMap(BackingMapManagerContext ctxService, ObservableMap mapInternal, Map mapMisses, CacheStore store, boolean fReadOnly, int cWriteBehindSeconds)
          Construct a ReadWriteBackingMap.
ReadWriteBackingMap(BackingMapManagerContext ctxService, ObservableMap mapInternal, Map mapMisses, CacheStore store, boolean fReadOnly, int cWriteBehindSeconds, double dflRefreshAheadFactor)
          Construct a ReadWriteBackingMap.
 
Method Summary
 void addMapListener(MapListener listener)
          Add a standard map listener.
 void addMapListener(MapListener listener, Filter filter, boolean fLite)
          Add a map listener that receives events based on a filter evaluation.
 void addMapListener(MapListener listener, Object oKey, boolean fLite)
          Add a map listener for a specific key.
 void clear()
          Remove everything from the Map.
protected  void configureCacheStore(CacheStore store, boolean fReadOnly)
          Set up the CacheStore that this backing map will use.
protected  void configureInternalCache(ObservableMap mapInternal)
          Configure the internal cache that this backing map uses to store its "in-memory" data.
protected  void configureReadThread(double dflRefreshAheadFactor)
          Set up the optional refresh-ahead thread and queue that this backing map will use.
protected  void configureWriteThread(int cWriteBehindSeconds)
          Set up the optional write-behind thread and queue that this backing map will use.
 boolean containsKey(Object oKey)
          Returns true if this map contains a mapping for the specified key.
 boolean containsValue(Object oValue)
          Returns true if this CachingMap maps one or more keys to the specified value.
 Set entrySet()
          Returns an set view of the mappings contained in this map.
 boolean equals(Object o)
          Compares the specified object with this map for equality.
 void flush()
          Flush the write-behind queue, writing everything immediately.
protected  void flush(ReadWriteBackingMap.WriteQueue queue, ReadWriteBackingMap.CacheStoreWrapper store)
          Flush the write-behind queue, writing everything immediately.
 Object get(Object oKey)
          Returns the value to which this map maps the specified key.
 ReadWriteBackingMap.CacheStoreWrapper getCacheStore()
          Get the representative of the "persistent" storage for this backing map.
 BackingMapManagerContext getContext()
          Get the context information provided by the CacheService.
 ConcurrentMap getControlMap()
          Get the concurrency control map for this backing map.
 ObservableMap getInternalCache()
          Get the representative of the "in-memory" storage for this backing map.
protected  MapListener getInternalListener()
          Obtain the MapListener that listens to the internal cache and routes those events to anyone listening to this ReadWriteBackingMap, creating such a listener if one does not already exist.
protected  LocalCache getInternalLocalCache()
          Get the LocalCache for this backing map.
 Map getMissesCache()
          Get the optional map used to cache CacheLoader (or CacheStore) misses.
 ReadWriteBackingMap.ReadQueue getReadQueue()
          Get the queue of keys that are yet to be read.
protected  ReadWriteBackingMap.ReadThread getReadThread()
          Get the refresh-ahead thread.
 double getRefreshAheadFactor()
          Return the refresh-ahead factor.
protected  Map getSyntheticEventsMap()
          Get the map of keys for which the events should be marked as synthetic (internal).
 double getWriteBatchFactor()
          Return the write-batch factor.
 int getWriteBehindSeconds()
          Return the number of seconds between write-behind writes to the CacheStore or 0 if write-behind is not enabled.
 ReadWriteBackingMap.WriteQueue getWriteQueue()
          Get the queue of entries that are yet to be written.
 int getWriteRequeueThreshold()
          Return the maximum size of the write-behind queue for which failed CacheStore write operations are requeued or 0 if write-behind requeueing is disabled.
protected  ReadWriteBackingMap.WriteThread getWriteThread()
          Get the write-behind thread.
 int hashCode()
          Returns the hash code value for this map.
protected  ReadWriteBackingMap.CacheLoaderCacheStore instantiateCacheLoaderCacheStore(CacheLoader loader)
          Factory pattern: Instantiate a CacheLoaderCacheStore wrapper around a passed CacheLoader.
protected  ReadWriteBackingMap.CacheStoreWrapper instantiateCacheStoreWrapper(CacheStore store)
          Factory pattern: Instantiate a CacheStore wrapper around the passed CacheStore.
protected  ConcurrentMap instantiateControlMap()
          Factory pattern: Create the concurrency control map for this backing map.
protected  ReadWriteBackingMap.EntrySet instantiateEntrySet()
          Factory pattern: instantiate an entry set for this backing map.
protected  MapListener instantiateInternalListener()
          Factory pattern: Create a MapListener that listens to the internal cache and routes those events to anyone listening to this ReadWriteBackingMap.
protected  ReadWriteBackingMap.KeySet instantiateKeySet()
          Factory pattern: instantiate a key set for this backing map.
protected  ReadWriteBackingMap.ReadLatch instantiateReadLatch(Object oKey)
          Factory pattern: Instantiate a new read latch the given key.
protected  ReadWriteBackingMap.ReadQueue instantiateReadQueue()
          Factory pattern: Instantiate a new ReadQueue object.
protected  ReadWriteBackingMap.ReadThread instantiateReadThread()
          Factory pattern: Instantiate the refresh-ahead thread.
protected  ReadWriteBackingMap.ValuesCollection instantiateValuesCollection()
          Factory pattern.
protected  ReadWriteBackingMap.WriteQueue instantiateWriteQueue()
          Factory pattern: Instantiate a new WriteQueue object.
protected  ReadWriteBackingMap.WriteThread instantiateWriteThread()
          Factory pattern: Instantiate the write-behind thread.
 boolean isActive()
          Determine if the backing map is still active.
 boolean isReadOnly()
          Determine if the backing map should send data changes through the CacheStore, or should just keep them in memory.
 boolean isRefreshAhead()
          Determine if the backing map preemptively reads soon-to-be expired entries on a refresh-ahead thread.
 boolean isRethrowExceptions()
          Determine if exceptions caught during synchronous CacheStore operations are rethrown to the calling thread; if false, exceptions are logged.
 boolean isWriteBehind()
          Determine if the backing map writes changes on a write-behind thread through the CacheStore.
 boolean isWriteThrough()
          Determine if the backing map writes changes immediately through the CacheStore.
 Set keySet()
          Returns an set view of the keys contained in this map.
 Object put(Object oKey, Object oValue)
          Associates the specified value with the specified key in this map.
 void release()
          Release the backing map when it is no longer being used.
 Object remove(Object oKey)
          Removes the mapping for this key from this map if present.
 void removeMapListener(MapListener listener)
          Remove a standard map listener.
 void removeMapListener(MapListener listener, Filter filter)
          Remove a map listener that previously signed up for events based on a filter evaluation.
 void removeMapListener(MapListener listener, Object oKey)
          Remove a map listener that previously signed up for events about a specific key.
 void setRefreshAheadFactor(double dflRefreshAheadFactor)
          Set the refresh-ahead factor, expressed as a percentage of the internal LocalCache expiration interval.
 void setRethrowExceptions(boolean fRethrow)
          Set the value of the flag that determines if exceptions caught during synchronous CacheStore operations are rethrown to the calling thread; if false, exceptions are logged.
 void setWriteBatchFactor(double dflWriteBatchFactor)
          Set the write-batch factor, expressed as a percentage of the write-behind interval.
 void setWriteBehindSeconds(int cSecs)
          Set the number of seconds between write-behind writes to the CacheStore.
 void setWriteRequeueThreshold(int cThreshold)
          Set the maximum size of the write-behind queue for which failed CacheStore write operations are requeued.
 int size()
          Returns the number of key-value mappings in this map.
protected  void terminateReadThread()
          Terminate the refresh-ahead thread.
protected  void terminateWriteThread()
          Terminate the write-behind thread.
 String toString()
          For debugging purposes, format the contents of the Map in a human- readable format.
protected  void updateOnGet(Map.Entry entryReal)
          Deprecated. as of Coherence 3.2 this method is never called
protected  void updateOnPut(Map.Entry entryReal)
          Deprecated. as of Coherence 3.2 this method is never called
 Collection values()
          Returns a collection view of the values contained in this map.
 
Methods inherited from class java.util.AbstractMap
clone, isEmpty, putAll
 
Methods inherited from interface java.util.Map
isEmpty, putAll
 

Field Detail

NO_VALUE

protected static final Object NO_VALUE
Marker object used to indicate to the write-behind thread that an entry has been removed from the queue.


m_listenerSupport

protected MapListenerSupport m_listenerSupport
MapListenerSupport object.

Constructor Detail

ReadWriteBackingMap

public ReadWriteBackingMap(BackingMapManagerContext ctxService,
                           ObservableMap mapInternal,
                           Map mapMisses,
                           CacheLoader loader)
Construct a ReadWriteBackingMap using a CacheLoader object.

Parameters:
ctxService - the context provided by the CacheService which is using this backing map
mapInternal - the ObservableMap used to store the data internally in this backing map
mapMisses - the Map used to cache CacheLoader misses (optional)
loader - the CacheLoader object to use (optional)

ReadWriteBackingMap

public ReadWriteBackingMap(BackingMapManagerContext ctxService,
                           ObservableMap mapInternal,
                           Map mapMisses,
                           CacheStore store,
                           boolean fReadOnly,
                           int cWriteBehindSeconds)
Construct a ReadWriteBackingMap.

Parameters:
ctxService - the context provided by the CacheService which is using this backing map
mapInternal - the ObservableMap used to store the data internally in this backing map
mapMisses - the Map used to cache CacheStore misses (optional)
store - the object responsible for the persistence of the cached data (optional)
fReadOnly - pass true to use the CacheStore only for read operations; changes to the cache will not be persisted
cWriteBehindSeconds - number of seconds to write if there is a CacheStore; zero disables write-behind caching, which (combined with !fReadOnly) implies write-through

ReadWriteBackingMap

public ReadWriteBackingMap(BackingMapManagerContext ctxService,
                           ObservableMap mapInternal,
                           Map mapMisses,
                           CacheStore store,
                           boolean fReadOnly,
                           int cWriteBehindSeconds,
                           double dflRefreshAheadFactor)
Construct a ReadWriteBackingMap.

Parameters:
ctxService - the context provided by the CacheService which is using this backing map
mapInternal - the ObservableMap used to store the data internally in this backing map
mapMisses - the Map used to cache CacheStore misses (optional)
store - the object responsible for the persistence of the cached data (optional)
fReadOnly - pass true to use the CacheStore only for read operations; changes to the cache will not be persisted
cWriteBehindSeconds - number of seconds to write if there is a CacheStore; zero disables write-behind caching, which (combined with !fReadOnly) implies write-through
dflRefreshAheadFactor - the interval before an entry expiration time (expressed as a percentage of the internal cache expiration interval) during which an asynchronous load request for the entry will be scheduled; zero disables refresh-ahead; only applicable when the mapInternal parameter is an instance of LocalCache
Method Detail

getContext

public BackingMapManagerContext getContext()
Get the context information provided by the CacheService.

Returns:
the CacheService's BackingMapManagerContext object that it provided to the BackingMapManager that created this backing map

isRethrowExceptions

public boolean isRethrowExceptions()
Determine if exceptions caught during synchronous CacheStore operations are rethrown to the calling thread; if false, exceptions are logged.

Returns:
true if CacheStore exceptions are rethrown to the calling thread

setRethrowExceptions

public void setRethrowExceptions(boolean fRethrow)
Set the value of the flag that determines if exceptions caught during synchronous CacheStore operations are rethrown to the calling thread; if false, exceptions are logged.

Parameters:
fRethrow - true to indicate that exceptions should be rethrown

getRefreshAheadFactor

public double getRefreshAheadFactor()
Return the refresh-ahead factor.

The refresh-ahead factor is used to calculate the "soft-expiration" time for cache entries. Soft-expiration is the point in time prior to the actual expiration after which any access request for an entry will schedule an asynchronous load request for the entry.

The value of this property is expressed as a percentage of the internal LocalCache expiration interval. If zero, refresh-ahead scheduling is disabled.

Returns:
the refresh-ahead factor

setRefreshAheadFactor

public void setRefreshAheadFactor(double dflRefreshAheadFactor)
Set the refresh-ahead factor, expressed as a percentage of the internal LocalCache expiration interval. Valid values are doubles in the interval [0.0, 1.0].

This method has no effect if refresh-ahead is disabled.

Parameters:
dflRefreshAheadFactor - the new refresh-ahead factor
See Also:
getRefreshAheadFactor()

isReadOnly

public boolean isReadOnly()
Determine if the backing map should send data changes through the CacheStore, or should just keep them in memory.

Returns:
false to send changes to CacheStore (a read-write cache), or true to just keep them in memory (a read-only cache)

isRefreshAhead

public boolean isRefreshAhead()
Determine if the backing map preemptively reads soon-to-be expired entries on a refresh-ahead thread.

Returns:
true if refresh-ahead is enabled

getWriteBatchFactor

public double getWriteBatchFactor()
Return the write-batch factor.

The write-batch factor is used to calculate the "soft-ripe" time for write-behind queue entries. A queue entry is considered to be "ripe" for a write operation if it has been in the write-behind queue for no less than the write-behind interval. The "soft-ripe" time is the point in time prior to the actual ripe time after which an entry will be included in a batched asynchronous write operation to the CacheStore (along with all other ripe and soft-ripe entries). In other words, a soft-ripe entry is an entry that has been in the write-behind queue for at least the following duration:

 D' = (1.0 - F)*D
where:
 D = write-behind delay
 F = write-batch factor
Conceptually, the write-behind thread uses the following logic when performing a batched update:

  1. The thread waits for a queued entry to become ripe.
  2. When an entry becomes ripe, the thread dequeues all ripe and soft-ripe entries in the queue.
  3. The thread then writes all ripe and soft-ripe entries either via store() (if there is only the single ripe entry) or storeAll() (if there are multiple ripe/soft-ripe entries).
  4. The thread then repeats (1).

This property is only applicable if asynchronous writes are enabled and the CacheStore implements the storeAll() method.

The value of this property is expressed as a percentage of the write-behind interval. Valid values are doubles in the interval [0.0, 1.0].

Returns:
the write-batch factor

setWriteBatchFactor

public void setWriteBatchFactor(double dflWriteBatchFactor)
Set the write-batch factor, expressed as a percentage of the write-behind interval. Valid values are doubles in the interval [0.0, 1.0].

This method has no effect if write-behind is disabled.

Parameters:
dflWriteBatchFactor - the new write-batch factor
See Also:
getWriteBatchFactor()

isWriteBehind

public boolean isWriteBehind()
Determine if the backing map writes changes on a write-behind thread through the CacheStore.

Returns:
true implies changes are queued to be written asynchronously

getWriteBehindSeconds

public int getWriteBehindSeconds()
Return the number of seconds between write-behind writes to the CacheStore or 0 if write-behind is not enabled.

Returns:
the number of seconds between write-behind writes

setWriteBehindSeconds

public void setWriteBehindSeconds(int cSecs)
Set the number of seconds between write-behind writes to the CacheStore.

This method has not effect if write-behind is not enabled.

Parameters:
cSecs - the new write-behind delay in seconds

getWriteRequeueThreshold

public int getWriteRequeueThreshold()
Return the maximum size of the write-behind queue for which failed CacheStore write operations are requeued or 0 if write-behind requeueing is disabled.

Returns:
the write-behind requeue threshold

setWriteRequeueThreshold

public void setWriteRequeueThreshold(int cThreshold)
Set the maximum size of the write-behind queue for which failed CacheStore write operations are requeued.

This method has not effect if write-behind is not enabled.

Parameters:
cThreshold - the new write-behind requeue threshold

isWriteThrough

public boolean isWriteThrough()
Determine if the backing map writes changes immediately through the CacheStore.

Returns:
true implies that changes to the backing map are written synchronously to the CacheStore

clear

public void clear()
Remove everything from the Map.

Specified by:
clear in interface Map
Overrides:
clear in class AbstractMap

containsKey

public boolean containsKey(Object oKey)
Returns true if this map contains a mapping for the specified key.

Specified by:
containsKey in interface Map
Overrides:
containsKey in class AbstractMap
Parameters:
oKey - the key to test for
Returns:
true if this map contains a mapping for the specified key, false otherwise.

containsValue

public boolean containsValue(Object oValue)
Returns true if this CachingMap maps one or more keys to the specified value.

Specified by:
containsValue in interface Map
Overrides:
containsValue in class AbstractMap
Parameters:
oValue - the value to test for
Returns:
true if this CachingMap maps one or more keys to the specified value, false otherwise

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 AbstractMap
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 AbstractMap
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. A null return can also indicate that the map previously associated null with the specified key, if the implementation supports null values.

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

size

public int size()
Returns the number of key-value mappings in this map. If the map contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Specified by:
size in interface Map
Overrides:
size in class AbstractMap
Returns:
the number of key-value mappings in this map

entrySet

public Set entrySet()
Returns an set view of the mappings contained in this map.

Specified by:
entrySet in interface Map
Specified by:
entrySet in class AbstractMap
Returns:
a set view of the mappings contained in this map

keySet

public Set keySet()
Returns an set view of the keys contained in this map.

Specified by:
keySet in interface Map
Overrides:
keySet in class AbstractMap
Returns:
a set view of the keys contained in this map

values

public Collection values()
Returns a collection view of the values contained in this map.

Specified by:
values in interface Map
Overrides:
values in class AbstractMap
Returns:
a collection view of the values contained in this map

updateOnGet

protected void updateOnGet(Map.Entry entryReal)
Deprecated. as of Coherence 3.2 this method is never called

Update any relevant data based on the value that has just been loaded from the store as a result of the "get" operation. This method is called while the entry is locked and intended to be overriden by subclasses.


updateOnPut

protected void updateOnPut(Map.Entry entryReal)
Deprecated. as of Coherence 3.2 this method is never called

Update any relevant data based on the value that is about to be written to the store or queued for write and owned by this context. This method is called while the entry is locked and intended to be overriden by subclasses.


instantiateEntrySet

protected ReadWriteBackingMap.EntrySet instantiateEntrySet()
Factory pattern: instantiate an entry set for this backing map.

Returns:
a new EntrySet object

instantiateKeySet

protected ReadWriteBackingMap.KeySet instantiateKeySet()
Factory pattern: instantiate a key set for this backing map.

Returns:
a new KeySet object

instantiateValuesCollection

protected ReadWriteBackingMap.ValuesCollection instantiateValuesCollection()
Factory pattern.

Returns:
a new instance of the ValuesCollection class (or subclass thereof)

addMapListener

public void addMapListener(MapListener listener)
Add a standard map listener.

Specified by:
addMapListener in interface ObservableMap
Parameters:
listener - the MapEvent listener to add

removeMapListener

public void removeMapListener(MapListener listener)
Remove a standard map listener.

Specified by:
removeMapListener in interface ObservableMap
Parameters:
listener - the listener to remove

addMapListener

public void addMapListener(MapListener listener,
                           Object oKey,
                           boolean fLite)
Add a map listener for a specific key.

Specified by:
addMapListener in interface ObservableMap
Parameters:
listener - the listener to add
oKey - the key that identifies the entry for which to raise events
fLite - true to indicate that the MapEvent objects do not have to include the OldValue and NewValue property values in order to allow optimizations
Since:
Coherence 2.3

removeMapListener

public void removeMapListener(MapListener listener,
                              Object oKey)
Remove a map listener that previously signed up for events about a specific key.

Specified by:
removeMapListener in interface ObservableMap
Parameters:
listener - the listener to remove
oKey - the key that identifies the entry for which to raise events
Since:
Coherence 2.3

addMapListener

public void addMapListener(MapListener listener,
                           Filter filter,
                           boolean fLite)
Add a map listener that receives events based on a filter evaluation.

Specified by:
addMapListener in interface ObservableMap
Parameters:
listener - the listener to add
filter - a filter that will be passed MapEvent objects to select from; a MapEvent will be delivered to the listener only if the filter evaluates to true for that MapEvent; null is equivalent to a filter that alway returns true
fLite - true to indicate that the MapEvent objects do not have to include the OldValue and NewValue property values in order to allow optimizations
Since:
Coherence 2.3

removeMapListener

public void removeMapListener(MapListener listener,
                              Filter filter)
Remove a map listener that previously signed up for events based on a filter evaluation.

Specified by:
removeMapListener in interface ObservableMap
Parameters:
listener - the listener to remove
filter - a filter used to evaluate events
Since:
Coherence 2.3

equals

public boolean equals(Object o)
Compares the specified object with this map for equality. Returns true if the given object is also a map and the two maps represent the same mappings.

Specified by:
equals in interface Map
Overrides:
equals in class AbstractMap
Parameters:
o - object to be compared for equality with this map
Returns:
true if the specified object is equal to this map

hashCode

public int hashCode()
Returns the hash code value for this map.

Specified by:
hashCode in interface Map
Overrides:
hashCode in class AbstractMap
Returns:
the hash code value for this map

toString

public String toString()
For debugging purposes, format the contents of the Map in a human- readable format.

Overrides:
toString in class AbstractMap
Returns:
a String representation of the Map object

getInternalCache

public ObservableMap getInternalCache()
Get the representative of the "in-memory" storage for this backing map.

Returns:
the ObservableMap object (never null) that this backing map uses to store entries

getInternalLocalCache

protected LocalCache getInternalLocalCache()
Get the LocalCache for this backing map. If refresh-ahead is enabled, this accessor returns the same reference as getInternalCache(); otherwise, it returns null.

Returns:
the LocalCache for this backing map or null if refresh-ahead is not enabled

configureInternalCache

protected void configureInternalCache(ObservableMap mapInternal)
Configure the internal cache that this backing map uses to store its "in-memory" data.


getMissesCache

public Map getMissesCache()
Get the optional map used to cache CacheLoader (or CacheStore) misses.

Returns:
the Map that this backing map uses to cache CacheLoader (or CacheStore) misses or null if misses are not cached

getControlMap

public ConcurrentMap getControlMap()
Get the concurrency control map for this backing map.

Returns:
the ObservableMap object (never null) that this backing map uses to store entries

instantiateControlMap

protected ConcurrentMap instantiateControlMap()
Factory pattern: Create the concurrency control map for this backing map.

Returns:
a new concurrency control map

getSyntheticEventsMap

protected Map getSyntheticEventsMap()
Get the map of keys for which the events should be marked as synthetic (internal).

Returns:
the map of keys to mark events as internal

getInternalListener

protected MapListener getInternalListener()
Obtain the MapListener that listens to the internal cache and routes those events to anyone listening to this ReadWriteBackingMap, creating such a listener if one does not already exist.

Returns:
a routing MapListener

instantiateInternalListener

protected MapListener instantiateInternalListener()
Factory pattern: Create a MapListener that listens to the internal cache and routes those events to anyone listening to this ReadWriteBackingMap.

Returns:
a new routing MapListener

release

public void release()
Release the backing map when it is no longer being used.


isActive

public boolean isActive()
Determine if the backing map is still active.

Returns:
true if the backing map is still active

instantiateReadLatch

protected ReadWriteBackingMap.ReadLatch instantiateReadLatch(Object oKey)
Factory pattern: Instantiate a new read latch the given key.


getReadQueue

public ReadWriteBackingMap.ReadQueue getReadQueue()
Get the queue of keys that are yet to be read.

Returns:
the refresh-ahead queue object

instantiateReadQueue

protected ReadWriteBackingMap.ReadQueue instantiateReadQueue()
Factory pattern: Instantiate a new ReadQueue object.

Returns:
a new ReadQueue object

getWriteQueue

public ReadWriteBackingMap.WriteQueue getWriteQueue()
Get the queue of entries that are yet to be written.

Returns:
the write-behind queue object

flush

public void flush()
Flush the write-behind queue, writing everything immediately.


flush

protected void flush(ReadWriteBackingMap.WriteQueue queue,
                     ReadWriteBackingMap.CacheStoreWrapper store)
Flush the write-behind queue, writing everything immediately.

Parameters:
queue - the write-behind queue to flush
store - the CacheStore to flush to

instantiateWriteQueue

protected ReadWriteBackingMap.WriteQueue instantiateWriteQueue()
Factory pattern: Instantiate a new WriteQueue object.

Returns:
a new WriteQueue object

getReadThread

protected ReadWriteBackingMap.ReadThread getReadThread()
Get the refresh-ahead thread.

Returns:
the refresh-ahead thread or null if refresh-ahead is not enabled

configureReadThread

protected void configureReadThread(double dflRefreshAheadFactor)
Set up the optional refresh-ahead thread and queue that this backing map will use.

This method has no effect if the given refresh-ahead factor is zero or the LocalCache returned by getInternalLocalCache() is null or non-expiring.

Parameters:
dflRefreshAheadFactor - the refresh-ahead factor expressed as a percentage of the internal cache expiry

instantiateReadThread

protected ReadWriteBackingMap.ReadThread instantiateReadThread()
Factory pattern: Instantiate the refresh-ahead thread.

Returns:
a new refresh-ahead thread

terminateReadThread

protected void terminateReadThread()
Terminate the refresh-ahead thread.


getWriteThread

protected ReadWriteBackingMap.WriteThread getWriteThread()
Get the write-behind thread.

Returns:
the write-behind thread or null if there is no CacheStore to write to

configureWriteThread

protected void configureWriteThread(int cWriteBehindSeconds)
Set up the optional write-behind thread and queue that this backing map will use.

This method has no effect if the given write-behind delay is zero or isReadOnly() returns true.

Parameters:
cWriteBehindSeconds - write-behind delay

instantiateWriteThread

protected ReadWriteBackingMap.WriteThread instantiateWriteThread()
Factory pattern: Instantiate the write-behind thread.

Returns:
a new write-behind thread

terminateWriteThread

protected void terminateWriteThread()
Terminate the write-behind thread.


getCacheStore

public ReadWriteBackingMap.CacheStoreWrapper getCacheStore()
Get the representative of the "persistent" storage for this backing map.

Returns:
the CacheStore object that this backing map uses for persistence or null if there is no persistent store behind this backing map

configureCacheStore

protected void configureCacheStore(CacheStore store,
                                   boolean fReadOnly)
Set up the CacheStore that this backing map will use.

Parameters:
store - the CacheStore that this backing map will delegate persistence responsibilities to
fReadOnly - pass true to prevent the usage of the CacheStore write operations

instantiateCacheStoreWrapper

protected ReadWriteBackingMap.CacheStoreWrapper instantiateCacheStoreWrapper(CacheStore store)
Factory pattern: Instantiate a CacheStore wrapper around the passed CacheStore. (Supports CacheStore extension by delegation pattern.)

Parameters:
store - the CacheStore to wrap
Returns:
the CacheStore wrapper that can supplement and override the operations of the supplied CacheStore

instantiateCacheLoaderCacheStore

protected ReadWriteBackingMap.CacheLoaderCacheStore instantiateCacheLoaderCacheStore(CacheLoader loader)
Factory pattern: Instantiate a CacheLoaderCacheStore wrapper around a passed CacheLoader.

Parameters:
loader - the CacheLoader to wrap
Returns:
the CacheLoaderCacheStore

CoherenceTM v3.3
Copyright© 2000-2007 by Oracle Corporation