Class LRUTreeMap<K,​V>

  • Type Parameters:
    K - This is the type for the map 'key'. It should be thought of as identical to the java.util.TreeMap type-parameter 'K'
    V - This is the type used by the map for 'value'. It should be thought of as identical to the java.util.TreeMap type-parameter 'V'
    All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, java.util.Map<K,​V>, java.util.NavigableMap<K,​V>, java.util.SortedMap<K,​V>
    public class LRUTreeMap<K,​V>
extends java.util.TreeMap<K,​V>
    A great class, heavily used by the Java Doc Upgrader Tool, that extends Java's TreeMap class to eliminate "Least Recently Used" elements from the Map, effectively creating an 'in-memory cache' for the tool.

    LRU Algorithm: Least Recently Used

    This is identical to a standad java.util.TreeMap<K, V> with the extra stipulation that its size is limited to a user-specified value. Once this TreeMap reaches its maximum-size, it will beging throwing away entries, starting with the oldest, or 'Least Recently Used.'

    This class is identical, in every way, to the Java Standard TreeMap, other than this noted difference.

    This is a Limited TreeMap that is developed for the Java Doc Upgrader package. The feature 'Limited' here means that thee tree will only allow itself to contain a specified number of key-value pairs before it starts to throw older & unused elements away. Mainly, the intention is to use this like an "In-Memory Cache", where the number of elements in the Cache may not grow past a certain, pre-specified, size.

    The Vectorized-HTML lists that Java-HTML creates are efficient, and easy to search, but holding millions of HTMLNode elements may have adverse effects on the Memory-Heap, the pointer-reference tables, etc... If you want to save many HTML pages in memory, and (at the same) set a limit on how many pages can be stored in the JVM's memory before they are removed, that is the goal of the LimTreeMap class.

    Just like with the regular java.util.TreeMap, you may save Vectorized-HTML web-pages into the tree (as tree-values - the 'V' type-parameter), but you may also specify a "Max Number of Elements" to allow in the tree. When the tree has reached its maximum size, any new elements that are added to it will automatically cause the "Least Recently Used" Tree Element to be dropped out of the Map before the new one is inserted.


    LRU: Least Recently Used
    The LRU-algorithm makes it easier to keep a data-structure that holds 20, 50, 100, 500 etc... web-pages (or page-snippets) in Java's memory, without going over a pre-specified maximum number of pages. Computer memory may be much larger than when Java was first designed; however, searching through the pointer-reference tables when there are hundreds of thousands of String-references that cannot be garbage-collected can slow down the Virtual Machine.

    Though primarily used for caching parsed Vectorized-HTML Pages, the class' generic Type-Parameter may be used with any type.


    Finally, the default implementation of the following methods access the tree only through the method that are overloaded by this class. Therefore, the methods inherited from class java.util.TreeMap (including the default methods inherited from java.util.Map) are perfectly sufficient for using; there is no need to reimplement them to update the LRU-Counter. They are only accessing the tree through the overloaded methods provided by this class.


    INHERITED METHDS:
    The list below shows which methods are inherited by this class, not overloaded.

    • java.util.Map: compute, computeIfAbsent, computeIfPresent, getOrDefault, isEmpty, merge, putIfAbsent, remove

    • java.util.TreeMap: descendingKeySet, descendingMap, entrySet, keySet, headMap, navigableKeySet, subMap, tailkMap
    See Also:
    Serialized Form


    • Nested Class Summary

      • Nested classes/interfaces inherited from class java.util.AbstractMap

        java.util.AbstractMap.SimpleEntry<K extends java.lang.Object,​V extends java.lang.Object>, java.util.AbstractMap.SimpleImmutableEntry<K extends java.lang.Object,​V extends java.lang.Object>

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected Torello.Java.Additional.LRUTreeMap.LRUTreeMaps mapLRU
      Keeps a record of the 'Ordering of Use' for the elements in 'this' map.
      protected int MAX_NUM_ELEMENTS
      This is, literally, the maximum number of Key-Value pairs allowed into this instance of LRUTreeMap.
      protected static long serialVersionUID

    • Constructor Summary

      Constructors 
      Constructor Description
      LRUTreeMap​(int maxNumElements)
      Constructs a new, empty tree map, using the natural ordering of its keys.
      LRUTreeMap​(Comparator<? super K> comparator, int maxNumElements)
      Constructs a new, empty tree map, ordered according to the given comparator.
      LRUTreeMap​(Map<? extends K,​? extends V> m, int maxNumElements)
      Constructs a new tree map containing the same mappings as the given map, ordered according to the natural ordering of its keys.
      LRUTreeMap​(SortedMap<K,​? extends V> m, int maxNumElements)
      Constructs a new tree map containing the same mappings and using the same ordering as the specified sorted map.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      Map.Entry<K,​V> ceilingEntry​(K key)
      Returns a key-value mapping associated with the least key greater than or equal to the given 'key', or null if there is no such key.
      K ceilingKey​(K key)
      Returns the least key greater than or equal to the given 'key', or null if there is no such key.
      void clear()
      Removes all of the mappings from 'this' map.
      Object clone()
      Returns a shallow copy of this LRUTreeMap instance.
      boolean containsKey​(Object key)
      Returns TRUE if 'this' map contains a mapping for the specified 'key'.
      boolean containsValue​(Object value)
      Returns TRUE if 'this' map maps one or more keys to the specified 'value'.
      Map.Entry<K,​V> firstEntry()
      Returns a key-value mapping associated with the least key in 'this' map, or null if the map is empty.
      K firstKey()
      Returns the first (lowest) key currently in 'this' map.
      Map.Entry<K,​V> floorEntry​(K key)
      Returns a key-value mapping associated with the greatest key less than or equal to the given 'key', or null if there is no such key.
      K floorKey​(K key)
      Returns the greatest key less than or equal to the given 'key', or null if there is no such key.
      void forEach​(BiConsumer<? super K,​? super V> action)
      Performs the given action for each entry in 'this' map until all entries have been processed or the action throws an exception.
      V get​(Object key)
      Returns the value to which the specified 'key' is mapped, or null if 'this' map contains no mapping for the 'key'.
      int getMaxNumElements()
      This merely retrieves the value stored in MAX_NUM_ELEMENTS.
      Map.Entry<K,​V> higherEntry​(K key)
      Returns a key-value mapping associated with the least key strictly greater than the given 'key', or null if there is no such key.
      K higherKey​(K key)
      Returns the least key strictly greater than the given 'key', or null if there is no such key.
      Map.Entry<K,​V> lastEntry()
      Returns a key-value mapping associated with the greatest key in 'this' map, or null if the map is empty.
      K lastKey()
      Returns the last (highest) key currently in 'this' map.
      Map.Entry<K,​V> lowerEntry​(K key)
      Returns a key-value mapping associated with the greatest key strictly less than the given 'key', or null if there is no such key.
      K lowerKey​(K key)
      Returns the greatest key strictly less than the given 'key', or null if there is no such key.
      Map.Entry<K,​V> pollFirstEntry()
      Removes and returns a key-value mapping associated with the least key in 'this' map, or null if the map is empty.
      Map.Entry<K,​V> pollLastEntry()
      Removes and returns a key-value mapping associated with the greatest key in this map, or null if the map is empty.
      V put​(K key, V value)
      Associates the specified value with the specified key in 'this' map.
      void putAll​(Map<? extends K,​? extends V> map)
      Copies all of the mappings from the specified 'map' to 'this' map.
      V remove​(Object key)
      Removes the mapping for this 'key' from 'this' TreeMap if present.
      V replace​(K key, V value)
      Replaces the entry for the specified 'key' only if it is currently mapped to some value.
      boolean replace​(K key, V oldValue, V newValue)
      Replaces the entry for the specified 'key' only if currently mapped to the specified 'value'.
      int setMaxNumElements​(int maxNumElements)
      Sets a new value for the maximum number of elements allowed into this tree.

      • Methods inherited from class java.util.TreeMap

        comparator, descendingKeySet, descendingMap, entrySet, headMap, headMap, keySet, navigableKeySet, replaceAll, size, subMap, subMap, tailMap, tailMap, values

      • Methods inherited from class java.util.AbstractMap

        equals, hashCode, isEmpty, toString

      • Methods inherited from class java.lang.Object

        finalize, getClass, notify, notifyAll, wait, wait, wait

      • Methods inherited from interface java.util.Map

        compute, computeIfAbsent, computeIfPresent, equals, getOrDefault, hashCode, isEmpty, merge, putIfAbsent, remove

    • Field Detail

      • serialVersionUID

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected static final long serialVersionUID
        This fulfils the SerialVersion UID requirement for all classes that implement Java's interface java.io.Serializable. Using the Serializable Implementation offered by java is very easy, and can make saving program state when debugging a lot easier. It can also be used in place of more complicated systems like "hibernate" to store data as well.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         protected static final long serialVersionUID = 1;

      • mapLRU

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected Torello.Java.Additional.LRUTreeMap.LRUTreeMaps mapLRU
        Keeps a record of the 'Ordering of Use' for the elements in 'this' map. The values stored here are set by a counter that increases with each use.

      • MAX_NUM_ELEMENTS

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected int MAX_NUM_ELEMENTS
        This is, literally, the maximum number of Key-Value pairs allowed into this instance of LRUTreeMap. When an insert or 'put' operation is made after the tree has reached this maximum size, it will remove the oldest element in the tree, first, before inserting the new addition(s)j.

    • Constructor Detail

      • LRUTreeMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public LRUTreeMap​(int maxNumElements)
        Constructs a new, empty tree map, using the natural ordering of its keys. All keys inserted into the map must implement the interface 'Comparable'. Furthermore, all such keys must be mutually comparable: k1.compareTo(k2), and must not throw a ClassCastException for any keys k1 and k2 in the map. If the user attempts to put a key into the map that violates this constraint (for example, the user attempts to put a string key into a map whose keys are integers), the put(Object key, Object value) call will throw a ClassCastException.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        Parameters:
        maxNumElements - The maximum allowable number of elements that may be inserted into 'this' tree before older elements are discarded.

      • LRUTreeMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public LRUTreeMap​(java.util.Comparator<? super K> comparator,
                  int maxNumElements)
        Constructs a new, empty tree map, ordered according to the given comparator. All keys inserted into the map must be mutually comparable by the given comparator: comparator.compare(k1, k2), must not throw a ClassCastException for any keys k1 and k2 in the map. If the user attempts to put a key into the map that violates this constraint, the put(Object key, Object value) call will throw a ClassCastException.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        Parameters:
        comparator - the java.util.Comparator that will be used to order 'this' map. If null, the natural ordering of the keys will be used.
        maxNumElements - The maximum allowable number of elements that may be inserted into 'this' tree before older elements are discarded.

      • LRUTreeMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public LRUTreeMap​(java.util.Map<? extends K,​? extends V> m,
                  int maxNumElements)
        Constructs a new tree map containing the same mappings as the given map, ordered according to the natural ordering of its keys. All keys inserted into the new map must implement the interface 'Comparable'. Furthermore, all such keys must be mutually comparable: k1.compareTo(k2) must not throw a ClassCastException for any keys k1 and k2 in the map. This method runs in n * log(n) time.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        Parameters:
        m - the map whose mappings are to be placed in 'this' map
        maxNumElements - The maximum allowable number of elements that may be inserted into 'this' tree before older elements are discarded.
        Throws:
        java.lang.ClassCastException - if the keys in m are not Comparable, or are not mutually comparable
        java.lang.NullPointerException - if the specified map is null

      • LRUTreeMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public LRUTreeMap​(java.util.SortedMap<K,​? extends V> m,
                  int maxNumElements)
        Constructs a new tree map containing the same mappings and using the same ordering as the specified sorted map. This method runs in linear time.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        Parameters:
        m - the sorted map whose mappings are to be placed in 'this' map, and whose Comparator is to be used to sort 'this' map
        maxNumElements - The maximum allowable number of elements that may be inserted into 'this' tree before older elements are discarded.
        Throws:
        java.lang.NullPointerException - if the specified map is null

    • Method Detail

      • getMaxNumElements

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int getMaxNumElements()
        This merely retrieves the value stored in MAX_NUM_ELEMENTS.
        Returns:
        The maximum number of elements allowed in this tree before it begins discarding Key-Value Pairs.
        Code:
        Exact Method Body:
         return this.MAX_NUM_ELEMENTS;

      • setMaxNumElements

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int setMaxNumElements​(int maxNumElements)
        Sets a new value for the maximum number of elements allowed into this tree. If this number is smaller than the current size of the tree, then the oldest elements will be removed until the tree has a size() smaller than the value of 'maxNumElements'
        Parameters:
        maxNumElements - This is thee new maximum allowable size for this LRUTreeMap instance.
        Returns:
        The number of elements that had to be removed from this tree in order to adhere to this new size-specifier. '0' is returned if no elements were removed.
        Throws:
        java.lang.IllegalArgumentException - The value provided to 'maxNumElements' must be at least '3', or this exception throws.
        Code:
        Exact Method Body:
         CHECK_MAX_NUM_ELEMENTS(maxNumElements);

 this.MAX_NUM_ELEMENTS = maxNumElements;

 // No elements need to be removed from the tree.
 if (this.size() <= maxNumElements) return 0;

 // Returns how many elements were removed.
 return mapLRU.trimToFit();

      • containsKey

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean containsKey​(java.lang.Object key)
        Returns TRUE if 'this' map contains a mapping for the specified 'key'.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        UPDATES: After invoking the 'super' of this overridden method, the internal LRU-Counter is updated, if necessary.
        Specified by:
        containsKey in interface java.util.Map<K,​V>
        Overrides:
        containsKey in class java.util.TreeMap<K,​V>
        Parameters:
        key - key whose presence in 'this' map is to be tested
        Returns:
        TRUE if 'this' map contains a mapping for the specified 'key'
        Throws:
        java.lang.ClassCastException - if the specified 'key' cannot be compared with the keys currently in 'this' map
        java.lang.NullPointerException - if the specified 'key' is null and 'this' map uses natural ordering, or its Comparator does not permit null keys
        Code:
        Exact Method Body:
         boolean ret = super.containsKey(key);

 // Change the time-stamp-counter for 'key' (if it was present)
 // It is now the 'Most Recently Used'

 if (ret) this.mapLRU.changed((K) key);

 return ret;

      • containsValue

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean containsValue​(java.lang.Object value)
        Returns TRUE if 'this' map maps one or more keys to the specified 'value'. More formally, returns TRUE if and only if 'this' map contains at least one mapping to a value v such that (value==null ? v==null : value.equals(v)).

        This operation will probably require time linear in the map size for most implementations.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        Specified by:
        containsValue in interface java.util.Map<K,​V>
        Overrides:
        containsValue in class java.util.TreeMap<K,​V>
        Parameters:
        value - value whose presence in 'this' map is to be tested
        Returns:
        TRUE if a mapping to value exists; FALSE otherwise
        Code:
        Exact Method Body:
         for (Map.Entry<K, V> entry : this.entrySet())
     if (value.equals(entry.getValue()))
     {
         // Change the time-stamp-counter for 'entry.key'
         // These are all now the 'Most Recently Used' keys
         //
         // NOTE: The counter-value assigned to each key is in order consistent with the
         //       the order of the entries returned by the iterator.

         this.mapLRU.changed(entry.getKey());
         return true;
     }

 return false;

      • get

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public V get​(java.lang.Object key)
        Returns the value to which the specified 'key' is mapped, or null if 'this' map contains no mapping for the 'key'. More formally, if 'this' map contains a mapping from a key k to a value v such that 'key' compares equal to k according to the map's ordering, then this method returns v; otherwise it returns null. (There can be at most one such mapping.)

        A return value of null does not necessarily indicate that the map contains no mapping for the 'key'; it's also possible that the map explicitly maps the 'key' to null. The 'containsKey' operation may be used to distinguish these two cases.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        UPDATES: After invoking the 'super' of this overridden method, the internal LRU-Counter is updated, if necessary.
        Specified by:
        get in interface java.util.Map<K,​V>
        Overrides:
        get in class java.util.TreeMap<K,​V>
        Parameters:
        key - the key whose associated value is to be returned
        Returns:
        the value to which the specified 'key' is mapped, or null if 'this' map contains no mapping for the 'key'
        Throws:
        java.lang.ClassCastException - if the specified 'key' cannot be compared with the keys currently in 'this' map
        java.lang.NullPointerException - if the specified 'key' is null and 'this' map uses natural ordering, or its Comparator does not permit null keys
        Code:
        Exact Method Body:
         V ret = super.get(key);

 // Change the time-stamp-counter for 'key' (if it was present)
 // It is now the 'Most Recently Used'

 if (ret != null) mapLRU.changed((K) key);

 return ret;

      • firstKey

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public K firstKey()
        Returns the first (lowest) key currently in 'this' map.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        UPDATES: After invoking the 'super' of this overridden method, the internal LRU-Counter is updated, if necessary.
        Specified by:
        firstKey in interface java.util.SortedMap<K,​V>
        Overrides:
        firstKey in class java.util.TreeMap<K,​V>
        Returns:
        the first (lowest) key currently in 'this' map
        Throws:
        java.util.NoSuchElementException - if 'this' map is empty
        Code:
        Exact Method Body:
         K ret = super.firstKey();

 // Change the time-stamp-counter for 'first-key' (if present) before returning it.
 // It is now the 'Most Recently Used'

 if (ret != null) mapLRU.changed(ret);

 return ret;

      • lastKey

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public K lastKey()
        Returns the last (highest) key currently in 'this' map.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        UPDATES: After invoking the 'super' of this overridden method, the internal LRU-Counter is updated, if necessary.
        Specified by:
        lastKey in interface java.util.SortedMap<K,​V>
        Overrides:
        lastKey in class java.util.TreeMap<K,​V>
        Returns:
        the last (highest) key currently in 'this' map
        Throws:
        java.util.NoSuchElementException - if 'this' map is empty
        Code:
        Exact Method Body:
         K ret = super.lastKey();

 // Change the time-stamp-counter for 'last-key' (if present) before returning it.
 // It is now the 'Most Recently Used'

 if (ret != null) mapLRU.changed(ret);

 return ret;

      • putAll

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void putAll​(java.util.Map<? extends K,​? extends V> map)
        Copies all of the mappings from the specified 'map' to 'this' map. These mappings replace any mappings that 'this' map had for any of the keys currently in the specified 'map'.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        UPDATES: After invoking the 'super' of this overridden method, the internal LRU-Counter is updated.
        Specified by:
        putAll in interface java.util.Map<K,​V>
        Overrides:
        putAll in class java.util.TreeMap<K,​V>
        Parameters:
        map - mappings to be stored in 'this' map
        Throws:
        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.NullPointerException - if the specified map is null or the specified map contains a null key and 'this' map does not permit null keys
        Code:
        Exact Method Body:
         // Throws if map.size() is greater than MAX_NUM_ELEMENTS
 CHECK_NEW_MAP_SIZE(map.size());

 super.putAll(map);

 // Add all of the entries in 'map' into the (Internal) LRU-Counter class
 for (K key : map.keySet()) this.mapLRU.added(key);

 if (this.size() > this.MAX_NUM_ELEMENTS) mapLRU.trimToFit();

      • put

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public V put​(K key,
             V value)
        Associates the specified value with the specified key in 'this' map. If the map previously contained a mapping for the 'key', the old value is replaced.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        UPDATES: After invoking the 'super' of this overridden method, the internal LRU-Counter is updated.
        Specified by:
        put in interface java.util.Map<K,​V>
        Overrides:
        put in class java.util.TreeMap<K,​V>
        Parameters:
        key - key with which the specified 'value' is to be associated
        value - value to be associated with the specified 'key'
        Returns:
        the previous value associated with 'key', or null if there was no mapping for 'key'. (A null return can also indicate that the map previously associated null with key.)
        Throws:
        java.lang.ClassCastException - if the specified 'key' cannot be compared with the keys currently in 'this' map
        java.lang.NullPointerException - if the specified 'key' is null and 'this' map uses natural ordering, or its Comparator does not permit null keys
        Code:
        Exact Method Body:
         V ret = super.put(key, value);

 // Add this 'key' into the (Internal) LRU-Counter class
 this.mapLRU.added(key);

 return ret;

      • remove

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public V remove​(java.lang.Object key)
        Removes the mapping for this 'key' from 'this' TreeMap if present.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        UPDATES: After invoking the 'super' of this overridden method, the internal LRU-Counter is updated, if necessary.
        Specified by:
        remove in interface java.util.Map<K,​V>
        Overrides:
        remove in class java.util.TreeMap<K,​V>
        Parameters:
        key - key for which mapping should be removed
        Returns:
        the previous value associated with 'key', or null if there was no mapping for 'key'. (A null return can also indicate that the map previously associated null with 'key'.)
        Throws:
        java.lang.ClassCastException - if the specified 'key' cannot be compared with the keys currently in 'this' map
        java.lang.NullPointerException - if the specified 'key' is null and 'this' map uses natural ordering, or its Comparator does not permit null keys
        Code:
        Exact Method Body:
         V ret = super.remove(key);

 // Remove this 'key' from the (Internal) LRU-Counter class, if it was present.
 if (ret != null) this.mapLRU.removed((K) key);

 return ret;

      • clear

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void clear()
        Removes all of the mappings from 'this' map. The map will be empty after this call returns.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        UPDATES: After invoking the 'super' of this overridden method, the internal LRU-Counter is updated.
        Specified by:
        clear in interface java.util.Map<K,​V>
        Overrides:
        clear in class java.util.TreeMap<K,​V>
        Code:
        Exact Method Body:
         super.clear(); this.mapLRU.clear();

      • clone

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.Object clone()
        Returns a shallow copy of this LRUTreeMap instance. (The keys and values themselves are not cloned.)

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        Overrides:
        clone in class java.util.TreeMap<K,​V>
        Returns:
        a shallow copy of 'this' map
        Code:
        Exact Method Body:
         return new LRUTreeMap<K, V>(this, this.MAX_NUM_ELEMENTS);

      • firstEntry

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Map.Entry<K,​V> firstEntry()
        Returns a key-value mapping associated with the least key in 'this' map, or null if the map is empty.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        UPDATES: After invoking the 'super' of this overridden method, the internal LRU-Counter is updated, if necessary.
        Specified by:
        firstEntry in interface java.util.NavigableMap<K,​V>
        Overrides:
        firstEntry in class java.util.TreeMap<K,​V>
        Returns:
        an entry with the least key, or null if 'this' map is empty
        Code:
        Exact Method Body:
         Map.Entry<K, V> ret = super.firstEntry();

 // Change the time-stamp-counter for 'first-key' before returning it.
 // It is now the 'Most Recently Used'
 //
 // NOTE: The (internal) mapLRU only needs to watch the 'key', not the 'key-value' pair.

 if (ret != null) this.mapLRU.changed(ret.getKey());

 return ret;

      • lastEntry

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Map.Entry<K,​V> lastEntry()
        Returns a key-value mapping associated with the greatest key in 'this' map, or null if the map is empty.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        UPDATES: After invoking the 'super' of this overridden method, the internal LRU-Counter is updated, if necessary.
        Specified by:
        lastEntry in interface java.util.NavigableMap<K,​V>
        Overrides:
        lastEntry in class java.util.TreeMap<K,​V>
        Returns:
        an entry with the greatest key, or null if 'this' map is empty
        Code:
        Exact Method Body:
         Map.Entry<K, V> ret = super.lastEntry();

 // Change the time-stamp-counter for 'last-key' before returning it.
 // It is now the 'Most Recently Used'
 //
 // NOTE: The (internal) mapLRU only needs to watch the 'key', not the 'key-value' pair.

 if (ret != null) this.mapLRU.changed(ret.getKey());

 return ret;

      • pollFirstEntry

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Map.Entry<K,​V> pollFirstEntry()
        Removes and returns a key-value mapping associated with the least key in 'this' map, or null if the map is empty.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        UPDATES: After invoking the 'super' of this overridden method, the internal LRU-Counter is updated, if necessary.
        Specified by:
        pollFirstEntry in interface java.util.NavigableMap<K,​V>
        Overrides:
        pollFirstEntry in class java.util.TreeMap<K,​V>
        Returns:
        the removed first entry of 'this' map, or null if 'this' map is empty
        Code:
        Exact Method Body:
         Map.Entry<K, V> ret = super.pollFirstEntry();

 // If there was a 'first key', it was just removed from the TreeMap
 // Make sure to remove it from the (internal) LRU-Counter class

 if (ret != null) this.mapLRU.removed(ret.getKey());

 return ret;

      • pollLastEntry

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Map.Entry<K,​V> pollLastEntry()
        Removes and returns a key-value mapping associated with the greatest key in this map, or null if the map is empty.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        UPDATES: After invoking the 'super' of this overridden method, the internal LRU-Counter is updated, if necessary.
        Specified by:
        pollLastEntry in interface java.util.NavigableMap<K,​V>
        Overrides:
        pollLastEntry in class java.util.TreeMap<K,​V>
        Returns:
        the removed last entry of 'this' map, or null if 'this' map is empty
        Code:
        Exact Method Body:
         Map.Entry<K, V> ret = super.pollLastEntry();

 // If there was a 'last key', it was just removed from the TreeMap
 // Make sure to remove it from the (internal) LRU-Counter class

 if (ret != null) this.mapLRU.removed(ret.getKey());

 return ret;

      • lowerEntry

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Map.Entry<K,​V> lowerEntry​(K key)
        Returns a key-value mapping associated with the greatest key strictly less than the given 'key', or null if there is no such key.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        UPDATES: After invoking the 'super' of this overridden method, the internal LRU-Counter is updated, if necessary.
        Specified by:
        lowerEntry in interface java.util.NavigableMap<K,​V>
        Overrides:
        lowerEntry in class java.util.TreeMap<K,​V>
        Parameters:
        key - the key
        Returns:
        an entry with the greatest key less than 'key', or null if there is no such key
        Throws:
        java.lang.ClassCastException - if the specified 'key' cannot be compared with the keys currently in the map
        java.lang.NullPointerException - if the specified 'key' is null and 'this' map uses natural ordering, or its Comparator does not permit null keys
        Code:
        Exact Method Body:
         Map.Entry<K, V> ret = super.lowerEntry(key);

 // Change the time-stamp-counter for the lower-entry 'key' (if there is one)
 // before returning it.   It is now the 'Most Recently Used'

 if (ret != null) this.mapLRU.changed(ret.getKey());

 return ret;

      • lowerKey

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public K lowerKey​(K key)
        Returns the greatest key strictly less than the given 'key', or null if there is no such key.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        UPDATES: After invoking the 'super' of this overridden method, the internal LRU-Counter is updated, if necessary.
        Specified by:
        lowerKey in interface java.util.NavigableMap<K,​V>
        Overrides:
        lowerKey in class java.util.TreeMap<K,​V>
        Parameters:
        key - the key
        Returns:
        the greatest key less than 'key', or null if there is no such key
        Throws:
        java.lang.ClassCastException - if the specified 'key' cannot be compared with the keys currently in 'this' map
        java.lang.NullPointerException - if the specified 'key' is null and 'this' map uses natural ordering, or its Comparator does not permit null keys
        Code:
        Exact Method Body:
         K ret = super.lowerKey(key);

 // Change the time-stamp-counter for the lower-key (if there is one)
 // before returning it.   It is now the 'Most Recently Used'

 if (ret != null) this.mapLRU.changed(ret);

 return ret;

      • floorEntry

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Map.Entry<K,​V> floorEntry​(K key)
        Returns a key-value mapping associated with the greatest key less than or equal to the given 'key', or null if there is no such key.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        UPDATES: After invoking the 'super' of this overridden method, the internal LRU-Counter is updated, if necessary.
        Specified by:
        floorEntry in interface java.util.NavigableMap<K,​V>
        Overrides:
        floorEntry in class java.util.TreeMap<K,​V>
        Parameters:
        key - the key
        Returns:
        an entry with the greatest key less than or equal to 'key', or null if there is no such key
        Throws:
        java.lang.ClassCastException - if the specified 'key' cannot be compared with the keys currently in 'this' map
        java.lang.NullPointerException - if the specified 'key' is null and 'this' map uses natural ordering, or its Comparator does not permit null keys
        Code:
        Exact Method Body:
         Map.Entry<K, V> ret = super.floorEntry(key);

 // Change the time-stamp-counter for the 'key' of the floor-entry (if there is one)
 // before returning it.   It is now the 'Most Recently Used'

 if (ret != null) this.mapLRU.changed(ret.getKey());

 return ret;

      • floorKey

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public K floorKey​(K key)
        Returns the greatest key less than or equal to the given 'key', or null if there is no such key.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        UPDATES: After invoking the 'super' of this overridden method, the internal LRU-Counter is updated, if necessary.
        Specified by:
        floorKey in interface java.util.NavigableMap<K,​V>
        Overrides:
        floorKey in class java.util.TreeMap<K,​V>
        Parameters:
        key - the key
        Returns:
        the greatest key less than or equal to 'key', or null if there is no such key
        Throws:
        java.lang.ClassCastException - if the specified 'key' cannot be compared with the keys currently in the map
        java.lang.NullPointerException - if the specified 'key' is null and 'this' map uses natural ordering, or its Comparator does not permit null keys
        Code:
        Exact Method Body:
         K ret = super.floorKey(key);

 // Change the time-stamp-counter for the floor-key (if there is one)
 // before returning it.   It is now the 'Most Recently Used'

 if (ret != null) this.mapLRU.changed(ret);

 return ret;

      • ceilingEntry

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Map.Entry<K,​V> ceilingEntry​(K key)
        Returns a key-value mapping associated with the least key greater than or equal to the given 'key', or null if there is no such key.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        UPDATES: After invoking the 'super' of this overridden method, the internal LRU-Counter is updated, if necessary.
        Specified by:
        ceilingEntry in interface java.util.NavigableMap<K,​V>
        Overrides:
        ceilingEntry in class java.util.TreeMap<K,​V>
        Parameters:
        key - the key
        Returns:
        an entry with the least key greater than or equal to 'key', or null if there is no such key
        Throws:
        java.lang.ClassCastException - if the specified 'key' cannot be compared with the keys currently in the map
        java.lang.NullPointerException - if the specified 'key' is null and 'this' map uses natural ordering, or its Comparator does not permit null keys
        Code:
        Exact Method Body:
         Map.Entry<K, V> ret = super.ceilingEntry(key);

 // Change the time-stamp-counter for the 'key' of the ceiling-entry (if there is one)
 // before returning it.   It is now the 'Most Recently Used'

 if (ret != null) this.mapLRU.changed(ret.getKey());

 return ret;

      • ceilingKey

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public K ceilingKey​(K key)
        Returns the least key greater than or equal to the given 'key', or null if there is no such key.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        UPDATES: After invoking the 'super' of this overridden method, the internal LRU-Counter is updated, if necessary.
        Specified by:
        ceilingKey in interface java.util.NavigableMap<K,​V>
        Overrides:
        ceilingKey in class java.util.TreeMap<K,​V>
        Parameters:
        key - the key
        Returns:
        the least key greater than or equal to 'key', or null if there is no such key
        Throws:
        java.lang.ClassCastException - if the specified 'key' cannot be compared with the keys currently in the map
        java.lang.NullPointerException - if the specified 'key' is null and 'this' map uses natural ordering, or its Comparator does not permit null keys
        Code:
        Exact Method Body:
         K ret = super.ceilingKey(key);

 // Change the time-stamp-counter for the ceiling-key (if there is one)
 // before returning it.   It is now the 'Most Recently Used'

 if (ret != null) this.mapLRU.changed(ret);

 return ret;

      • higherEntry

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Map.Entry<K,​V> higherEntry​(K key)
        Returns a key-value mapping associated with the least key strictly greater than the given 'key', or null if there is no such key.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        UPDATES: After invoking the 'super' of this overridden method, the internal LRU-Counter is updated, if necessary.
        Specified by:
        higherEntry in interface java.util.NavigableMap<K,​V>
        Overrides:
        higherEntry in class java.util.TreeMap<K,​V>
        Parameters:
        key - the key
        Returns:
        an entry with the least key greater than key, or null if there is no such key
        Throws:
        java.lang.ClassCastException - if the specified 'key' cannot be compared with the keys currently in the map
        java.lang.NullPointerException - if the specified 'key' is null and 'this' map uses natural ordering, or its Comparator does not permit null keys
        Code:
        Exact Method Body:
         Map.Entry<K, V> ret = super.higherEntry(key);

 // Change the time-stamp-counter for the 'key' of the higher-entry (if there is one)
 // before returning it.   It is now the 'Most Recently Used'

 if (ret != null) this.mapLRU.changed(ret.getKey());

 return ret;

      • higherKey

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public K higherKey​(K key)
        Returns the least key strictly greater than the given 'key', or null if there is no such key.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        UPDATES: After invoking the 'super' of this overridden method, the internal LRU-Counter is updated, if necessary.
        Specified by:
        higherKey in interface java.util.NavigableMap<K,​V>
        Overrides:
        higherKey in class java.util.TreeMap<K,​V>
        Parameters:
        key - the key
        Returns:
        the least key greater than 'key', or null if there is no such key
        Throws:
        java.lang.ClassCastException - if the specified 'key' cannot be compared with the keys currently in 'this' map
        java.lang.NullPointerException - if the specified 'key' is null and 'this' map uses natural ordering, or its Comparator does not permit null keys
        Code:
        Exact Method Body:
         K ret = super.higherKey(key);

 // Change the time-stamp-counter for the higher-key (if there is one)
 // before returning it.   It is now the 'Most Recently Used'

 if (ret != null) this.mapLRU.changed(ret);

 return ret;

      • replace

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean replace​(K key,
                       V oldValue,
                       V newValue)
        Replaces the entry for the specified 'key' only if currently mapped to the specified 'value'.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        UPDATES: After invoking the 'super' of this overridden method, the internal LRU-Counter is updated, if necessary.
        Specified by:
        replace in interface java.util.Map<K,​V>
        Overrides:
        replace in class java.util.TreeMap<K,​V>
        Parameters:
        key - key with which the specified 'value' is associated
        oldValue - value expected to be associated with the specified 'key'
        newValue - value to be associated with the specified 'key'
        Returns:
        TRUE if the value was replaced
        Code:
        Exact Method Body:
         boolean ret = super.replace(key, oldValue, newValue);

 // Change the time-stamp-counter for 'key' - if-and-only-if it was present and it mapped
 // to 'oldValue'
 // If both of these conditions were met, then it is now the 'Most Recently Used'

 if (ret) this.mapLRU.changed(key);

 return ret;

      • replace

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public V replace​(K key,
                 V value)
        Replaces the entry for the specified 'key' only if it is currently mapped to some value.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        UPDATES: After invoking the 'super' of this overridden method, the internal LRU-Counter is updated, if necessary.
        Specified by:
        replace in interface java.util.Map<K,​V>
        Overrides:
        replace in class java.util.TreeMap<K,​V>
        Parameters:
        key - key with which the specified 'value' is associated
        value - value to be associated with the specified 'key'
        Returns:
        the previous value associated with the specified 'key', or null if there was no mapping for the 'key'. (A null return can also indicate that the map previously associated null with the key, if the implementation supports null values.)
        Code:
        Exact Method Body:
         V ret = super.replace(key, value);

 // Change the time-stamp-counter for 'key' - if-and-only-if it was present and mapped
 // to any value.
 // If it was, then it is now the 'Most Recently Used'

 if (ret != null) this.mapLRU.changed(key);

 if (this.size() > this.MAX_NUM_ELEMENTS) this.mapLRU.trimToFit();

 return ret;

      • forEach

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public void forEach​
            (java.util.function.BiConsumer<? super K,​? super V> action)
        Performs the given action for each entry in 'this' map until all entries have been processed or the action throws an exception. Unless otherwise specified by the implementing class, actions are performed in the order of entry set iteration (if an iteration order is specified.) Exceptions thrown by the action are relayed to the caller.

        Description copied from class: java.util.TreeMap<K, V>, JDK 1.8
        Specified by:
        forEach in interface java.util.Map<K,​V>
        Overrides:
        forEach in class java.util.TreeMap<K,​V>
        Parameters:
        action - The action to be performed for each entry
        Code:
        Exact Method Body:
         super.forEach(action);

 // No need to touch the (internal) LRU-Counter class.  All keys are being visited
 // at the same time.

 if (this.size() > this.MAX_NUM_ELEMENTS) this.mapLRU.trimToFit();