Skip navigation links

Overview | Package | Class | Tree | Index | Help
| Oracle® Coherence Java API Reference Release 3.6.0.0 E15725-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.tangosol.net.cache
Class CachingMap

`java.lang.Object
com.tangosol.net.cache.CachingMap`

All Implemented Interfaces:
  Map

Direct Known Subclasses:
  NearCache

      public class CachingMap

extends Object
implements Map

Map implementation that wraps two maps - a front map (assumed to be "inexpensive" and probably "incomplete") and a back map (assumed to be "complete" and "correct", but more "expensive") - using a read-through/write-through approach.

If the back map implements ObservableMap interface, the CachingMap provides four different strategies of invalidating the front map entries that have changed by other processes in the back map:

- LISTEN_NONE strategy instructs the cache not to listen for invalidation events at all. This is the best choice for raw performance and scalability when business requirements permit the use of data which might not be absolutely current. Freshness of data can be guaranteed by use of a sufficiently brief eviction policy for the front map;
- LISTEN_PRESENT strategy instructs the CachingMap to listen to the back map events related only to the items currently present in the front map. This strategy works best when each instance of a front map contains distinct subset of data relative to the other front map instances (e.g. sticky data access patterns);
- LISTEN_ALL strategy instructs the CachingMap to listen to all back map events. This strategy is optimal for read-heavy tiered access patterns where there is significant overlap between the different instances of front maps;
- LISTEN_AUTO strategy instructs the CachingMap implementation to switch automatically between LISTEN_PRESENT and LISTEN_ALL strategies based on the cache statistics.

The front map implementation is assumed to be thread safe; additionally any modifications to the front map are allowed only after the corresponding lock is acquired against the `ControlMap`.

Note: null values are not cached in the front map and therefore this implementation is not optimized for maps that allow null values to be stored.

Author:
  ag/gg 2002.09.10, gg 2003.10.16

Nested Class Summary
`protected class` | `CachingMap.BackMapListener` MapListener for back map responsible for keeping the front map coherent with the back map.
`protected class` | `CachingMap.FrontMapListener` MapListener for front map responsible for deregistering back map listeners upon front map eviction.

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

Field Summary
`static int` | `LISTEN_ALL` Invalidation strategy that instructs the CachingMap to listen to all back map events; this strategy is preferred when updates to the back map are frequent and with high probability come from the outside of this CachingMap; for example multiple CachingMap instances using the same back map with a large degree of key set overlap between front maps.
`static int` | `LISTEN_AUTO` Invalidation strategy that instructs the CachingMap implementation to switch automatically between LISTEN_PRESENT and LISTEN_ALL strategies based on the cache statistics.
`static int` | `LISTEN_NONE` No invalidation strategy.
`static int` | `LISTEN_PRESENT` Invalidation strategy that instructs the CachingMap to listen to the back map events related only to the items currently present in the front map; this strategy serves best when the changes to the back map come mostly from the CachingMap itself.
`protected int` | `m_nStrategyCurrent` The current invalidation strategy, which at times could be different from the target strategy.
`protected int` | `m_nStrategyTarget` The invalidation strategy that this map is to use.

Constructor Summary
`CachingMap(Map mapFront, Map mapBack)` Construct a CachingMap using two specified maps: FrontMap (aka "cache", "near" or "shallow") and BackMap (aka "actual", "real" or "deep").
`CachingMap(Map mapFront, Map mapBack, int nStrategy)` Construct a CachingMap using two specified maps: FrontMap (aka "cache", "near" or "shallow") and BackMap (aka "actual", "real" or "deep") and using the specified front map invalidation strategy.

