Overview | Package | Class | Tree | Index | Help

Oracle® Coherence Java API Reference
v3.5.3
E15583-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.tangosol.net.cache
Class ReadWriteBackingMap

    java.lang.Object
      java.util.AbstractMap
          com.tangosol.net.cache.ReadWriteBackingMap

All Implemented Interfaces:
  CacheMap, ObservableMap, java.util.Map

Direct Known Subclasses:
  ReadWriteSplittingBackingMap, VersionedBackingMap

    public class ReadWriteBackingMap

extends java.util.AbstractMap
implements CacheMap

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.
`static class` | `ReadWriteBackingMap.EvictingBackupMap` A Map implementation used for a backup map that evicts all data that has been successfully written.
`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
`java.util.Map.Entry`

Field Summary
`protected static float` | `GUARD_RECOVERY` The recovery threshold to use for guarded execution of write-behind/refresh-ahead threads.
`protected MapListenerSupport` | `m_listenerSupport` MapListenerSupport object.
`protected static java.lang.Object` | `NO_VALUE` Marker object used to indicate to the write-behind thread that an entry has been removed from the queue.

Fields inherited from interface com.tangosol.net.cache.CacheMap
`EXPIRY_DEFAULT, EXPIRY_NEVER`

Constructor Summary
`ReadWriteBackingMap(BackingMapManagerContext ctxService, ObservableMap mapInternal, java.util.Map mapMisses, CacheLoader loader)` Construct a ReadWriteBackingMap using a CacheLoader object.
`ReadWriteBackingMap(BackingMapManagerContext ctxService, ObservableMap mapInternal, java.util.Map mapMisses, CacheLoader loader, boolean fReadOnly, int cWriteBehindSeconds)` Construct a ReadWriteBackingMap.
`ReadWriteBackingMap(BackingMapManagerContext ctxService, ObservableMap mapInternal, java.util.Map mapMisses, CacheLoader loader, boolean fReadOnly, int cWriteBehindSeconds, double dflRefreshAheadFactor)` Construct a ReadWriteBackingMap.

Method Summary
`void` | `addMapListener(MapListener listener)` Add a standard map listener that will receive all events (inserts, updates, deletes) that occur against the map, with the key, old-value and new-value included.
`void` | `addMapListener(MapListener listener, Filter filter, boolean fLite)` Add a map listener that receives events based on a filter evaluation.
`void` | `addMapListener(MapListener listener, java.lang.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(java.lang.Object oKey)` Returns `true` if this map contains a mapping for the specified key.
`boolean` | `containsValue(java.lang.Object oValue)` Returns `true` if this CachingMap maps one or more keys to the specified value.
`java.util.Set` | `entrySet()` Returns an set view of the mappings contained in this map.
`boolean` | `equals(java.lang.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.
`java.lang.Object` | `get(java.lang.Object oKey)` Returns the value to which this map maps the specified key.
`java.util.Map` | `getAll(java.util.Collection colKeys)` Retrieve values for all the specified keys.
`protected java.lang.Object` | `getCachedOrPending(java.lang.Object oKey)` Get a value from the internal cache in a way that respects a potentially pending write-behind operation.
`ReadWriteBackingMap.CacheStoreWrapper` | `getCacheStore()` Get the representative of the "persistent" storage for this backing map.
`long` | `getCacheStoreTimeoutMillis()` Return the timeout used for CacheStore operations, or 0 if no timeout is specified.
`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 ConfigurableCacheMap` | `getInternalConfigurableCache()` Get the map that provides internal 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.
`java.util.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 java.util.Map` | `getSyntheticEventsMap()` Get the map of keys for which the events should be marked as synthetic (internal).
`double` | `getWriteBatchFactor()` Return the write-batch factor.
`long` | `getWriteBehindMillis()` Return the number of milliseconds between write-behind writes to the CacheStore or `0` if write-behind is not enabled.
`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 void` | `heartbeat()` Issue a service guardian "heartbeat" for the current thread.
`protected CacheStore` | `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(java.lang.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.
`java.util.Set` | `keySet()` Returns an set view of the keys contained in this map.
`java.lang.Object` | `put(java.lang.Object oKey, java.lang.Object oValue)` Associates the specified value with the specified key in this map.
`java.lang.Object` | `put(java.lang.Object oKey, java.lang.Object oValue, long cMillis)` Associates the specified value with the specified key in this map.
`protected java.lang.Object` | `putInternal(java.lang.Object oKey, java.lang.Object oValue, long cMillis)` An actual implementation for the extended put() method.
`void` | `release()` Release the backing map when it is no longer being used.
`java.lang.Object` | `remove(java.lang.Object oKey)` Removes the mapping for this key from this map if present.
`protected java.lang.Object` | `removeFromWriteQueue(java.lang.Object oKey)` Remove the specified entry from the WriteQueue.
`void` | `removeMapListener(MapListener listener)` Remove a standard map listener that previously signed up for all events.
`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, java.lang.Object oKey)` Remove a map listener that previously signed up for events about a specific key.
`void` | `setCacheStoreTimeoutMillis(long cStoreTimeoutMillis)` Set the timeout used for CacheStore operations.
`void` | `setRefreshAheadFactor(double dflRefreshAheadFactor)` Set the refresh-ahead factor, expressed as a percentage of the internal cache 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` | `setWriteBehindMillis(long cMillis)` Set the number of milliseconds between write-behind writes to the CacheStore.
`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.
`java.lang.String` | `toString()` For debugging purposes, format the contents of the Map in a human- readable format.
`java.util.Collection` | `values()` Returns a collection view of the values contained in this map.
`protected boolean` | `waitFor(java.lang.Object o, long cMillis)` Wait for notification on the specified object for no longer than the specified wait time.

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 java.lang.Object NO_VALUE

  Marker object used to indicate to the write-behind thread that an entry has been removed from the queue.

### GUARD_RECOVERY

    protected static final float GUARD_RECOVERY

  The recovery threshold to use for guarded execution of write-behind/refresh-ahead threads.

  See Also:
    Constant Field Values

### m_listenerSupport

    protected MapListenerSupport m_listenerSupport

  MapListenerSupport object.

Constructor Detail

### ReadWriteBackingMap

    public ReadWriteBackingMap(BackingMapManagerContext ctxService,
                               ObservableMap mapInternal,
                               java.util.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 object responsible for the persistence of the cached data (optional)

### ReadWriteBackingMap

    public ReadWriteBackingMap(BackingMapManagerContext ctxService,
                               ObservableMap mapInternal,
                               java.util.Map mapMisses,
                               CacheLoader loader,
                               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)
    `loader` - the object responsible for the persistence of the cached data (optional)
    `fReadOnly` - pass true is the specified loader is in fact a CacheStore that needs to be used 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,
                               java.util.Map mapMisses,
                               CacheLoader loader,
                               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)
    `loader` - the object responsible for the persistence of the cached data (optional)
    `fReadOnly` - pass true is the specified loader is in fact a CacheStore that needs to be used 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 `ConfigurableCacheMap`

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

### getWriteBehindMillis

    public long getWriteBehindMillis()

  Return the number of milliseconds between write-behind writes to the CacheStore or `0` if write-behind is not enabled.

  Returns:
    the number of milliseconds between write-behind writes
  Since:
    Coherence 3.4

### setWriteBehindMillis

    public void setWriteBehindMillis(long cMillis)

  Set the number of milliseconds between write-behind writes to the CacheStore.

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

  Parameters:
    `cMillis` - the new write-behind delay in milliseconds
  Since:
    Coherence 3.4

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

### getCacheStoreTimeoutMillis

    public long getCacheStoreTimeoutMillis()

  Return the timeout used for CacheStore operations, or 0 if no timeout is specified.

  Returns:
    the CacheStore timeout

### setCacheStoreTimeoutMillis

    public void setCacheStoreTimeoutMillis(long cStoreTimeoutMillis)

  Set the timeout used for CacheStore operations. A value of 0 indicates to use the default guardian timeout of the associated service.

  Parameters:
    `cStoreTimeoutMillis` - the CacheStore timeout, or 0 for the default guardian timeout

### clear

    public void clear()

  Remove everything from the Map.

  Specified by:
    `clear` in interface `java.util.Map`
  Overrides:
    `clear` in class `java.util.AbstractMap`

### containsKey

    public boolean containsKey(java.lang.Object oKey)

  Returns `true` if this map contains a mapping for the specified key.

  Specified by:
    `containsKey` in interface `java.util.Map`
  Overrides:
    `containsKey` in class `java.util.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(java.lang.Object oValue)

  Returns `true` if this CachingMap maps one or more keys to the specified value.

  Specified by:
    `containsValue` in interface `java.util.Map`
  Overrides:
    `containsValue` in class `java.util.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 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 `java.util.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 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 `CacheMap`
  Specified by:
    `put` in interface `java.util.Map`
  Overrides:
    `put` in class `java.util.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 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 `java.util.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 `java.util.Map`
  Overrides:
    `size` in class `java.util.AbstractMap`
  Returns:
    the number of key-value mappings in this map

### entrySet

    public java.util.Set entrySet()

  Returns an set view of the mappings contained in this map.

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

### keySet

    public java.util.Set keySet()

  Returns an set view of the keys contained in this map.

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

### values

    public java.util.Collection values()

  Returns a collection view of the values contained in this map.

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

### put

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

  Associates the specified value with the specified key in this map.

  Specified by:
    `put` in interface `CacheMap`
  Parameters:
    `oKey` - key with which the specified value is to be associated
    `oValue` - value to be associated with the specified key
    `cMillis` - the number of milliseconds until the entry will expire; pass zero to use the cache's default ExpiryDelay settings; pass -1 to indicate that the entry should never expire
  Returns:
    previous value associated with specified key, or `null` if there was no mapping for key

### getAll

    public java.util.Map getAll(java.util.Collection colKeys)

  Retrieve values for all the specified keys.

  Specified by:
    `getAll` in interface `CacheMap`
  Parameters:
    `colKeys` - a collection of keys that may be in the named cache
  Returns:
    a Map of keys to values for the specified keys passed in `colKeys`

### getCachedOrPending

    protected java.lang.Object getCachedOrPending(java.lang.Object oKey)

  Get a value from the internal cache in a way that respects a potentially pending write-behind operation.

  Parameters:
    `oKey` - the key
  Returns:
    the corresponding value

### putInternal

    protected java.lang.Object putInternal(java.lang.Object oKey,
                                           java.lang.Object oValue,
                                           long cMillis)

  An actual implementation for the extended put() method.

  Parameters:
    `oKey` - key with which the specified value is to be associated
    `oValue` - value to be associated with the specified key
    `cMillis` - the number of milliseconds until the entry will expire
  Returns:
    previous value associated with specified key, or `null` if there was no mapping for key.

### waitFor

    protected boolean waitFor(java.lang.Object o,
                              long cMillis)

  Wait for notification on the specified object for no longer than the specified wait time.

  Note: the caller must hold synchronization on the object being waited on.

  Parameters:
    `o` - the object to wait for notification on
    `cMillis` - the maximum time in milliseconds to wait; pass 0 for forever
  Returns:
    true iff notification was received, the timeout has passed, or the thread was spuriously wakenend; false if this thread was interrupted

### heartbeat

    protected void heartbeat()

  Issue a service guardian "heartbeat" for the current thread.

### 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 that will receive all events (inserts, updates, deletes) that occur against the map, with the key, old-value and new-value included. This has the same result as the following call:

         addMapListener(listener, (Filter) null, false);

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

### removeMapListener

    public void removeMapListener(MapListener listener)

  Remove a standard map listener that previously signed up for all events. This has the same result as the following call:

         removeMapListener(listener, (Filter) null);

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

### addMapListener

    public void addMapListener(MapListener listener,
                               java.lang.Object oKey,
                               boolean fLite)

  Add a map listener for a specific key.

  The listeners will receive MapEvent objects, but if fLite is passed as true, they might not contain the OldValue and NewValue properties.

  To unregister the MapListener, use the `ObservableMap.removeMapListener(MapListener, Object)` method.

  Specified by:
    `addMapListener` in interface `ObservableMap`
  Parameters:
    `listener` - the `MapEvent` 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

### removeMapListener

    public void removeMapListener(MapListener listener,
                                  java.lang.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

### addMapListener

    public void addMapListener(MapListener listener,
                               Filter filter,
                               boolean fLite)

  Add a map listener that receives events based on a filter evaluation.

  The listeners will receive MapEvent objects, but if fLite is passed as true, they might not contain the OldValue and NewValue properties.

  To unregister the MapListener, use the `ObservableMap.removeMapListener(MapListener, Filter)` method.

  Specified by:
    `addMapListener` in interface `ObservableMap`
  Parameters:
    `listener` - the `MapEvent` 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 (see `MapEventFilter`); 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

### 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` - the filter that was passed into the corresponding addMapListener() call

### equals

    public boolean equals(java.lang.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 `java.util.Map`
  Overrides:
    `equals` in class `java.util.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 `java.util.Map`
  Overrides:
    `hashCode` in class `java.util.AbstractMap`
  Returns:
    the hash code value for this map

### toString

    public java.lang.String toString()

  For debugging purposes, format the contents of the Map in a human- readable format.

  Overrides:
    `toString` in class `java.util.AbstractMap`
  Returns:
    a String representation of this ReadWriteBackingMap

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

### getInternalConfigurableCache

    protected ConfigurableCacheMap getInternalConfigurableCache()

  Get the map that provides internal storage for this backing map. If the internal storage is a ConfigurableCacheMap, then this accessor returns the same reference as `getInternalCache()`; otherwise it returns null. The refresh-ahead implementation relies on the internal storage providing the ConfigurableCacheMap interface, so this method will always return a non-null value if refresh-ahead is enabled.

  Returns:
    the cache for this backing map or null if the internal map is not an implementation of the ConfigurableCacheMap interface

### configureInternalCache

    protected void configureInternalCache(ObservableMap mapInternal)

  Configure the internal cache that this backing map uses to store its "in-memory" data.

### getMissesCache

    public java.util.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 java.util.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(java.lang.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

### removeFromWriteQueue

    protected java.lang.Object removeFromWriteQueue(java.lang.Object oKey)

  Remove the specified entry from the WriteQueue.

  Returns:
    the currently queueed value (could be NO_VALUE or null)

### 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 cache returned by `getInternalConfigurableCache()` 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 CacheStore instantiateCacheLoaderCacheStore(CacheLoader loader)

  Factory pattern: Instantiate a CacheLoaderCacheStore wrapper around a passed CacheLoader.

  Parameters:
    `loader` - the CacheLoader to wrap; never null
  Returns:
    a CacheStore istance

Overview | Package | Class | Tree | Index | Help

Oracle® Coherence Java API Reference
v3.5.3
E15583-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2000, 2010, Oracle. All rights reserved.