ExpiringMap (CodelanxCommons 0.3.2-SNAPSHOT API)

java.lang.Object
- com.codelanx.commons.util.cache.ExpiringMap<K,V>

Type Parameters:

K - Key type

V - Value type

All Implemented Interfaces:

ConcurrentMap<K,V>, Map<K,V>
```
public class ExpiringMap<K,V>
extends Object
implements ConcurrentMap<K,V>
```
A thread-safe map that expires entries. Optional features include expiration policies, variable entry settings, and expiration listeners.
Entries are tracked by expiration time and expired by a single static Timer.
Expiration listeners will automatically be assigned to run in the context of the Timer thread or in a separate thread based on their first timed duration.
When variable expiration is disabled (default), put/remove operations are constant O(n). When variable expiration is enabled, put/remove operations impose an O(log n) cost.
Example usages:
```
 
 Map<String, Integer> map = ExpiringMap.create();
 Map<String, Integer> map = ExpiringMap.builder().expiration(30, TimeUnit.SECONDS).build();
 Map<String, Connection> map = ExpiringMap.builder()
   .expiration(10, TimeUnit.MINUTES)
   .entryLoader(new EntryLoader<String, Connection>() {
     public Connection load(String address) {
       return new Connection(address);
     }
   })
   .expirationListener(new ExpirationListener<String, Connection>() {
     public void expired(String key, Connection connection) {
       connection.close();
     }
   })
   .build();
 
 
```
Author:

Jonathan Halterman, 1Rogue Cleanup and updating for Java 8

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`ExpiringMap.Builder<K,V>` Builder object for an `ExpiringMap`.
`static class`	`ExpiringMap.ExpirationPolicy` Map entry expiration policy.

Nested classes/interfaces inherited from interface java.util.Map
Map.Entry<K,V>

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addExpirationHandler(BiConsumer<K,V> listener)` Adds a `BiConsumer` which will be applied to any entries upon expiry
`static <K,V> ExpiringMap.Builder<K,V>`	`builder()` Returns a new `ExpiringMap.Builder` for this `ExpiringMap`
`void`	`clear()`
`boolean`	`containsKey(Object key)`
`boolean`	`containsValue(Object value)`
`static <K,V> ExpiringMap<K,V>`	`create()` Creates a new instance of ExpiringMap with ExpirationPolicy.CREATED and expiration duration of 60 TimeUnit.SECONDS.
`Set<Map.Entry<K,V>>`	`entrySet()` Note this operation manually maps internal expiring entries upon each usage of this method.
`boolean`	`equals(Object obj)`
`V`	`get(Object key)`
`long`	`getExpiration()` Returns the map's default expiration duration in milliseconds.
`long`	`getExpiration(K key)` Gets the expiration duration in milliseconds for the entry corresponding to the given key.
`int`	`hashCode()`
`boolean`	`isEmpty()`
`Set<K>`	`keySet()`
`V`	`put(K key, V value)` Puts `value` in the map for `key`.
`V`	`put(K key, V value, ExpiringMap.ExpirationPolicy expirationPolicy)` Inserts an entry to this map with a specific `ExpiringMap.ExpirationPolicy`
`V`	`put(K key, V value, ExpiringMap.ExpirationPolicy expirationPolicy, long duration, TimeUnit timeUnit)` Puts `value` in the map for `key`.
`V`	`put(K key, V value, long duration, TimeUnit timeUnit)` Inserts an entry with a specific expiration time
`void`	`putAll(Map<? extends K,? extends V> map)` Inserts all values from another map into this one
`V`	`putIfAbsent(K key, V value)`
`V`	`remove(Object key)`
`boolean`	`remove(Object key, Object value)`
`void`	`removeExpirationHandler(BiConsumer<K,V> listener)` Removes an expiration listener.
`V`	`replace(K key, V value)`
`boolean`	`replace(K key, V oldValue, V newValue)`
`void`	`resetExpiration(K key)` Resets expiration for the entry corresponding to `key`.
`void`	`setExpiration(K key, long duration, TimeUnit timeUnit)` Sets the expiration duration for the entry corresponding to the given key.
`void`	`setExpiration(long duration, TimeUnit timeUnit)` Updates the default map entry expiration.
`void`	`setExpirationPolicy(ExpiringMap.ExpirationPolicy expirationPolicy)` Sets the global expiration policy for the map.
`void`	`setExpirationPolicy(K key, ExpiringMap.ExpirationPolicy expirationPolicy)` Sets the expiration policy for the entry corresponding to the given key.
`int`	`size()`
`String`	`toString()`
`Collection<V>`	`values()` Note this method maps internal entries into values upon each specific call.
`Iterator<V>`	`valuesIterator()` Returns an iterator over the map values.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.concurrent.ConcurrentMap
compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, replaceAll

- Method Detail
  - builder
```
public static <K,V> ExpiringMap.Builder<K,V> builder()
```
    Returns a new ExpiringMap.Builder for this ExpiringMap
    
    Type Parameters:
    
    K - The type of the keys
    
    V - The type of the values
    
    Returns:
    
    New ExpiringMap builder
    
    Since:
    
    0.1.0
  - create
```
public static <K,V> ExpiringMap<K,V> create()
```
    Creates a new instance of ExpiringMap with ExpirationPolicy.CREATED and expiration duration of 60 TimeUnit.SECONDS.
    
    Type Parameters:
    
    K - The type of the keys for this map
    
    V - The type of the values for this map
    
    Returns:
    
    A new ExpiringMap
    
    Since:
    
    0.1.0
  - addExpirationHandler
```
public void addExpirationHandler(BiConsumer<K,V> listener)
```
    Adds a BiConsumer which will be applied to any entries upon expiry
    
    Parameters:
    
    listener - The BiConsumer to apply
    
    Throws:
    
    IllegalArgumentException - If listener is null
    
    Since:
    
    0.1.0
  - clear
```
public void clear()
```
    Specified by:
    
    clear in interface Map<K,V>
  - containsKey
```
public boolean containsKey(Object key)
```
    Specified by:
    
    containsKey in interface Map<K,V>
  - containsValue
```
public boolean containsValue(Object value)
```
    Specified by:
    
    containsValue in interface Map<K,V>
  - entrySet
```
public Set<Map.Entry<K,V>> entrySet()
```
    Note this operation manually maps internal expiring entries upon each usage of this method. Look into using keySet() if possible
    
    Specified by:
    
    entrySet in interface Map<K,V>
    
    Returns:
    
    A Set of entry objects for keys and values
    
    Since:
    
    0.1.0
  - equals
```
public boolean equals(Object obj)
```
    Specified by:
    
    equals in interface Map<K,V>
    
    Overrides:
    
    equals in class Object
  - get
```
public V get(Object key)
```
    Specified by:
    
    get in interface Map<K,V>
  - getExpiration
```
public long getExpiration()
```
    Returns the map's default expiration duration in milliseconds.
    
    Returns:
    
    The expiration duration (milliseconds)
    
    Since:
    
    0.1.0
  - getExpiration
```
public long getExpiration(K key)
```
    Gets the expiration duration in milliseconds for the entry corresponding to the given key. Returns -1 if there is no mapped key
    
    Parameters:
    
    key - The key to check the expiration for
    
    Returns:
    
    The expiration duration in milliseconds
    
    Since:
    
    0.1.0
  - hashCode
```
public int hashCode()
```
    Specified by:
    
    hashCode in interface Map<K,V>
    
    Overrides:
    
    hashCode in class Object
  - isEmpty
```
public boolean isEmpty()
```
    Specified by:
    
    isEmpty in interface Map<K,V>
  - keySet
```
public Set<K> keySet()
```
    Specified by:
    
    keySet in interface Map<K,V>
  - put
```
public V put(K key,
             V value)