Method Summary
`void` | `clear()` Clears both the front and back maps.
`boolean` | `containsKey(Object oKey)` Check whether or not this map contains a mapping for the specified key.
`boolean` | `containsValue(Object oValue)` Check whether or not this CachingMap maps one or more keys to the specified value.
`protected int` | `ensureInvalidationStrategy()` Ensure that a strategy has been choosen and that any appropriate global listeners have been registered.
`Set` | `entrySet()` Obtain an set view of the mappings contained in this map.
`Object` | `get(Object oKey)` Obtain the value to which this map maps the specified key.
`Map` | `getAll(Collection colKeys)` Get all the specified keys, if they are in the cache.
`Map` | `getBackMap()` Obtain the back map reference.
`CacheStatistics` | `getCacheStatistics()` Obtain the CacheStatistics for this cache.
`ConcurrentMap` | `getControlMap()` Obtain the ConcurrentMap that should be used to synchronize the front map modification access.
`Map` | `getFrontMap()` Obtain the front map reference.
`long` | `getInvalidationHits()` Determine the rough number of front map invalidation hits since the cache statistics were last reset.
`long` | `getInvalidationMisses()` Determine the rough number of front map invalidation misses since the cache statistics were last reset.
`int` | `getInvalidationStrategy()` Obtain the invalidation strategy used by this CachingMap.
`long` | `getTotalRegisterListener()` Determine the total number of `registerListener(Object oKey)` operations since the cache statistics were last reset.
`protected MapListener` | `instantiateBackMapListener()` Factory pattern: instantiate back map listener.
`protected CachingMap.FrontMapListener` | `instantiateFrontMapListener()` Factory pattern: instantiate front map listener.
`protected void` | `invalidateFront(Object oKey)` Invalidate the key from the front.
`protected boolean` | `isCoherent()` Determine if changes to the back map affect the front map so that data in the front map stays in sync.
`boolean` | `isEmpty()` Check whether or not this map is empty.
`Set` | `keySet()` Obtain an set view of the keys contained in this map.
`Object` | `put(Object oKey, Object oValue)` Associates the specified value with the specified key in this map.
`Object` | `put(Object oKey, Object oValue, boolean fReturn, long cMillis)` Implementation of put method that optionally skips the return value retrieval and allows to specify an expiry for the cache entry.
`void` | `putAll(Map map)` Copy all of the mappings from the specified map to this map.
`protected void` | `registerFrontListener()` Register the global front map listener.
`protected void` | `registerListener()` Register the global back map listener.
`protected void` | `registerListener(Object oKey)` Register the back map listener for the specified key.
`void` | `release()` Release the CachingMap.
`Object` | `remove(Object oKey)` Remove the mapping for this key from this map if present.
`protected void` | `resetInvalidationStrategy()` Reset the "current invalidation strategy" flag.
`int` | `size()` Return the number of key-value mappings in this map.
`String` | `toString()` For debugging purposes, format the contents of the CachingMap in a human readable format.
`protected void` | `unregisterFrontListener()` Unregister the global front map listener.
`protected void` | `unregisterListener()` Unregister the global back map listener.
`protected void` | `unregisterListener(Object oKey)` Unregister the back map listener for the specified key.
`protected void` | `validate(MapEvent evt)` Validate the front map entry for the specified back map event.
`Collection` | `values()` Obtain an collection of the values contained in this map.

Methods inherited from interface java.util.Map
`equals, hashCode`

Field Detail

### LISTEN_NONE

    public static final int LISTEN_NONE

  No invalidation strategy.
  See Also:
    Constant Field Values

### LISTEN_PRESENT

    public static final int LISTEN_PRESENT

  Invalidation strategy that instructs the CachingMap to listen to the back map events related only to the items currently present in the front map; this strategy serves best when the changes to the back map come mostly from the CachingMap itself.
  See Also:
    Constant Field Values

### LISTEN_ALL

    public static final int LISTEN_ALL

  Invalidation strategy that instructs the CachingMap to listen to all back map events; this strategy is preferred when updates to the back map are frequent and with high probability come from the outside of this CachingMap; for example multiple CachingMap instances using the same back map with a large degree of key set overlap between front maps.
  See Also:
    Constant Field Values

### LISTEN_AUTO

    public static final int LISTEN_AUTO

  Invalidation strategy that instructs the CachingMap implementation to switch automatically between LISTEN_PRESENT and LISTEN_ALL strategies based on the cache statistics.
  See Also:
    Constant Field Values

### m_nStrategyTarget

    protected int m_nStrategyTarget

  The invalidation strategy that this map is to use.

### m_nStrategyCurrent

    protected int m_nStrategyCurrent

  The current invalidation strategy, which at times could be different from the target strategy.

Constructor Detail

### CachingMap

    public CachingMap(Map mapFront,
                      Map mapBack)

  Construct a CachingMap using two specified maps:
  - FrontMap (aka "cache", "near" or "shallow") and
  - BackMap (aka "actual", "real" or "deep").
  If the BackMap implements the ObservableMap interface a listener will be added to the BackMap to invalidate FrontMap items updated [externally] in the back map using the `LISTEN_AUTO` strategy.
  Parameters:
    `mapBack` - back map
    `mapFront` - front map
  See Also:
    `SeppukuMapListener`

