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 SimpleOverflowMap

    java.lang.Object
      com.tangosol.util.Base
          com.tangosol.util.AbstractKeyBasedMap
              com.tangosol.net.cache.SimpleOverflowMap

All Implemented Interfaces:
  java.util.Map

    public class SimpleOverflowMap

extends AbstractKeyBasedMap

A non-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 SimpleOverflowMap is not observable, and as such it is assumed to be a passive data structure. In other words, it does not support item expiration or other types of "self-generating" events. As such, it may be more efficient for many common use cases that would benefit from the complete avoidance of event handling. As a second effect of being a passive data structure, the implementation is able to avoid tracking all of its entries; instead it tracks only entries that are in the front map and those that currently have a pending event or an in-flight operation occurring. This means that huge key sets are possible, since only keys in the front map will be managed in memory by the overflow map, but it means that some operations that would benefit from knowing the entire set of keys will be more expensive. Examples of operations that would be less efficient as a result include `containsKey()`, `size()`, `keySet().iterator()`, etc.

Since:
  Coherence 3.1
Author:
  cp 2005.07.11

Nested Class Summary
`protected static class` | `SimpleOverflowMap.FrontFilterConverter` A combination Filter and Converter used to iterate through the status map in order to iterate through the front keys.
`protected class` | `SimpleOverflowMap.FrontMapListener` A listener for the front map that moves evictions to the back map.
`protected static class` | `SimpleOverflowMap.HashcodeComparator` A stateless Comparator that compares `Object.hashCode()` values.
`protected class` | `SimpleOverflowMap.KeyIterator` An Iterator implementation that attempts to provide the most resilient and most up-to-date view of the keys in the OverflowMap.
`protected static class` | `SimpleOverflowMap.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.AbstractKeyBasedMap
`AbstractKeyBasedMap.EntrySet, AbstractKeyBasedMap.KeySet, AbstractKeyBasedMap.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.
`protected java.util.Map` | `m_mapBack` The "back" map, which the front overflows to.
`protected ObservableMap` | `m_mapFront` The "front" map, which is size-limited.
`protected java.util.Map` | `m_mapMiss` The miss cache; may be null.
`protected SimpleCacheStatistics` | `m_stats` The CacheStatistics object maintained by this cache.

Constructor Summary
`SimpleOverflowMap(ObservableMap mapFront, java.util.Map mapBack)` Construct a SimpleOverflowMap using two specified maps: FrontMap (aka "cache" or "shallow") and BackMap (aka "file" or "deep")
`SimpleOverflowMap(ObservableMap mapFront, java.util.Map mapBack, java.util.Map mapMiss)` Construct a SimpleOverflowMap using three specified maps: Front Map (aka "cache" or "shallow") and Back Map (aka "file" or "deep") Miss Cache

Method Summary
`protected SimpleOverflowMap.Status[]` | `beginBulkKeyProcess(java.lang.Object[] aoKey)` Begin key-level procecessing for any number of keys.
`protected SimpleOverflowMap.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.
`boolean` | `containsKey(java.lang.Object oKey)` Returns `true` if this map contains a mapping for the specified key.
`protected void` | `endBulkKeyProcess(java.lang.Object[] aoKey, SimpleOverflowMap.Status[] aStatus)` Finish the processing of any number of keys.
`protected void` | `endKeyProcess(java.lang.Object oKey, SimpleOverflowMap.Status status)` Finish the processing of a single key.
`protected void` | `endMapProcess()` Release exclusive access for the OverflowMap.
`java.lang.Object` | `get(java.lang.Object oKey)` Returns the value to which this map maps the specified key.
`java.util.Map` | `getBackMap()` Returns 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.
`ObservableMap` | `getFrontMap()` Returns the front Map.
`protected MapListener` | `getFrontMapListener()` Get the MapListener for the front map.
`java.util.Map` | `getMissCache()` Returns the optional miss cache.
`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 MapListener` | `instantiateFrontMapListener()` Factory pattern: Front Map Listener.
`protected SimpleOverflowMap.Status` | `instantiateStatus()` Factory method: Instantiate a Status object.
`boolean` | `isEmpty()` Returns `true` if this map contains no key-value mappings.
`boolean` | `isFrontPutBlind()` Determine if the front Map is more efficiently updated using putAll.
`boolean` | `isNullValuesAllowed()` Determine if null values are permitted.
`protected java.util.Iterator` | `iterateKeys()` Create an iterator over the keys in this 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 void` | `processDeferredEvents()` Process deferred events, if there are any.
`protected void` | `processFrontEvent(SimpleOverflowMap.Status status, MapEvent evt)` 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.
`void` | `putAll(java.util.Map map)` Copies all of the mappings from the specified map to this map.
`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.
`java.lang.Object` | `remove(java.lang.Object oKey)` Removes the mapping for this key from this map if present.
`protected boolean` | `removeBlind(java.lang.Object oKey)` Removes the mapping for this key from this map if present.
`protected void` | `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.
`int` | `size()` Returns the number of key-value mappings in this map.
`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.

Methods inherited from class com.tangosol.util.AbstractKeyBasedMap
`clone, containsValue, entrySet, equals, getAll, hashCode, instantiateEntrySet, instantiateKeySet, instantiateValues, keySet, toString, 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