```
    Puts value in the map for key. Resets the entry's expiration unless an entry already exists for the same key and value.
    
    Specified by:
    
    put in interface Map<K,V>
    
    Parameters:
    
    key - to put value for
    
    value - to put for key
    
    Returns:
    
    the old value
    
    Throws:
    
    IllegalArgumentException - on null key
    
    Since:
    
    0.1.0
  - put
```
public V put(K key,
             V value,
             ExpiringMap.ExpirationPolicy expirationPolicy)
```
    Inserts an entry to this map with a specific ExpiringMap.ExpirationPolicy
    
    Parameters:
    
    key - to put value for
    
    value - to put for key
    
    expirationPolicy - The ExpiringMap.ExpirationPolicy for this entry
    
    Returns:
    
    the old value
    
    Since:
    
    0.1.0
    
    See Also:
    
    put(Object, Object, ExpirationPolicy, long, TimeUnit)
  - put
```
public V put(K key,
             V value,
             ExpiringMap.ExpirationPolicy expirationPolicy,
             long duration,
             TimeUnit timeUnit)
```
    Puts value in the map for key. Resets the entry's expiration unless an entry already exists for the same key and value. Requires that variable expiration be enabled.
    
    Parameters:
    
    key - Key to put value for
    
    value - Value to put for key
    
    expirationPolicy - The ExpiringMap.ExpirationPolicy for this entry
    
    duration - the length of time after an entry is created that it should be removed
    
    timeUnit - the unit that duration is expressed in
    
    Returns:
    
    the old value
    
    Throws:
    
    UnsupportedOperationException - If variable expiration is not enabled
    
    IllegalArgumentException - on null key or timeUnit
    
    Since:
    
    0.1.0
  - put
```
public V put(K key,
             V value,
             long duration,
             TimeUnit timeUnit)
