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 two TimeoutMap#findTimedout methods.

Author:

Philipp Meinen

Method Summary

void	add(long timeous, K key, V value) Add a key-value pair with an associated timeout to the map.
void	addWithTimestamp(long timestamp, K key, V value) Add a key-value pair with a specific timeout timestamp.
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()
Map.Entry<K,V>	pollTimeout() finds the next entry which is timed out, based on the time of the invocation of this method.
V	remove(K key) removes an entry by it's key
int	size() query the number of entries in this map.

Method Detail

add

void add(long timeous,
         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)

timeUnit - the unit of the parameter timeout

key - -

value - -

addWithTimestamp

void addWithTimestamp(long timestamp,
                      K key,
                      V value)

Add a key-value pair with a specific timeout timestamp.

Parameters:

timestamp - the timestamp when this key-value pair will expire (in milliseconds since the epoch).

timeUnit - the unit of the parameter timestamp

key - -

value - -

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.

pollTimeout

Map.Entry<K,V> pollTimeout()

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

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

Parameters:

timeUnit - the unit of the returned value.

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.