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 OverflowMap

    java.lang.Object
      com.tangosol.util.Base
          com.tangosol.util.AbstractKeyBasedMap
              com.tangosol.util.AbstractKeySetBasedMap
                  com.tangosol.net.cache.OverflowMap

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

    public class OverflowMap

extends AbstractKeySetBasedMap
implements CacheMap

An Observable Map implementation that wraps two maps - a front map (assumed to be fast but limited in its maximum size) and a back map (assumed to be slower but much less limited in its maximum size).

The OverflowMap is observable, and as such it is allowed to be an active data structure. In other words, it supports item expiration, eviction, and other types of "self-generating" events. (The `SimpleOverflowMap`) is an alternative that may be more efficient if the overflow map is passive.) As a consequence of the requirements for managing the overflow map as an active data structure, the OverflowMap maintains information about each entry in the map; in practice, this will limit the size of the OverflowMap since all keys and some additional information for each key will be maintained in memory. On the other hand, by maintaining this information in memory, certain operations will be more efficient, such as the methods `containsKey()`, `size()`, `keySet().iterator()`, etc. (Again, for an alternative, see `SimpleOverflowMap`, which does not maintain the entire set of keys in memory.)

The primary reason why OverflowMap is based on the AbstractKeySetBasedMap is that the set of keys within the OverflowMap is considered to be "known", although not altogether stable due to concurrency issues (the OverflowMap is designed to support a high level of concurrency). AbstractKeySetBasedMap conceptually delegates many operations down to its key Set, which the OverflowMap implementation reverses (by having the implementations on the OverflowMap itself). However, the key and entry Sets and the values Collection benefit significantly in terms of their ability to optimize the `Collection.iterator()` and `Collection.toArray()` methods.

Further, as a result (and sometimes as a consequence) of its observability, the OverflowMap supports (and has to support) a number of capabilities that the SimpleOverflowMap does not:

- Expiry - the entries in the OverflowMap can each have their own expiry, which is respected regardless of whether the entry is being managed in the front and/or back map.
- Reentrancy - since an event listener on the OverflowMap can respond to an event in an unpredictable manner, including by attempting to undo or compensate for or react to the event, the OverflowMap is forced to support reentrancy.

Since:
  Coherence 2.2
Author:
  cp 2003.05.24, cp 2005.08.11 re-architected and split out SimpleOverflowMap

Nested Class Summary
`protected class` | `OverflowMap.BackMapListener` A listener for the back map.
`class` | `OverflowMap.EntrySet` A set of entries backed by this map.
`protected static class` | `OverflowMap.ExpirableStatus` The ExpirableStatus adds expiry to the base Status object.
`protected class` | `OverflowMap.FrontMapListener` A listener for the front map that moves evictions to the back map.
`protected static class` | `OverflowMap.HistoricCacheEvent` A CacheEvent that carries a recent value (to avoid it being lost during eviction).
`protected class` | `OverflowMap.InternalKeySet` A read-only set of keys backed by this map.
`protected static class` | `OverflowMap.Status` The Status object is used to manage concurrency at the key level for the key-level operations against the Map, to track all the items in the front Map, to manage the state transition for operations occurring against the Map, and to coordinate events across multiple threads.

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

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

Field Summary
`static int` | `ENTRY_DELETED` This event indicates that an entry has been removed from the map.
`static int` | `ENTRY_INSERTED` This event indicates that an entry has been added to the map.
`static int` | `ENTRY_UPDATED` This event indicates that an entry has been updated in the map.

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