```
    Inserts an entry with a specific expiration time
    
    Parameters:
    
    key - Key to use in mapping to a value
    
    value - Value being mapped to
    
    duration - The duration before this entry expires
    
    timeUnit - The unit of time for this duration
    
    Returns:
    
    The old value, or null if none existed or it was null
    
    Since:
    
    0.1.0
    
    See Also:
    
    put(Object, Object, ExpirationPolicy, long, TimeUnit)
  - putAll
```
public void putAll(Map<? extends K,? extends V> map)
```
    Inserts all values from another map into this one
    
    Specified by:
    
    putAll in interface Map<K,V>
    
    Parameters:
    
    map - A Map to insert into this ExpiringMap
    
    Since:
    
    0.1.0
    
    See Also:
    
    put(Object, Object)
  - putIfAbsent
```
public V putIfAbsent(K key,
                     V value)
```
    Specified by:
    
    putIfAbsent in interface ConcurrentMap<K,V>
    
    Specified by:
    
    putIfAbsent in interface Map<K,V>
  - remove
```
public V remove(Object key)
```
    Specified by:
    
    remove in interface Map<K,V>
  - remove
```
public boolean remove(Object key,
                      Object value)
```
    Specified by:
    
    remove in interface ConcurrentMap<K,V>
    
    Specified by:
    
    remove in interface Map<K,V>
  - replace
```
public V replace(K key,
                 V value)
```
    Specified by:
    
    replace in interface ConcurrentMap<K,V>
    
    Specified by:
    
    replace in interface Map<K,V>
  - replace
```
public boolean replace(K key,
                       V oldValue,
                       V newValue)
```
    Specified by:
    
    replace in interface ConcurrentMap<K,V>
    
    Specified by:
    
    replace in interface Map<K,V>
  - removeExpirationHandler
```
public void removeExpirationHandler(BiConsumer<K,V> listener)
```
    Removes an expiration listener.
    
    Parameters:
    
    listener - The BiConsumer to remove
    
    Since:
    
    0.1.0
  - resetExpiration
```
public void resetExpiration(K key)
```
    Resets expiration for the entry corresponding to key.
    
    Parameters:
    
    key - to reset expiration for
    
    Since:
    
    0.1.0
  - setExpiration
```
public void setExpiration(K key,
                          long duration,
                          TimeUnit timeUnit)
```
    Sets the expiration duration for the entry corresponding to the given key. Supported only if variable expiration is enabled.
    
    Parameters:
    
    key - Key to set expiration for
    
    duration - the length of time after an entry is created that it should be removed
    
    timeUnit - the unit that duration is expressed in
    
    Throws:
    
    UnsupportedOperationException - If variable expiration is not enabled
    
    Since:
    
    0.1.0
  - setExpiration
```
public void setExpiration(long duration,
                          TimeUnit timeUnit)
```
    Updates the default map entry expiration. Supported only if variable expiration is enabled.
    
    Parameters:
    
    duration - the length of time after an entry is created that it should be removed
    
    timeUnit - the unit that duration is expressed in
    
    Since:
    
    0.1.0
  - setExpirationPolicy
```
public void setExpirationPolicy(ExpiringMap.ExpirationPolicy expirationPolicy)
```
    Sets the global expiration policy for the map.
    
    Parameters:
    
    expirationPolicy - The new ExpiringMap.ExpirationPolicy for all entries
    
    Since:
    
    0.1.0
  - setExpirationPolicy
```
public void setExpirationPolicy(K key,
                                ExpiringMap.ExpirationPolicy expirationPolicy)
```
    Sets the expiration policy for the entry corresponding to the given key.
    
    Parameters:
    
    key - to set policy for
    
    expirationPolicy - to set
    
    Throws:
    
    UnsupportedOperationException - If variable expiration is not enabled
    
    Since:
    
    0.1.0
  - size
```
public int size()
```
    Specified by:
    
    size in interface Map<K,V>
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - values
```
public Collection<V> values()
```
    Note this method maps internal entries into values upon each specific call. Look into using valuesIterator() if possible
    
    Specified by:
    
    values in interface Map<K,V>
    
    Returns:
    
    a Collection of all values in this map
    
    Since:
    
    0.1.0
  - valuesIterator
```
public Iterator<V> valuesIterator()
```
    Returns an iterator over the map values.
    
    Returns:
    
    a Iterator of values for this map
    
    Throws:
    
    ConcurrentModificationException - if the map's size changes while iterating, excluding calls to Iterator.remove().
    
    Since:
    
    0.1.0

Class ExpiringMap<K,V>

Nested Class Summary

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

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.concurrent.ConcurrentMap

Method Detail

builder

create

addExpirationHandler

clear

containsKey

containsValue

entrySet

equals

get

getExpiration

getExpiration

hashCode

isEmpty

keySet

put

put

put

put

putAll

putIfAbsent

remove

remove

replace

replace

removeExpirationHandler

resetExpiration

setExpiration

setExpiration

setExpirationPolicy

setExpirationPolicy

size

toString

values

valuesIterator