com.stoyanr.evictor

Interface ConcurrentMapWithTimedEviction<K,V>

Type Parameters:

K - the type of keys maintained by this map

V - the type of mapped values

All Superinterfaces:

ConcurrentMap<K,V>, Map<K,V>

All Known Implementing Classes:

ConcurrentHashMapWithTimedEviction, ConcurrentMapWithTimedEvictionDecorator

public interface ConcurrentMapWithTimedEviction<K,V>
extends ConcurrentMap<K,V>

A ConcurrentMap that supports timed entry eviction. It provides overloaded put, putIfAbsent, and replace methods with one additional parameter, evictMs, which is the time in ms during which the entry can stay in the map (time-to-live).

Author:

Stoyan Rachev

Nested Class Summary

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

Map.Entry<K,V>

Method Summary

Methods

Modifier and Type	Method and Description
V	put(K key, V value, long evictMs) Associates the specified value with the specified key in this map for the specified duration (optional operation).
V	putIfAbsent(K key, V value, long evictMs) If the specified key is not already associated with a value, associate it with the given value for the specified duration.
V	replace(K key, V value, long evictMs) Replaces the entry for a key only if currently mapped to some value, for the specified duration.
boolean	replace(K key, V oldValue, V newValue, long evictMs) Replaces the entry for a key only if currently mapped to a given value, for the specified duration.

Methods inherited from interface java.util.concurrent.ConcurrentMap

putIfAbsent, remove, replace, replace

Methods inherited from interface java.util.Map

clear, containsKey, containsValue, entrySet, equals, get, hashCode, isEmpty, keySet, put, putAll, remove, size, values

Method Detail

put

V put(K key,
    V value,
    long evictMs)

Associates the specified value with the specified key in this map for the specified duration (optional operation). If the map previously contained a mapping for the key, the old value is replaced by the specified value. (A map m is said to contain a mapping for a key k if and only if m.containsKey(k) would return true.)

Parameters:

key - key with which the specified value is to be associated

value - value to be associated with the specified key

evictMs - the time in ms during which the entry can stay in the map (time-to-live). When this time has elapsed, the entry will be evicted from the map automatically. A value of 0 for this argument means "forever", i.e. put(key, value, 0) is equivalent to put(key, value).

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, if the implementation supports null values.)

Throws:

UnsupportedOperationException - if the put operation is not supported by this map

ClassCastException - if the class of the specified key or value prevents it from being stored in this map

NullPointerException - if the specified key or value is null and this map does not permit null keys or values

IllegalArgumentException - if some property of the specified key or value prevents it from being stored in this map, or if evictMs is negative

putIfAbsent

V putIfAbsent(K key,
            V value,
            long evictMs)

If the specified key is not already associated with a value, associate it with the given value for the specified duration. This is equivalent to

 if (!map.containsKey(key))
     return map.put(key, value, evictMs);
 else
     return map.get(key);
 

except that the action is performed atomically.

Parameters:

key - key with which the specified value is to be associated

value - value to be associated with the specified key

evictMs - the time in ms during which the entry can stay in the map (time-to-live). When this time has elapsed, the entry will be evicted from the map automatically. A value of 0 for this argument means "forever", i.e. putIfAbsent(key, value, 0) is equivalent to putIfAbsent(key, value).

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

Throws:

UnsupportedOperationException - if the put operation is not supported by this map

ClassCastException - if the class of the specified key or value prevents it from being stored in this map

NullPointerException - if the specified key or value is null, and this map does not permit null keys or values

IllegalArgumentException - if some property of the specified key or value prevents it from being stored in this map, or if evictMs is negative

replace

V replace(K key,
        V value,
        long evictMs)

Replaces the entry for a key only if currently mapped to some value, for the specified duration. This is equivalent to

 if (map.containsKey(key)) {
     return map.put(key, value, evictMs);
 } else
     return null;
 

except that the action is performed atomically.

Parameters:

key - key with which the specified value is associated

value - value to be associated with the specified key

evictMs - the time in ms during which the entry can stay in the map (time-to-live). When this time has elapsed, the entry will be evicted from the map automatically. A value of 0 for this argument means "forever", i.e. replace(key, value, 0) is equivalent to replace(key, value).

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

Throws:

UnsupportedOperationException - if the put operation is not supported by this map

ClassCastException - if the class of the specified key or value prevents it from being stored in this map

NullPointerException - if the specified key or value is null, and this map does not permit null keys or values

IllegalArgumentException - if some property of the specified key or value prevents it from being stored in this map, or if evictMs is negative

replace

boolean replace(K key,
              V oldValue,
              V newValue,
              long evictMs)

Replaces the entry for a key only if currently mapped to a given value, for the specified duration. This is equivalent to

 if (map.containsKey(key) && map.get(key).equals(oldValue)) {
     map.put(key, newValue, evictMs);
     return true;
 } else
     return false;
 

except that the action is performed atomically.

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

evictMs - the time in ms during which the entry can stay in the map (time-to-live). When this time has elapsed, the entry will be evicted from the map automatically. A value of 0 for this argument means "forever", i.e. replace(key, oldValue, newValue, 0) is equivalent to put(key, oldValue, newValue).

Returns:

true if the value was replaced

Throws:

UnsupportedOperationException - if the put operation is not supported by this map

ClassCastException - if the class of a specified key or value prevents it from being stored in this map

NullPointerException - if a specified key or value is null, and this map does not permit null keys or values

IllegalArgumentException - if some property of a specified key or value prevents it from being stored in this map, or if evictMs is negative