Package org.codehaus.plexus.util

Class 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

    • Nested Class Summary

      • Nested classes/interfaces inherited from interface java.util.Map

        java.util.Map.Entry<K extends java.lang.Object,​V extends java.lang.Object>

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private FastMap _backingFastMap
      Holds the FastMap backing this collection (null if generic backing map).
      private java.util.Map _backingMap
      Holds the generic map backing this collection.
      private java.lang.Object[] _keys
      Holds the keys being cached.
      private FastMap _keysMap
      Holds the keys of the backing map (key-to-key mapping).
      private int _mask
      Holds the cache's mask (capacity - 1).
      private java.lang.Object[] _values
      Holds the values being cached.

    • Constructor Summary

      Constructors 
      Constructor 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 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.
      private java.lang.Object getCacheMissed​(java.lang.Object key, int index)  
      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

    • Field Detail

      • _backingFastMap

        private final FastMap _backingFastMap
        Holds the FastMap backing this collection (null if generic backing map).

      • _backingMap

        private final java.util.Map _backingMap
        Holds the generic map backing this collection.

      • _keysMap

        private final FastMap _keysMap
        Holds the keys of the backing map (key-to-key mapping). (null if FastMap backing map).

      • _mask

        private final int _mask
        Holds the cache's mask (capacity - 1).

      • _keys

        private final java.lang.Object[] _keys
        Holds the keys being cached.

      • _values

        private final java.lang.Object[] _values
        Holds the values being cached.

    • 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 maintain 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.

      • getCacheMissed

        private java.lang.Object getCacheMissed​(java.lang.Object key,
                                        int index)

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