Constructor Summary
`OverflowMap(ObservableMap mapFront, java.util.Map mapBack)` Construct a OverflowMap using two specified maps: FrontMap (aka "cache" or "shallow") and BackMap (aka "file" or "deep") If the BackMap implements the ObservableMap interface a listener will be added to the BackMap to invalidate items updated [externally] in the back map.

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.
`protected void` | `adjustSize(int cItems)` Adjust the number of entries in the OverflowMap.
`protected OverflowMap.Status` | `beginKeyProcess(java.lang.Object oKey)` Block until a key is available for processing, and return the Status object for that key.
`protected void` | `beginMapProcess()` Block until this thread has exclusive access to perform operations against the OverflowMap.
`void` | `clear()` Clear all key/value mappings.
`protected void` | `closeStatus(OverflowMap.Status status)` Helper method to close a Status, processing any pending events as part of the process.
`boolean` | `containsKey(java.lang.Object oKey)` Returns `true` if this map contains a mapping for the specified key.
`protected void` | `dispatchEvent(OverflowMap.Status status, int nId, java.lang.Object oKey, java.lang.Object oValueOld, java.lang.Object oValueNew, boolean fSynthetic)` Dispatch an event containing the passed event information.
`protected void` | `dispatchEvent(OverflowMap.Status status, MapEvent evt)` Dispatch the passed event.
`protected void` | `endKeyProcess(java.lang.Object oKey, OverflowMap.Status status)` Finish the processing of a single key.
`protected void` | `endMapProcess()` Release exclusive access for the OverflowMap.
`void` | `evict()` Flush items that have expired.
`protected static void` | `evict(java.util.Map map)` If the passed Map supports it, evict its expired data.
`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)` Get all the specified keys, if they are in the Map.
`java.util.Map` | `getBackMap()` Returns the back Map.
`protected MapListener` | `getBackMapListener()` Get the MapListener for the back map.
`CacheStatistics` | `getCacheStatistics()` Returns the CacheStatistics for this cache.
`protected java.util.List` | `getDeferredList()` Obtain the List of keys that may have deferred events.
`protected LongArray` | `getExpiryArray()` Obtain the array of keys that have an expiration, indexed by expiration times.
`int` | `getExpiryDelay()` Determine the "time to live" for each individual cache entry.
`ObservableMap` | `getFrontMap()` Returns the front Map.
`protected MapListener` | `getFrontMapListener()` Get the MapListener for the front map.
`protected java.lang.Object` | `getInternal(java.lang.Object oKey, boolean fStats, java.util.Map mapResult)` A combined implementation of `get(java.lang.Object)` and `getAll(java.util.Collection)` that eliminates duplicate (and very complex) code.
`protected java.util.Set` | `getInternalKeySet()` Obtain a set of keys that are represented by this Map.
`protected static java.lang.Object` | `getLatestOldValue(MapEvent evt)` Obtain the latest old value from the passed event.
`protected MapListenerSupport` | `getMapListenerSupport()` Accessor for the MapListenerSupport for sub-classes.
`protected int` | `getSize()` Obtain the number of entries in the OverflowMap.
`protected java.util.Map` | `getStatusMap()` Obtain the Map of Status objects for entries managed by this Overflow Map.
`protected ThreadGate` | `getThreadGate()` Obtain the ThreadGate for managing key-level and Collection-level operations against the Map, versus Map-level operations themselves.
`protected boolean` | `hasListeners()` Determine if the OverflowMap has any listeners at all.
`protected MapListener` | `instantiateBackMapListener()` Factory pattern: Back Map Listener.
`protected java.util.Set` | `instantiateEntrySet()` Factory pattern: Create a Set that represents the entries in the Map.
`protected MapListener` | `instantiateFrontMapListener()` Factory pattern: Front Map Listener.
`protected java.util.Set` | `instantiateInternalKeySet()` Factory pattern: Create a read-only Set of keys in the Overflow Map
`protected OverflowMap.Status` | `instantiateStatus()` Factory method: Instantiate a Status object.
`boolean` | `isEmpty()` Returns `true` if this map contains no key-value mappings.
`boolean` | `isExpiryEnabled()` Determine if this OverflowMap supports entry expiry.
`boolean` | `isFrontPutBlind()` Determine if the front Map is more efficiently updated using putAll.
`protected boolean` | `isInternalKeySetIteratorMutable()` Determine if this Iterator should remove an iterated item by calling remove on the internal key Set Iterator, or by calling removeBlind on the map itself.
`boolean` | `isNullValuesAllowed()` Determine if null values are permitted.
`protected static boolean` | `isSynthetic(MapEvent evt)` Helper method to determine if an event is synthetic.
`protected static MapEvent` | `mergeEvents(MapEvent evtOld, MapEvent evtNew)` Merge two events that have been raised in sequence from a given map.
`protected void` | `onBackEvent(MapEvent evtBack)` Handle an event occuring against the "back" map.
`protected void` | `onFrontEvent(MapEvent evt)` Either handle an event by turning it over to another thread that is processing the key specified by the event, or take responsibility on this thread for deferring the event and registering its immediate side-effects.
`protected boolean` | `prepareStatus(java.lang.Object oKey, OverflowMap.Status status)` Validate the status and process any deferred events or pending expiry.
`protected void` | `processBackEvent(OverflowMap.Status status, MapEvent evtBack)` Process an event.
`protected void` | `processDeferredEvents(boolean fProcessAll)` Process deferred events, if there are any.
`protected void` | `processEvent(OverflowMap.Status status, MapEvent evt)` Process an arbitrary event that has occurred against either the front or back map.
`protected void` | `processFrontEvent(OverflowMap.Status status, MapEvent evtFront)` Process an event.
`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 cache.
`void` | `putAll(java.util.Map map)` Copies all of the mappings from the specified map to this map.
`protected java.lang.Object` | `putInternal(java.lang.Object oKey, java.lang.Object oValue, boolean fStoreOnly, long cMillis)` A combined implementation of `put(Object, Object)` and "void put(Object, Object)" that eliminates duplicate (and muchos complex) code between the `put(java.lang.Object, java.lang.Object)` and `putAll(java.util.Map)` methods.
`protected static void` | `putOne(java.util.Map map, java.lang.Object oKey, java.lang.Object oValue, boolean fPutBlind)` Helper to put a value into a map using either the `put` or `putAll` method.
`protected void` | `registerExpiry(java.lang.Object oKey, long ldtExpire)` Register an expiry for the specified key.
`protected void` | `releaseClosedStatus(java.lang.Object oKey)` Helper method to encapsulate the release of a Status object on which closeProcessing() has already been called.
`java.lang.Object` | `remove(java.lang.Object oKey)` Removes the mapping for this key from this map if present.
`protected boolean` | `removeBlind(java.lang.Object oKey)` Removes the mapping for this key from this map if present.
`protected java.lang.Object` | `removeInternal(java.lang.Object oKey, boolean fCheckRemovedOnly, boolean fEviction)` A combined implementation of remove() and removeBlind() that eliminates duplicate (and muchos complex) code
`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.
`protected void` | `setBackMapListener(MapListener listener)` Specify the MapListener for the back map.
`protected void` | `setExpiryArray(LongArray laExpiry)` Specify the array of keys that have an expiration, indexed by expiration times.
`void` | `setExpiryDelay(int cMillis)` Specify the "time to live" for cache entries.
`void` | `setExpiryEnabled(boolean fEnableExpiry)` Specify whether or not entry expiry is supported.
`protected void` | `setFrontMapListener(MapListener listener)` Specify the MapListener for the front map.
`void` | `setFrontPutBlind(boolean fUseFrontPutAll)` Specify whether the front Map is more efficiently updated using putAll.
`void` | `setNullValuesAllowed(boolean fAllowNulls)` Specify whether null values are permitted.
`protected void` | `setSize(int cItems)` Update the number of entries in the OverflowMap.
`int` | `size()` Returns the number of key-value mappings in this map.
`protected void` | `unregisterExpiry(java.lang.Object oKey, long ldtExpire)` Unregister the specified key expiry that is registered to expire at the specified time.
`protected static void` | `verifyNoNulls(java.util.Collection collection, java.lang.String sAssert)` Check the passed collection for nulls, and fail if it contains any.
`protected static void` | `warnEventSequence(MapEvent evtOld, MapEvent evtNew)` Issue a one-time warning that events are being received in an order than cannot be explained by normal operation according to the contracts expected by this OverflowMap.
`protected void` | `warnMissingEvent(java.lang.Object oKey, int nId, boolean fFront)` An expected event did not get raised.
`protected void` | `warnUnfathomable(MapEvent evt)` Something totally inexplicable has occurred.

