org.codehaus.plexus.util

## Class CachedMap

- java.lang.Object
- - org.codehaus.plexus.util.CachedMap

- All Implemented Interfaces:
    java.util.Map

      public final class CachedMap
      extends java.lang.Object
      implements java.util.Map

  This class provides cache access to `Map` collections.

  Instance of this class can be used as "proxy" for any collection implementing the `java.util.Map` interface.

  Typically, `CachedMap` are used to accelerate access to large collections when the access to the collection is not evenly distributed (associative cache). The performance gain is about 50% for the fastest hash map collections (e.g. `FastMap`). For slower collections such as `java.util.TreeMap`, non-resizable `FastMap` (real-time) or database access, performance can be of several orders of magnitude.

  Note: The keys used to access elements of a `CachedMap` do not need to be immutable as they are not stored in the cache (only keys specified by the `put(java.lang.Object, java.lang.Object)` method are). In other words, access can be performed using mutable keys as long as these keys can be compared for equality with the real map's keys (e.g. same `hashCode` values).

  This implementation is not synchronized. Multiple threads accessing or modifying the collection must be synchronized externally.

  This class is public domain (not copyrighted).

  Version:
    5.3, October 30, 2003
  Author:
    Jean-Marie Dautelle

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface java.util.Map

      `java.util.Map.Entry<K,V>`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CachedMap()` Creates a cached map backed by a `FastMap`.
    `CachedMap(int cacheSize)` Creates a cached map backed by a `FastMap` and having the specified cache size.
    `CachedMap(int cacheSize, java.util.Map backingMap)` Creates a cached map backed by the specified map and having the specified cache size.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clear()` Removes all mappings from this map (optional operation).
    `boolean` | `containsKey(java.lang.Object key)` Indicates if this map contains a mapping for the specified key.
    `boolean` | `containsValue(java.lang.Object value)` Returns `true` if this map maps one or more keys to the specified value.
    `java.util.Set` | `entrySet()` Returns an unmodifiable 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()` Flushes the key/value pairs being cached.
    `java.lang.Object` | `get(java.lang.Object key)` Returns the value to which this map maps the specified key.
    `java.util.Map` | `getBackingMap()` Returns the backing map.
    `int` | `getCacheSize()` Returns the actual cache size.
    `int` | `hashCode()` Returns the hash code value for this map.
    `boolean` | `isEmpty()` Returns `true` if this map contains no key-value mappings.
    `java.util.Set` | `keySet()` Returns an unmodifiable view of the keys contained in this map.
    `java.lang.Object` | `put(java.lang.Object key, java.lang.Object value)` 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 (optional operation).
    `java.lang.Object` | `remove(java.lang.Object key)` Removes the mapping for this key from this map if it is present.
    `int` | `size()` Returns the number of key-value mappings in this map.
    `java.util.Collection` | `values()` Returns an unmodifiable view of the values contained in this map.

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface java.util.Map

      `compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll`

- - ### Constructor Detail

    - #### CachedMap

          public CachedMap()

      Creates a cached map backed by a `FastMap`. The default cache size and map capacity is set to `256` entries.

    - #### CachedMap

          public CachedMap(int cacheSize)

      Creates a cached map backed by a `FastMap` and having the specified cache size.
      Parameters:
        `cacheSize` - the cache size, the actual cache size is the first power of 2 greater or equal to `cacheSize`. This is also the initial capacity of the backing map.

    - #### CachedMap

          public CachedMap(int cacheSize,
                           java.util.Map backingMap)

      Creates a cached map backed by the specified map and having the specified cache size. In order to maitain cache veracity, it is critical that all update to the backing map is accomplished through the `CachedMap` instance; otherwise `flush()` has to be called.
      Parameters:
        `cacheSize` - the cache size, the actual cache size is the first power of 2 greater or equal to `cacheSize`.
        `backingMap` - the backing map to be "wrapped" in a cached map.

  - ### Method Detail

    - #### getCacheSize

          public int getCacheSize()

      Returns the actual cache size.
      Returns:
        the cache size (power of 2).

    - #### getBackingMap

          public java.util.Map getBackingMap()

      Returns the backing map. If the backing map is modified directly, this `CachedMap` has to be flushed.
      Returns:
        the backing map.
      See Also:
        `flush()`

    - #### flush

          public void flush()

      Flushes the key/value pairs being cached. This method should be called if the backing map is externally modified.

    - #### get

          public java.lang.Object get(java.lang.Object key)

      Returns the value to which this map maps the specified key. First, the cache is being checked, then if the cache does not contains the specified key, the backing map is accessed and the key/value pair is stored in the cache.
      Specified by:
        `get` in interface `java.util.Map`
      Parameters:
        `key` - the key whose associated value is to be returned.
      Returns:
        the value to which this map maps the specified key, or `null` if the map contains no mapping for this key.
      Throws:
        `java.lang.ClassCastException` - if the key is of an inappropriate type for the backing map (optional).
        `java.lang.NullPointerException` - if the key is `null`.

    - #### put

          public java.lang.Object put(java.lang.Object key,
                                      java.lang.Object value)

      Associates the specified value with the specified key in this map.
      Specified by:
        `put` in interface `java.util.Map`
      Parameters:
        `key` - the key with which the specified value is to be associated.
        `value` - the value to be associated with the specified key.
      Returns:
        the previous value associated with specified key, or `null` if there was no mapping for the key.
      Throws:
        `java.lang.UnsupportedOperationException` - if the `put` operation is not supported by the backing map.
        `java.lang.ClassCastException` - if the class of the specified key or value prevents it from being stored in this map.
        `java.lang.IllegalArgumentException` - if some aspect of this key or value prevents it from being stored in this map.
        `java.lang.NullPointerException` - if the key is `null`.

    - #### remove

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

      Removes the mapping for this key from this map if it is present.
      Specified by:
        `remove` in interface `java.util.Map`
      Parameters:
        `key` - 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.
      Throws:
        `java.lang.ClassCastException` - if the key is of an inappropriate type for the backing map (optional).
        `java.lang.NullPointerException` - if the key is `null`.
        `java.lang.UnsupportedOperationException` - if the `remove` method is not supported by the backing map.

    - #### containsKey

          public boolean containsKey(java.lang.Object key)

      Indicates if this map contains a mapping for the specified key.
      Specified by:
        `containsKey` in interface `java.util.Map`
      Parameters:
        `key` - the key whose presence in this map is to be tested.
      Returns:
        `true` if this map contains a mapping for the specified key; `false` otherwise.

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

    - #### isEmpty

          public boolean isEmpty()

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

    - #### containsValue

          public boolean containsValue(java.lang.Object value)

      Returns `true` if this map maps one or more keys to the specified value.
      Specified by:
        `containsValue` in interface `java.util.Map`
      Parameters:
        `value` - value whose presence in this map is to be tested.
      Returns:
        `true` if this map maps one or more keys to the specified value.
      Throws:
        `java.lang.ClassCastException` - if the value is of an inappropriate type for the backing map (optional).
        `java.lang.NullPointerException` - if the value is `null` and the backing map does not not permit `null` values.

    - #### putAll

          public void putAll(java.util.Map map)

      Copies all of the mappings from the specified map to this map (optional operation). This method automatically flushes the cache.
      Specified by:
        `putAll` in interface `java.util.Map`
      Parameters:
        `map` - the mappings to be stored in this map.
      Throws:
        `java.lang.UnsupportedOperationException` - if the `putAll` method is not supported by the backing map.
        `java.lang.ClassCastException` - if the class of a key or value in the specified map prevents it from being stored in this map.
        `java.lang.IllegalArgumentException` - some aspect of a key or value in the specified map prevents it from being stored in this map.
        `java.lang.NullPointerException` - the specified map is `null`, or if the backing map does not permit `null` keys or values, and the specified map contains `null` keys or values.

    - #### clear

          public void clear()

      Removes all mappings from this map (optional operation). This method automatically flushes the cache.
      Specified by:
        `clear` in interface `java.util.Map`
      Throws:
        `java.lang.UnsupportedOperationException` - if clear is not supported by the backing map.

    - #### keySet

          public java.util.Set keySet()

      Returns an unmodifiable view of the keys contained in this map.
      Specified by:
        `keySet` in interface `java.util.Map`
      Returns:
        an unmodifiable view of the keys contained in this map.

    - #### values

          public java.util.Collection values()

      Returns an unmodifiable view of the values contained in this map.
      Specified by:
        `values` in interface `java.util.Map`
      Returns:
        an unmodifiable view of the values contained in this map.

    - #### entrySet

          public java.util.Set entrySet()

      Returns an unmodifiable view of the mappings contained in this map. Each element in the returned set is a `Map.Entry`.
      Specified by:
        `entrySet` in interface `java.util.Map`
      Returns:
        an unmodifiable view of the mappings contained in this map.

    - #### 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.lang.Object`
      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.lang.Object`
      Returns:
        the hash code value for this map.