com.h3c.util.cache

## Class AgeOutHashMap<K,V>

- java.lang.Object
- - com.h3c.util.cache.AgeOutHashMap<K,V>

- Type Parameters:
    `K` - the key class
    `V` - the value class
  Direct Known Subclasses:
    NotedAgeOutHashMap

      public class AgeOutHashMap<K,V>
      extends Object

  Provides a map of key/value pairs that will automatically age-out when not write-accessed within a given number of milliseconds. The age-out parameter is dynamically configurable, meaning that it can be changed after creation of the map.

  Note that this design uses a "passive" age-out model, meaning that aged-out entries are only detected and removed as a side-effect of interaction with the map. For example:

       AgeOutHashMap<Foo, Bar> map = new AgeOutHashMap<Foo, Bar>(100);
       map.put(Foo.F1, Bar.B2);
       // .. wait longer than 100ms for age-out ..
       // At this point, the entry is still in the map, but is only (silently)
       // removed when we attempt to access it:
       Bar b = map.get(Foo.F1);
       assertNull(b);

  Entries in the map can be "actively" aged-out by invoking the `prune()` method.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static long` | `DEFAULT_AGE_OUT_MS` The default age-out (ms).
    `static long` | `MIN_AGE_OUT_MS` The minimum age-out (ms) allowed.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AgeOutHashMap()` Constructs a map with the initial age-out set to the default value of 5000L milliseconds.
    `AgeOutHashMap(long ageOutMs)` Constructs a map with the specified initial age-out value (ms).
    `AgeOutHashMap(long ageOutMs, boolean ageOutDeadwoodOnly)` Constructs a map with the specified initial age-out value (ms).

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `deadwood(Set<V> values)` Invoked when a set of values are silently removed from the map.
    `protected void` | `deadwood(V value)` Invoked when a value is silently removed from the map.
    `V` | `get(K key)` Returns the value in the map for the given key.
    `long` | `getAgeOutMs()` Returns the current age-out value (ms).
    `int` | `prune()` Prunes aged-out entries from the map, returning the true map size.
    `V` | `put(K key, V value)` Creates an entry in the map for the given key and value, returning the old value if there was one; null otherwise.
    `V` | `remove(K key)` Removes the entry from the map for the given key, returning its value.
    `void` | `setAgeOut(long ageOutMs)` Sets a new age-out value (ms) on the map.
    `int` | `size()` Returns the number of entries in the map.
    `String` | `toString()`
    `boolean` | `touch(K key)` Refreshes the timestamp for the map entry with the given key, if it exists.
    `boolean` | `touchOrPut(K key, V value)` Refreshes the timestamp for the map entry with the given key, if it exists, or creates a new entry.

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

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### DEFAULT_AGE_OUT_MS

          public static final long DEFAULT_AGE_OUT_MS

      The default age-out (ms).
      See Also:
        Constant Field Values

    - #### MIN_AGE_OUT_MS

          public static final long MIN_AGE_OUT_MS

      The minimum age-out (ms) allowed.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### AgeOutHashMap

          public AgeOutHashMap()

      Constructs a map with the initial age-out set to the default value of 5000L milliseconds.

    - #### AgeOutHashMap

          public AgeOutHashMap(long ageOutMs)

      Constructs a map with the specified initial age-out value (ms).
      Parameters:
        `ageOutMs` - the initial age-out value
      Throws:
        `IllegalArgumentException` - if ageOutMs is less than 10L

    - #### AgeOutHashMap

          public AgeOutHashMap(long ageOutMs,
                       boolean ageOutDeadwoodOnly)

      Constructs a map with the specified initial age-out value (ms). During a call to public `remove(Object)`, the `ageOutDeadwoodOnly` flag determines if `deadwood(Object)` is invoked.
      Parameters:
        `ageOutMs` - the initial age-out value
        `ageOutDeadwoodOnly` - the age-out deadwood only flag
      Throws:
        `IllegalArgumentException` - if ageOutMs is less than 10L

  - ### Method Detail

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### getAgeOutMs

          public long getAgeOutMs()

      Returns the current age-out value (ms).
      Returns:
        the current age-out value (ms)

    - #### setAgeOut

          public void setAgeOut(long ageOutMs)

      Sets a new age-out value (ms) on the map. Any entries in the map older than this new value are immediately pruned.
      Parameters:
        `ageOutMs` - the new age-out value (ms)

    - #### size

          public int size()

      Returns the number of entries in the map. Note that this may be an over-estimate of the true number if there are entries that have aged-out but have not yet been pruned from the map. To get an accurate count, invoke `prune()` first.
      Returns:
        the number of map entries

    - #### prune

          public int prune()

      Prunes aged-out entries from the map, returning the true map size.
      Returns:
        the map size after pruning

    - #### put

          public V put(K key,
              V value)

      Creates an entry in the map for the given key and value, returning the old value if there was one; null otherwise.
      Parameters:
        `key` - the key
        `value` - the new value
      Returns:
        the old value

    - #### touch

          public boolean touch(K key)

      Refreshes the timestamp for the map entry with the given key, if it exists. This method returns `true` to indicate that the entry exists and had its timestamp updated; `false` if there was no entry for the given key.
      Parameters:
        `key` - the key
      Returns:
        true, if the entry exists and was updated; false otherwise

    - #### touchOrPut

          public boolean touchOrPut(K key,
                           V value)

      Refreshes the timestamp for the map entry with the given key, if it exists, or creates a new entry. This method returns `true` to indicate that the entry already existed and had its timestamp updated; `false` if a new entry was created.
      Parameters:
        `key` - the key
        `value` - the value
      Returns:
        true, if the entry existed and was simply refreshed; false, if a new entry was created

    - #### get

          public V get(K key)

      Returns the value in the map for the given key. If no such entry exists in the map, null is returned.
      Parameters:
        `key` - the key
      Returns:
        the mapped value

    - #### remove

          public V remove(K key)

      Removes the entry from the map for the given key, returning its value. If no such entry exists in the map, null is returned. The `deadwood(Object)` callback will be invoked if a value was found and `ageOutDeadwoodOnly` is not set.
      Parameters:
        `key` - the key
      Returns:
        the (removed) value

    - #### deadwood

          protected void deadwood(V value)

      Invoked when a value is silently removed from the map. This default implementation does nothing.

      This method is provided so that subclasses may override it and do something interesting with the value just removed.

      Parameters:
        `value` - the value removed from the map

    - #### deadwood

          protected void deadwood(Set<V> values)

      Invoked when a set of values are silently removed from the map. This default implementation does nothing.

      This method is provided so that subclasses may override it and do something interesting with the values just removed.

      Parameters:
        `values` - the values removed from the map

Copyright © 2014. All Rights Reserved.