Methods inherited from class com.tangosol.util.AbstractKeySetBasedMap
`instantiateKeyIterator, instantiateKeySet, instantiateValues, iterateKeys`

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

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

Field Detail

### ENTRY_INSERTED

    public static final int ENTRY_INSERTED

  This event indicates that an entry has been added to the map.

  See Also:
    Constant Field Values

### ENTRY_UPDATED

    public static final int ENTRY_UPDATED

  This event indicates that an entry has been updated in the map.

  See Also:
    Constant Field Values

### ENTRY_DELETED

    public static final int ENTRY_DELETED

  This event indicates that an entry has been removed from the map.

  See Also:
    Constant Field Values

Constructor Detail

### OverflowMap

    public OverflowMap(ObservableMap mapFront,
                       java.util.Map mapBack)

  Construct a OverflowMap using two specified maps:
  - FrontMap (aka "cache" or "shallow") and
  - BackMap (aka "file" or "deep")
  If the BackMap implements the ObservableMap interface a listener will be added to the BackMap to invalidate items updated [externally] in the back map.

  Parameters:
    `mapBack` - back map
    `mapFront` - front map

Method Detail

### clear

    public void clear()

  Clear all key/value mappings.

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

### 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 `AbstractKeySetBasedMap`
  Returns:
    `true` if this map contains a mapping for the specified key, `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`
  Specified by:
    `get` in class `AbstractKeyBasedMap`
  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

