ch.bind.philib.util

Interface TimeoutMap<K,V>

Type Parameters:

K - type parameter for the map's keys.

V - type parameter for the map's values.

All Known Implementing Classes:

SimpleTimeoutMap

public interface TimeoutMap<K,V>

A map which additionaly to normal map operations allows the user to supply a timeout. The oldest timed-out entry in the map can be found through the non-blocking pollTimeoutNow() method or two blocking methods: pollTimeoutBlocking() and pollTimeoutBlocking(long, TimeUnit).

Author:

Philipp Meinen

Method Summary

Methods

Modifier and Type	Method and Description
void	clear() removes all key-value pairs from this map.
boolean	containsKey(K key) Check for the existence of a key.
V	get(K key) Searches a value by its key
long	getTimeToNextTimeout()
boolean	isEmpty()
List<Map.Entry<K,V>>	pollAllTimeoutNow() Nonblocking poll for all timed out entries, based on the time of the invocation of this method.
Map.Entry<K,V>	pollTimeoutBlocking() Blocking poll for the next entry which is timed out.
Map.Entry<K,V>	pollTimeoutBlocking(long duration, TimeUnit timeUnit) Blocking poll for the next entry which is timed out.
Map.Entry<K,V>	pollTimeoutNow() Nonblocking poll for the next entry which is timed out, based on the time of the invocation of this method.
V	put(long timeout, K key, V value) Add a key-value pair with an associated timeout to the map.
V	remove(K key) removes an entry by it's key
int	size() query the number of entries in this map.

Method Detail

put

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

Add a key-value pair with an associated timeout to the map. The resulting timeout-timestamp is the current time plus the supplied timeout.

Parameters:

timeout - the timeout for this key-value pair (in milliseconds)

key - -

value - -

Returns:

the value which was previously associated with the given key or null if none.

get

V get(K key)

Searches a value by its key

Parameters:

key -

Returns:

null if the key does not exist.

remove

V remove(K key)

removes an entry by it's key

Parameters:

key - the key for which an entry must be removed.

Returns:

null if there was no entry for this key in that map, otherwise the value of the removed entry.

pollTimeoutNow

Map.Entry<K,V> pollTimeoutNow()

Nonblocking poll for the next entry which is timed out, based on the time of the invocation of this method.

Returns:

null if there is no timed-out entry in this map. otherwise the oldest timed-out entry.

pollAllTimeoutNow

List<Map.Entry<K,V>> pollAllTimeoutNow()

Nonblocking poll for all timed out entries, based on the time of the invocation of this method.

Returns:

Collections.EMPTY_LIST if there is are no timed out entries in this map.

pollTimeoutBlocking

Map.Entry<K,V> pollTimeoutBlocking()
                                   throws InterruptedException

Blocking poll for the next entry which is timed out.

Returns:

null if there is no timed-out entry in this map within the given duration. otherwise the oldest timed-out entry.

Throws:

InterruptedException

pollTimeoutBlocking

Map.Entry<K,V> pollTimeoutBlocking(long duration,
                                 TimeUnit timeUnit)
                                   throws InterruptedException

Blocking poll for the next entry which is timed out. The parameters duration and timeUnit define for how long the method must wait for a timeout to occur.

Returns:

null if there is no timed-out entry in this map within the given duration. otherwise the oldest timed-out entry.

Throws:

InterruptedException

clear

void clear()

removes all key-value pairs from this map.

size

int size()

query the number of entries in this map.

Returns:

the number of entries in this map.

isEmpty

boolean isEmpty()

Returns:

true if this map is empty, false otherwise.

containsKey

boolean containsKey(K key)

Check for the existence of a key.

Parameters:

key - -

Returns:

true if there is an entry identified by that key in this map, false otherwise.

getTimeToNextTimeout

long getTimeToNextTimeout()

Returns:

Long.MAX_VALUE if the TimeoutMap is empty. Otherwise the time until the next entry times out (in milliseconds since the epoch). A return value of zero indicates that there is at least one entry which has already timed out.