com.twelvemonkeys.util

Class TimeoutMap<K,V>

java.lang.Object

java.util.AbstractMap<K,V>

com.twelvemonkeys.util.TimeoutMap<K,V>

All Implemented Interfaces:

ExpiringMap<K,V>, java.io.Serializable, java.lang.Cloneable, java.util.Map<K,V>

public class TimeoutMap<K,V>
extends java.util.AbstractMap<K,V>
implements ExpiringMap<K,V>, java.io.Serializable, java.lang.Cloneable

A Map implementation that removes (exipres) its elements after a given period. The map is by default backed by a HashMap, or can be instantiated with any given Map as backing.

Notes to consider when using this map:

• Elements may not expire on the exact millisecond as expected.
• The value returned by the size() method of the map, or any of its collection views, may not represent the exact number of entries in the map at any given time.
• Elements in this map may expire at any time (but never between invocations of Iterator.hasNext() and Iterator.next() or Iterator.remove(), when iterating the collection views).

Version:

$Id: //depot/branches/personal/haraldk/twelvemonkeys/release-2/twelvemonkeys-core/src/main/java/com/twelvemonkeys/util/TimeoutMap.java#2 $

Author:

Harald Kuhr

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class java.util.AbstractMap

java.util.AbstractMap.SimpleEntry<K,V>, java.util.AbstractMap.SimpleImmutableEntry<K,V>

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

java.util.Map.Entry<K,V>

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.Map<K,java.util.Map.Entry<K,V>>	entries
protected long	expiryTime Expiry time
protected int	modCount

Constructor Summary

Constructors

Constructor and Description
TimeoutMap() Creates a TimeoutMap with the default expiry time of 1 minute.
TimeoutMap(long pExpiryTime) Creates a TimeoutMap with the given expiry time (milliseconds).
TimeoutMap(java.util.Map<? extends K,? extends V> pContents) Creates a TimeoutMap containing the same elements as the given map with the default expiry time of 1 minute.
TimeoutMap(java.util.Map<K,java.util.Map.Entry<K,V>> pBacking, java.util.Map<? extends K,? extends V> pContents, long pExpiryTime) Creates a TimeoutMap with the given expiry time (milliseconds).

Method Summary

Methods

Modifier and Type	Method and Description
void	clear() Removes all mappings from this map.
protected java.lang.Object	clone() Returns a shallow copy of this AbstractMap instance: the keys and values themselves are not cloned.
boolean	containsKey(java.lang.Object pKey) Returns true if this map contains a mapping for the specified pKey.
boolean	containsValue(java.lang.Object pValue) Returns true if this map maps one or more keys to the specified pValue.
java.util.Set<java.util.Map.Entry<K,V>>	entrySet()
V	get(java.lang.Object pKey) Returns the value to which this map maps the specified pKey.
long	getExpiryTime() Gets the maximum time any value will be kept in the map, before it expires.
protected void	init() Default implementation, does nothing.
boolean	isEmpty() Returns true if this map contains no key-value mappings.
java.util.Set<K>	keySet()
protected java.util.Iterator<java.util.Map.Entry<K,V>>	newEntryIterator()
protected java.util.Iterator<K>	newKeyIterator()
protected java.util.Iterator<V>	newValueIterator()
void	processRemoved(java.util.Map.Entry pRemoved) May be used by clients as a call-back to notify when mappings expire from the map.
V	put(K pKey, V pValue) Associates the specified pValue with the specified pKey in this map (optional operation).
V	remove(java.lang.Object pKey) Removes the mapping for this pKey from this map if present (optional operation).
protected java.util.Map.Entry<K,V>	removeEntry(java.util.Map.Entry<K,V> pEntry) Removes the given entry from the Map.
protected void	removeExpiredEntries() Removes any expired mappings.
void	setExpiryTime(long pExpiryTime) Sets the maximum time any value will be kept in the map, before it expires.
int	size() Returns the number of key-value mappings in this map.
java.util.Collection<V>	values()

Methods inherited from class java.util.AbstractMap

equals, hashCode, putAll, toString

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map

containsValue, equals, hashCode, putAll

Field Detail

expiryTime

protected long expiryTime

Expiry time

entries

protected java.util.Map<K,java.util.Map.Entry<K,V>> entries

modCount

protected transient volatile int modCount

Constructor Detail

TimeoutMap

public TimeoutMap()

Creates a TimeoutMap with the default expiry time of 1 minute. This TimeoutMap will be backed by a new HashMap instance.

This is constructor is here to comply with the reccomendations for "standard" constructors in the Map interface.

See Also:

TimeoutMap(long)

TimeoutMap

public TimeoutMap(java.util.Map<? extends K,? extends V> pContents)

Creates a TimeoutMap containing the same elements as the given map with the default expiry time of 1 minute. This TimeoutMap will be backed by a new HashMap instance, and not the map passed in as a paramter.

This is constructor is here to comply with the reccomendations for "standard" constructors in the Map interface.

Parameters:

pContents - the map whose mappings are to be placed in this map. May be null.

See Also:

TimeoutMap(java.util.Map, Map, long), Map

TimeoutMap

public TimeoutMap(long pExpiryTime)

Creates a TimeoutMap with the given expiry time (milliseconds). This TimeoutMap will be backed by a new HashMap instance.

Parameters:

pExpiryTime - the expiry time (time to live) for elements in this map

TimeoutMap