### isEmpty

    public boolean isEmpty()

  Returns `true` if this map contains no key-value mappings.

  Specified by:
    `isEmpty` in interface `java.util.Map`
  Overrides:
    `isEmpty` in class `AbstractKeySetBasedMap`
  Returns:
    `true` if this map contains no key-value mappings

### 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 `AbstractKeyBasedMap`
  Parameters:
    `oKey` - key with which the specified value is to be associated
    `oValue` - value to be associated with the specified key
  Returns:
    previous value associated with specified key, or `null` if there was no mapping for key

### putAll

    public void putAll(java.util.Map map)

  Copies all of the mappings from the specified map to this map. The effect of this call is equivalent to that of calling `AbstractKeyBasedMap.put(java.lang.Object, java.lang.Object)` on this map once for each mapping in the passed map. The behavior of this operation is unspecified if the passed map is modified while the operation is in progress.

  Specified by:
    `putAll` in interface `java.util.Map`
  Overrides:
    `putAll` in class `AbstractKeyBasedMap`
  Parameters:
    `map` - the Map containing the key/value pairings to put into this Map

### remove

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

  Removes the mapping for this key from this map if present. Expensive: updates both the underlying cache and the local cache.

  Specified by:
    `remove` in interface `java.util.Map`
  Overrides:
    `remove` in class `AbstractKeyBasedMap`
  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.

  Specified by:
    `size` in interface `java.util.Map`
  Overrides:
    `size` in class `AbstractKeySetBasedMap`
  Returns:
    the number of key-value mappings 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 cache. If the cache previously contained a mapping for this key, the old value is replaced. This variation of the `CacheMap.put(Object oKey, Object oValue)` method allows the caller to specify an expiry (or "time to live") for the cache entry.

  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 cache entry will expire, also referred to as the entry's "time to live"; pass `CacheMap.EXPIRY_DEFAULT` to use the cache's default time-to-live setting; pass `CacheMap.EXPIRY_NEVER` to indicate that the cache entry should never expire; this milliseconds value is not a date/time value, such as is returned from System.currentTimeMillis()
  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