### CachingMap

    public CachingMap(Map mapFront,
                      Map mapBack,
                      int nStrategy)

  Construct a CachingMap using two specified maps:
  - FrontMap (aka "cache", "near" or "shallow") and
  - BackMap (aka "actual", "real" or "deep")
  and using the specified front map invalidation strategy.
  Parameters:
    `mapFront` - front map
    `mapBack` - back map
    `nStrategy` - specifies the strategy used for the front map invalidation; valid values are LISTEN_* constants
  Since:
    Coherence 2.3

Method Detail

### release

    public void release()

  Release the CachingMap. If the BackMap implements an ObservableMap calling this method is necessary to remove the BackMap listener. Any access to the CachingMap which has been released will cause IllegalStateException.

### getFrontMap

    public Map getFrontMap()

  Obtain the front map reference.

  Note: direct modifications of the returned map may cause an unpredictable behavior of the CachingMap.

  Returns:
    the front Map

### getBackMap

    public Map getBackMap()

  Obtain the back map reference.

  Note: direct modifications of the returned map may cause an unpredictable behavior of the CachingMap.

  Returns:
    the back Map

### getInvalidationStrategy

    public int getInvalidationStrategy()

  Obtain the invalidation strategy used by this CachingMap.
  Returns:
    one of LISTEN_* values

### getControlMap

    public ConcurrentMap getControlMap()

  Obtain the ConcurrentMap that should be used to synchronize the front map modification access.
  Returns:
    a ConcurrentMap controlling the front map modifications

### isCoherent

    protected boolean isCoherent()

  Determine if changes to the back map affect the front map so that data in the front map stays in sync.
  Returns:
    true if the front map has a means to stay in sync with the back map so that it does not contain stale data

### getCacheStatistics

    public CacheStatistics getCacheStatistics()

  Obtain the CacheStatistics for this cache.
  Returns:
    a CacheStatistics object

### clear

    public void clear()

  Clears both the front and back maps.
  Specified by:
    `clear` in interface `Map`

### containsKey

    public boolean containsKey(Object oKey)

  Check whether or not this map contains a mapping for the specified key.
  Specified by:
    `containsKey` in interface `Map`
  Parameters:
    `oKey` - key whose presence in this map is to be tested.
  Returns:
    `true` if this map contains a mapping for the specified key, `false` otherwise.

### containsValue

    public boolean containsValue(Object oValue)

  Check whether or not this CachingMap maps one or more keys to the specified value.
  Specified by:
    `containsValue` in interface `Map`
  Parameters:
    `oValue` - value whose presence in this map is to be tested.
  Returns:
    `true` if this CachingMap maps one or more keys to the specified value, `false` otherwise

### entrySet

    public Set entrySet()

  Obtain an set view of the mappings contained in this map. If there is a listener for the back map, then the set will be mutable; otherwise the returned set will be immutable. The returned set reflects the full contents of the back map.
  Specified by:
    `entrySet` in interface `Map`
  Returns:
    a set view of the mappings contained in this map.

### get

    public Object get(Object oKey)

  Obtain the value to which this map maps the specified key.
  Specified by:
    `get` in interface `Map`
  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
  See Also:
    `Map.containsKey(Object)`

### getAll

    public Map getAll(Collection colKeys)

  Get all the specified keys, if they are in the cache. 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.

  Note: this implementation does not differentiate between missing keys or null values stored in the back map; in both cases the returned map will not contain the corresponding entry.

  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 `col`
  Since:
    Coherence 2.5

### isEmpty

    public boolean isEmpty()

  Check whether or not this map is empty. Expensive: always reflects the contents of the underlying cache.
  Specified by:
    `isEmpty` in interface `Map`
  Returns:
    `true` if this map contains no key-value mappings.

### keySet

    public Set keySet()

  Obtain an set view of the keys contained in this map. If there is a listener for the back map, then the set will be mutable; otherwise the returned set will be immutable. The returned set reflects the full contents of the back map.
  Specified by:
    `keySet` in interface `Map`
  Returns:
    a set view of the keys contained in this map.

### put

    public Object put(Object oKey,
                      Object oValue)

  Associates the specified value with the specified key in this map.
  Specified by:
    `put` in interface `Map`
  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.