public TimeoutMap(java.util.Map<K,java.util.Map.Entry<K,V>> pBacking,
          java.util.Map<? extends K,? extends V> pContents,
          long pExpiryTime)

Creates a TimeoutMap with the given expiry time (milliseconds). This TimeoutMap will be backed by the given Map.

Note that structurally modifying the backing map directly (not through this map or its collection views), is not allowed, and will produce undeterministic exceptions.

Parameters:

pBacking - the map that will be used as backing.

pContents - the map whose mappings are to be placed in this map. May be null.

pExpiryTime - the expiry time (time to live) for elements in this map

Method Detail

getExpiryTime

public long getExpiryTime()

Gets the maximum time any value will be kept in the map, before it expires.

Returns:

the expiry time

setExpiryTime

public void setExpiryTime(long pExpiryTime)

Sets the maximum time any value will be kept in the map, before it expires. Removes any items that are older than the specified time.

Parameters:

pExpiryTime - the expiry time (time to live) for elements in this map

size

public int size()

Returns the number of key-value mappings in this map. If the map contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Specified by:

size in interface java.util.Map<K,V>

Returns:

the number of key-value mappings in this map.

isEmpty

public boolean isEmpty()

Returns true if this map contains no key-value mappings.

Specified by:

isEmpty in interface java.util.Map<K,V>

Returns:

true if this map contains no key-value mappings.

containsKey

public boolean containsKey(java.lang.Object pKey)

Returns true if this map contains a mapping for the specified pKey.

Specified by:

containsKey in interface java.util.Map<K,V>

Parameters:

pKey - pKey whose presence in this map is to be tested.

Returns:

true if this map contains a mapping for the specified pKey.

get

public V get(java.lang.Object pKey)

Returns the value to which this map maps the specified pKey. Returns null if the map contains no mapping for this pKey. A return value of null does not necessarily indicate that the map contains no mapping for the pKey; it's also possible that the map explicitly maps the pKey to null. The containsKey operation may be used to distinguish these two cases.

Specified by:

get in interface java.util.Map<K,V>

Parameters:

pKey - pKey whose associated value is to be returned.

Returns:

the value to which this map maps the specified pKey, or null if the map contains no mapping for this pKey.

See Also:

containsKey(java.lang.Object)

put

public V put(K pKey,
    V pValue)

Associates the specified pValue with the specified pKey in this map (optional operation). If the map previously contained a mapping for this pKey, the old pValue is replaced.

Specified by:

put in interface java.util.Map<K,V>

Parameters:

pKey - pKey with which the specified pValue is to be associated.

pValue - pValue to be associated with the specified pKey.

Returns:

previous pValue associated with specified pKey, or null if there was no mapping for pKey. A null return can also indicate that the map previously associated null with the specified pKey, if the implementation supports null values.

remove

public V remove(java.lang.Object pKey)

Removes the mapping for this pKey from this map if present (optional operation).

Specified by:

remove in interface java.util.Map<K,V>

Parameters:

pKey - pKey whose mapping is to be removed from the map.

Returns:

previous value associated with specified pKey, or null if there was no mapping for pKey. A null return can also indicate that the map previously associated null with the specified pKey, if the implementation supports null values.

clear

public void clear()

Removes all mappings from this map.

Specified by:

clear in interface java.util.Map<K,V>

removeExpiredEntries

protected void removeExpiredEntries()

Removes any expired mappings.

values

public java.util.Collection<V> values()

Specified by:

values in interface java.util.Map<K,V>

entrySet

public java.util.Set<java.util.Map.Entry<K,V>> entrySet()

Specified by:

entrySet in interface java.util.Map<K,V>

keySet

public java.util.Set<K> keySet()

Specified by:

keySet in interface java.util.Map<K,V>

newKeyIterator

protected java.util.Iterator<K> newKeyIterator()

newValueIterator

protected java.util.Iterator<V> newValueIterator()

newEntryIterator

protected java.util.Iterator<java.util.Map.Entry<K,V>> newEntryIterator()

processRemoved

public void processRemoved(java.util.Map.Entry pRemoved)

Description copied from interface: ExpiringMap

May be used by clients as a call-back to notify when mappings expire from the map.

Specified by:

processRemoved in interface ExpiringMap<K,V>

Parameters:

pRemoved - the removed mapping

init

protected void init()

Default implementation, does nothing.

containsValue

public boolean containsValue(java.lang.Object pValue)

Returns true if this map maps one or more keys to the specified pValue. More formally, returns true if and only if this map contains at least one mapping to a pValue v such that (pValue==null ? v==null : pValue.equals(v)).

This implementation requires time linear in the map size for this operation.

Specified by:

containsValue in interface java.util.Map<K,V>

Overrides:

containsValue in class java.util.AbstractMap<K,V>

Parameters:

pValue - pValue whose presence in this map is to be tested.

Returns:

true if this map maps one or more keys to the specified pValue.

clone

protected java.lang.Object clone()
                          throws java.lang.CloneNotSupportedException

Returns a shallow copy of this AbstractMap instance: the keys and values themselves are not cloned.

Overrides:

clone in class java.util.AbstractMap<K,V>

Returns:

a shallow copy of this map.

Throws:

java.lang.CloneNotSupportedException

removeEntry

protected java.util.Map.Entry<K,V> removeEntry(java.util.Map.Entry<K,V> pEntry)

Removes the given entry from the Map.

Parameters:

pEntry - the entry to be removed

Returns:

the removed entry, or null if nothing was removed.