### getAll

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

  Get all the specified keys, if they are in the Map. For each key that is in the cache, that key and its corresponding value will be placed in the map that is returned by this method. The absence of a key in the returned map indicates that it was not in the cache, which may imply (for caches that can load behind the scenes) that the requested data could not be loaded.

  Specified by:
    `getAll` in interface `CacheMap`
  Overrides:
    `getAll` in class `AbstractKeyBasedMap`
  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`

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

### removeBlind

    protected boolean removeBlind(java.lang.Object oKey)

  Removes the mapping for this key from this map if present. This method exists to allow sub-classes to optmiize remove functionalitly for situations in which the original value is not required.

  Overrides:
    `removeBlind` in class `AbstractKeyBasedMap`
  Parameters:
    `oKey` - key whose mapping is to be removed from the map
  Returns:
    true iff the Map changed as the result of this operation

### getInternalKeySet

    protected java.util.Set getInternalKeySet()

  Obtain a set of keys that are represented by this Map.

  The AbstractKeySetBasedMap only utilizes the internal key set as a read-only resource.

  Specified by:
    `getInternalKeySet` in class `AbstractKeySetBasedMap`
  Returns:
    an internal Set of keys that are contained by this Map

### isInternalKeySetIteratorMutable

    protected boolean isInternalKeySetIteratorMutable()

  Determine if this Iterator should remove an iterated item by calling remove on the internal key Set Iterator, or by calling removeBlind on the map itself.

  Overrides:
    `isInternalKeySetIteratorMutable` in class `AbstractKeySetBasedMap`
  Returns:
    true to remove using the internal key Set Iterator or false to use the `AbstractKeyBasedMap.removeBlind(Object)` method

### getInternal

    protected java.lang.Object getInternal(java.lang.Object oKey,
                                           boolean fStats,
                                           java.util.Map mapResult)

  A combined implementation of `get(java.lang.Object)` and `getAll(java.util.Collection)` that eliminates duplicate (and very complex) code.

  Parameters:
    `oKey` - the key to access
    `fStats` - pass true to update statistics
    `mapResult` - pass a map into which the key and its value will be put iff the key is contained within the overflow map
  Returns:
    the value (which may be null) is returned from the entry if it exists, otherwise null is returned

### putInternal

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

  A combined implementation of `put(Object, Object)` and "void put(Object, Object)" that eliminates duplicate (and muchos complex) code between the `put(java.lang.Object, java.lang.Object)` and `putAll(java.util.Map)` methods. Additionally implements the put-with-expiry option.

  Parameters:
    `oKey` - the key to store
    `oValue` - the value to store
    `fStoreOnly` - pass true to simply store the new value, or false to both store the new value and return the previous value
    `cMillis` - the time-to-live for the entry as defined by `CacheMap.put(Object, Object, long)`
  Returns:
    the previous value if fStoreOnly is false and the entry existed in the overflow map, otherwise undefined

### removeInternal

    protected java.lang.Object removeInternal(java.lang.Object oKey,
                                              boolean fCheckRemovedOnly,
                                              boolean fEviction)

  A combined implementation of remove() and removeBlind() that eliminates duplicate (and muchos complex) code

  Parameters:
    `oKey` - the key to remove
    `fCheckRemovedOnly` - pass true to only check for entry existence
    `fEviction` - pass true if the removal is an eviction and if the status is already owned by this thread
  Returns:
    if only checking for existence, then a Boolean value is returned, otherwise the value (which may be null) is returned from the entry if it exists, otherwise null is returned

### getFrontMap

    public ObservableMap getFrontMap()

  Returns the front Map.

  Warning: Direct modifications of the returned map may cause unpredictable behavior of the Overflow Map.

  Returns:
    the front Map

### getBackMap

    public java.util.Map getBackMap()

  Returns the back Map.

  Warning: Direct modifications of the returned map may cause unpredictable behavior of the Overflow Map.

  Returns:
    the back Map

### getExpiryDelay

    public int getExpiryDelay()

  Determine the "time to live" for each individual cache entry.

  Returns:
    the number of milliseconds that a cache entry value will live, or `EXPIRY_NEVER` if the entries never expire by default

### setExpiryDelay

    public void setExpiryDelay(int cMillis)

  Specify the "time to live" for cache entries. This does not affect the already-scheduled expiry of existing entries.

  Parameters:
    `cMillis` - the number of milliseconds to specify that cache entries subsequently added without an expiry will live, `EXPIRY_DEFAULT` to indicate that the OverflowMap's default expiry be used (which is to never automatically expire values), or `EXPIRY_NEVER` to specify that cache entries subsequently added without an expiry will never expire

### getSize

    protected int getSize()

  Obtain the number of entries in the OverflowMap.

  Returns:
    the cached size of the OverflowMap

### setSize

    protected void setSize(int cItems)

  Update the number of entries in the OverflowMap.

  Parameters:
    `cItems` - the cached size of the OverflowMap

### adjustSize

    protected void adjustSize(int cItems)

  Adjust the number of entries in the OverflowMap.

  Parameters:
    `cItems` - the number of items to adjust the cached size of the OverflowMap by, for example +1 or -1

### getCacheStatistics

    public CacheStatistics getCacheStatistics()

  Returns the CacheStatistics for this cache.

  Returns:
    a CacheStatistics object

### getThreadGate

    protected ThreadGate getThreadGate()

  Obtain the ThreadGate for managing key-level and Collection-level operations against the Map, versus Map-level operations themselves.

  Returns:
    the ThreadGate for the OverflowMap

### getStatusMap

    protected java.util.Map getStatusMap()

  Obtain the Map of Status objects for entries managed by this Overflow Map. There will be a Status object for each entry in the front map, and a Status object for each key that has a current operation underway.

  Returns:
    the Map of Status objects

### getExpiryArray

    protected LongArray getExpiryArray()

  Obtain the array of keys that have an expiration, indexed by expiration times.

  Returns:
    a sparse LongArray keyed by expiry time with a corresponding value of a set of keys that expire at that time

### setExpiryArray

    protected void setExpiryArray(LongArray laExpiry)

  Specify the array of keys that have an expiration, indexed by expiration times.

  Parameters:
    `laExpiry` - a LongArray to use to keep track of what expires when

### getFrontMapListener

    protected MapListener getFrontMapListener()

  Get the MapListener for the front map.

  Returns:
    the MapListener for the front map

### setFrontMapListener

    protected void setFrontMapListener(MapListener listener)

  Specify the MapListener for the front map.

  The caller is required to manage all of the thread concurrency issues associated with modifying the listener.

  Parameters:
    `listener` - the MapListener for the front map

### getBackMapListener

    protected MapListener getBackMapListener()

  Get the MapListener for the back map.

  Returns:
    the MapListener for the back map

### setBackMapListener

    protected void setBackMapListener(MapListener listener)

  Specify the MapListener for the back map.

  The caller is required to manage all of the thread concurrency issues associated with modifying the listener.

  Parameters:
    `listener` - the MapListener for the back map

### getDeferredList

    protected java.util.List getDeferredList()

  Obtain the List of keys that may have deferred events.

  Returns:
    the List of keys of deferred-event Status objects

### isNullValuesAllowed

    public boolean isNullValuesAllowed()

  Determine if null values are permitted. By default, they are not.

  Returns:
    true iff null values are permitted

### setNullValuesAllowed

    public void setNullValuesAllowed(boolean fAllowNulls)

  Specify whether null values are permitted.

  Parameters:
    `fAllowNulls` - pass true to allow null values; false to disallow

### isExpiryEnabled

    public boolean isExpiryEnabled()

  Determine if this OverflowMap supports entry expiry.

  Returns:
    true iff the entry expiry feature is supported

### setExpiryEnabled

    public void setExpiryEnabled(boolean fEnableExpiry)

  Specify whether or not entry expiry is supported. Since there is a per-entry (memory) cost just to support the expiry feature, and since there is additional memory cost (and a small performance cost) to keep track of entries that are set to expire, this feature is made optional.

  Note that this feature must be enabled before populating the cache.

  Parameters:
    `fEnableExpiry` - pass true to enable entry expiry, false to disable it

### isFrontPutBlind

    public boolean isFrontPutBlind()

  Determine if the front Map is more efficiently updated using putAll. (The use of `putAll` instead of `put` is called put-blind because it does not return a value.)

  Returns:
    true iff the use of the `put` method should be avoided when updating the front Map, and `putAll` should be used instead

### setFrontPutBlind

    public void setFrontPutBlind(boolean fUseFrontPutAll)

  Specify whether the front Map is more efficiently updated using putAll.

  Parameters:
    `fUseFrontPutAll` - pass true to allow null values; false to disallow

### beginKeyProcess

    protected OverflowMap.Status beginKeyProcess(java.lang.Object oKey)

  Block until a key is available for processing, and return the Status object for that key. The caller is then expected to perform its processing, during which time events against the Map Entry may occur. Note that those events can occur on threads other than the current thread; when this current thread can no longer handle events from other threads, it must call `OverflowMap.Status.closeProcessing()` and then perform its final adjustments to the Status data structure, handling any events that were queued in the meantime on the Status. After completing the processing during this "quiet period" in which all other threads are prevented from accessing this entry or handling events for this entry, then the caller must call `endKeyProcess(java.lang.Object, com.tangosol.net.cache.OverflowMap.Status)` passing the Status object returned from this method.

  Parameters:
    `oKey` - the key to process
  Returns:
    the Status object for the specified key

### endKeyProcess

    protected void endKeyProcess(java.lang.Object oKey,
                                 OverflowMap.Status status)

  Finish the processing of a single key.

  Parameters:
    `status` - the Status object returned from the call to `beginKeyProcess(java.lang.Object)`

### beginMapProcess

    protected void beginMapProcess()

  Block until this thread has exclusive access to perform operations against the OverflowMap.

### endMapProcess

    protected void endMapProcess()

  Release exclusive access for the OverflowMap.

### prepareStatus

    protected boolean prepareStatus(java.lang.Object oKey,
                                    OverflowMap.Status status)

  Validate the status and process any deferred events or pending expiry.

  Parameters:
    `oKey` - the entry key
    `status` - the Status object for the entry
  Returns:
    true iff the Status is in the processing state and oready to be used

### onFrontEvent

    protected void onFrontEvent(MapEvent evt)

  Either handle an event by turning it over to another thread that is processing the key specified by the event, or take responsibility on this thread for deferring the event and registering its immediate side-effects.

### onBackEvent

    protected void onBackEvent(MapEvent evtBack)

  Handle an event occuring against the "back" map.

  Parameters:
    `evtBack` - an event from the back map

### mergeEvents

    protected static MapEvent mergeEvents(MapEvent evtOld,
                                          MapEvent evtNew)

  Merge two events that have been raised in sequence from a given map.

  Parameters:
    `evtOld` - the first event
    `evtNew` - the second event
  Returns:
    the merged event

### getLatestOldValue

    protected static java.lang.Object getLatestOldValue(MapEvent evt)

  Obtain the latest old value from the passed event. The latest old value is the value that must be retained upon the eviction of data from the front map.

  Parameters:
    `evt` - an event (which may be a HistoricCacheEvent)
  Returns:
    the latest old value from the event

### processEvent

    protected void processEvent(OverflowMap.Status status,
                                MapEvent evt)

  Process an arbitrary event that has occurred against either the front or back map.

  Parameters:
    `status` - the Status object representing the Overflow Map's entry against which the event was raised
    `evt` - the MapEvent to process

### processFrontEvent

    protected void processFrontEvent(OverflowMap.Status status,
                                     MapEvent evtFront)

  Process an event. The Status must already be owned by this thread and in the processing or committing state.

  Parameters:
    `evtFront` - the event to process; may be null

### processBackEvent

    protected void processBackEvent(OverflowMap.Status status,
                                    MapEvent evtBack)

  Process an event. The Status must already be owned by this thread and in the processing or committing state.

  Parameters:
    `evtBack` - the event to process; may be null

### processDeferredEvents

    protected void processDeferredEvents(boolean fProcessAll)

  Process deferred events, if there are any.

  Parameters:
    `fProcessAll` - pass true to process all pending events, false to process just a fair portion of them

### closeStatus

    protected void closeStatus(OverflowMap.Status status)

  Helper method to close a Status, processing any pending events as part of the process.

  Parameters:
    `status` - the Status object to close

### releaseClosedStatus

    protected void releaseClosedStatus(java.lang.Object oKey)

  Helper method to encapsulate the release of a Status object on which closeProcessing() has already been called.

  Parameters:
    `oKey` - the entry key

### getMapListenerSupport

    protected MapListenerSupport getMapListenerSupport()

  Accessor for the MapListenerSupport for sub-classes.

  Returns:
    the MapListenerSupport, or null if there are no listeners

### hasListeners

    protected boolean hasListeners()

  Determine if the OverflowMap has any listeners at all.

  Returns:
    true iff this OverflowMap has at least one MapListener

### dispatchEvent

    protected void dispatchEvent(OverflowMap.Status status,
                                 int nId,
                                 java.lang.Object oKey,
                                 java.lang.Object oValueOld,
                                 java.lang.Object oValueNew,
                                 boolean fSynthetic)

  Dispatch an event containing the passed event information.

  Parameters:
    `status` - the Status for the entry
    `nId` - this event's id
    `oKey` - the key into the map
    `oValueOld` - the old value
    `oValueNew` - the new value
    `fSynthetic` - true iff the event is caused by the cache internal processing such as eviction or loading

### dispatchEvent

    protected void dispatchEvent(OverflowMap.Status status,
                                 MapEvent evt)

  Dispatch the passed event.

  Parameters:
    `status` - the Status for the entry
    `evt` - a MapEvent object

### isSynthetic

    protected static boolean isSynthetic(MapEvent evt)

  Helper method to determine if an event is synthetic.

  Parameters:
    `evt` - a Map Event
  Returns:
    true if the event is a synthetic cache event

### registerExpiry

    protected void registerExpiry(java.lang.Object oKey,
                                  long ldtExpire)

  Register an expiry for the specified key.

  Parameters:
    `oKey` - the key of the entry to expire
    `ldtExpire` - the time to expire the entry

### unregisterExpiry

    protected void unregisterExpiry(java.lang.Object oKey,
                                    long ldtExpire)

  Unregister the specified key expiry that is registered to expire at the specified time.

  Parameters:
    `oKey` - the key that is set to expire
    `ldtExpire` - the time that the key is set to expire

### verifyNoNulls

    protected static void verifyNoNulls(java.util.Collection collection,
                                        java.lang.String sAssert)

  Check the passed collection for nulls, and fail if it contains any.

  Parameters:
    `collection` - a Collection
    `sAssert` - the human-readable description of the error if any nulls are found in the passed Collection

### putOne

    protected static void putOne(java.util.Map map,
                                 java.lang.Object oKey,
                                 java.lang.Object oValue,
                                 boolean fPutBlind)

  Helper to put a value into a map using either the `put` or `putAll` method.

  Parameters:
    `map` - the Map to put into
    `oKey` - the key to put
    `oValue` - the value to put
    `fPutBlind` - true to use the putBlind optimization

### evict

    public void evict()

  Flush items that have expired.

  Since:
    Coherence 3.2

### evict

    protected static void evict(java.util.Map map)

  If the passed Map supports it, evict its expired data.

  Parameters:
    `map` - a Map that may or may not support the requesting of an eviction of expired data
  Since:
    Coherence 3.2

### warnMissingEvent

    protected void warnMissingEvent(java.lang.Object oKey,
                                    int nId,
                                    boolean fFront)

  An expected event did not get raised. Try to report it to the log.

  Parameters:
    `oKey` - the key for which an event is missing
    `nId` - the event type that is missing
    `fFront` - true if the event was expected to come from the front map, false if from the back map

### warnUnfathomable

    protected void warnUnfathomable(MapEvent evt)

  Something totally inexplicable has occurred. Try to report it to the log.

  Parameters:
    `evt` - the event that cannot be explained

### warnEventSequence

    protected static void warnEventSequence(MapEvent evtOld,
                                            MapEvent evtNew)

  Issue a one-time warning that events are being received in an order than cannot be explained by normal operation according to the contracts expected by this OverflowMap.

  Parameters:
    `evtOld` - the previous (potentially amalgamated) event
    `evtNew` - the new event

### instantiateEntrySet

    protected java.util.Set instantiateEntrySet()

  Factory pattern: Create a Set that represents the entries in the Map.

  Overrides:
    `instantiateEntrySet` in class `AbstractKeySetBasedMap`
  Returns:
    a new instance of Set that represents the entries in the Map

### instantiateInternalKeySet

    protected java.util.Set instantiateInternalKeySet()

  Factory pattern: Create a read-only Set of keys in the Overflow Map

  Returns:
    a new instance of Set that represents the keys in the Map

### instantiateStatus

    protected OverflowMap.Status instantiateStatus()

  Factory method: Instantiate a Status object.

  Returns:
    a new Status object

### instantiateFrontMapListener

    protected MapListener instantiateFrontMapListener()

  Factory pattern: Front Map Listener.

  Returns:
    a new instance of the listener for the front map

### instantiateBackMapListener

    protected MapListener instantiateBackMapListener()

  Factory pattern: Back Map Listener.

  Returns:
    a new instance of the listener for the back map

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.