AgeOutHashMap (sdn-apidoc 2.0.0 API)

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.

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

Class AgeOutHashMap<K,V>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_AGE_OUT_MS

MIN_AGE_OUT_MS

Constructor Detail

AgeOutHashMap

AgeOutHashMap

AgeOutHashMap

Method Detail

toString

getAgeOutMs

setAgeOut

size

prune

put

touch

touchOrPut

get

remove

deadwood

deadwood