### put

    public Object put(Object oKey,
                      Object oValue,
                      boolean fReturn,
                      long cMillis)

  Implementation of put method that optionally skips the return value retrieval and allows to specify an expiry for the cache entry.
  Parameters:
    `oKey` - the key
    `oValue` - the value
    `fReturn` - if true, the return value is required; otherwise the return value will be ignored
    `cMillis` - the number of milliseconds until the cache entry will expire
  Returns:
    previous value (if required)
  Throws:
    `UnsupportedOperationException` - if the requested expiry is a positive value and either the front map or the back map implementations do not support the expiration functionality
  See Also:
    `CacheMap.put(Object oKey, Object oValue, long cMillis)`

### putAll

    public void putAll(Map map)

  Copy all of the mappings from the specified map to this map.
  Specified by:
    `putAll` in interface `Map`
  Parameters:
    `map` - Mappings to be stored in this map

### invalidateFront

    protected void invalidateFront(Object oKey)

  Invalidate the key from the front. The caller must have the key locked.
  Parameters:
    `oKey` - the key to invalidate

### validate

    protected void validate(MapEvent evt)

  Validate the front map entry for the specified back map event.
  Parameters:
    `evt` - the MapEvent from the back map

### remove

    public Object remove(Object oKey)

  Remove the mapping for this key from this map if present. Expensive: updates both the underlying cache and the local cache.
  Specified by:
    `remove` in interface `Map`
  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()

  Return the number of key-value mappings in this map. Expensive: always reflects the contents of the underlying cache.
  Specified by:
    `size` in interface `Map`
  Returns:
    the number of key-value mappings in this map

### values

    public Collection values()

  Obtain an collection of the values contained in this map. If there is a listener for the back map, then the collection will be mutable; otherwise the returned collection will be immutable. The returned collection reflects the full contents of the back map.
  Specified by:
    `values` in interface `Map`
  Returns:
    a collection view of the values contained in this map

### getInvalidationHits

    public long getInvalidationHits()

  Determine the rough number of front map invalidation hits since the cache statistics were last reset. <p/> An invalidation hit is an externally induced map event for an entry that exists in the front map.
  Returns:
    the number of cache invalidation hits

### getInvalidationMisses

    public long getInvalidationMisses()

  Determine the rough number of front map invalidation misses since the cache statistics were last reset. An invalidation miss is an externally induced map event for an entry that does not exists in the front map.
  Returns:
    the number of cache invalidation misses

### getTotalRegisterListener

    public long getTotalRegisterListener()

  Determine the total number of `registerListener(Object oKey)` operations since the cache statistics were last reset.
  Returns:
    the total number of listener registrations

### toString

    public String toString()

  For debugging purposes, format the contents of the CachingMap in a human readable format.
  Returns:
    a String representation of the CachingMap object

### registerListener

    protected void registerListener()

  Register the global back map listener.

### unregisterListener

    protected void unregisterListener()

  Unregister the global back map listener.

### registerListener

    protected void registerListener(Object oKey)

  Register the back map listener for the specified key.
  Parameters:
    `oKey` - the key

### unregisterListener

    protected void unregisterListener(Object oKey)

  Unregister the back map listener for the specified key.
  Parameters:
    `oKey` - the key

### registerFrontListener

    protected void registerFrontListener()

  Register the global front map listener.

### unregisterFrontListener

    protected void unregisterFrontListener()

  Unregister the global front map listener.

### ensureInvalidationStrategy

    protected int ensureInvalidationStrategy()

  Ensure that a strategy has been choosen and that any appropriate global listeners have been registered.
  Returns:
    the current strategy

### resetInvalidationStrategy

    protected void resetInvalidationStrategy()

  Reset the "current invalidation strategy" flag. <p/> This method should be called only while the access to the front map is fully synchronzied and the front map is empty to prevent stalled data.

### instantiateBackMapListener

    protected MapListener instantiateBackMapListener()

  Factory pattern: instantiate back map listener.
  Returns:
    an instance of back map listener responsible for keeping the front map coherent with the back map

### instantiateFrontMapListener

    protected CachingMap.FrontMapListener instantiateFrontMapListener()

  Factory pattern: instantiate front map listener.
  Returns:
    an instance of front map listener

Skip navigation links

Overview | Package | Class | Tree | Index | Help
| Oracle® Coherence Java API Reference Release 3.6.0.0 E15725-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.