### m_mapFront

    protected ObservableMap m_mapFront

  The "front" map, which is size-limited.

### m_mapBack

    protected java.util.Map m_mapBack

  The "back" map, which the front overflows to.

### m_mapMiss

    protected java.util.Map m_mapMiss

  The miss cache; may be null.

### m_stats

    protected SimpleCacheStatistics m_stats

  The CacheStatistics object maintained by this cache.

Constructor Detail

### SimpleOverflowMap

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

  Construct a SimpleOverflowMap using two specified maps:
  - FrontMap (aka "cache" or "shallow") and
  - BackMap (aka "file" or "deep")

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

### SimpleOverflowMap

    public SimpleOverflowMap(ObservableMap mapFront,
                             java.util.Map mapBack,
                             java.util.Map mapMiss)

  Construct a SimpleOverflowMap using three specified maps:
  - Front Map (aka "cache" or "shallow") and
  - Back Map (aka "file" or "deep")
  - Miss Cache

  Parameters:
    `mapFront` - front map
    `mapBack` - back map
    `mapMiss` - an optional miss cache

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 `AbstractKeyBasedMap`
  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 `AbstractKeyBasedMap`
  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 `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 `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 `AbstractKeyBasedMap`
  Returns:
    the number of key-value mappings in this map

### iterateKeys

    protected java.util.Iterator iterateKeys()

  Create an iterator over the keys in this Map.

  Specified by:
    `iterateKeys` in class `AbstractKeyBasedMap`
  Returns:
    a new instance of an Iterator over the keys in this Map

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

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

### getMissCache

    public java.util.Map getMissCache()

  Returns the optional miss cache.

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

  Returns:
    the miss cache, or null if there is no miss cache

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

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

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

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

### instantiateFrontMapListener

    protected MapListener instantiateFrontMapListener()

  Factory pattern: Front Map Listener.

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

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

### processFrontEvent

    protected void processFrontEvent(SimpleOverflowMap.Status status,
                                     MapEvent evt)

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

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

### beginKeyProcess

    protected SimpleOverflowMap.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 `SimpleOverflowMap.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.SimpleOverflowMap.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,
                                 SimpleOverflowMap.Status status)

  Finish the processing of a single key.

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

### beginBulkKeyProcess

    protected SimpleOverflowMap.Status[] beginBulkKeyProcess(java.lang.Object[] aoKey)

  Begin key-level procecessing for any number of keys.

  Parameters:
    `aoKey` - an array of zero or more keys; note that this array may be re-ordered by this method
  Returns:
    an array of Status objects corresponding to the passed keys
  See Also:
    `beginKeyProcess(Object)`

### endBulkKeyProcess

    protected void endBulkKeyProcess(java.lang.Object[] aoKey,
                                     SimpleOverflowMap.Status[] aStatus)

  Finish the processing of any number of keys.

  Parameters:
    `aoKey` - the same array of keys as were passed to `beginBulkKeyProcess(java.lang.Object[])`
    `aStatus` - the array of Status objects returned from the call to `beginBulkKeyProcess(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.

### processDeferredEvents

    protected void processDeferredEvents()

  Process deferred events, if there are any. This implementation processes only the first deferred event that it encounters.

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

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

### instantiateStatus

    protected SimpleOverflowMap.Status instantiateStatus()

  Factory method: Instantiate a Status object.

  Returns:
    a new Status object

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.