Class TimeoutMap<K,V>

java.lang.Object
java.util.AbstractMap<K,V>
com.twelvemonkeys.util.TimeoutMap<K,V>
All Implemented Interfaces:
ExpiringMap<K,V>, Serializable, Cloneable, Map<K,V>

public class TimeoutMap<K,V> extends AbstractMap<K,V> implements ExpiringMap<K,V>, Serializable, Cloneable
A Map implementation that removes (expires) 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:
  • Field Details

    • expiryTime

      protected long expiryTime
      Expiry time
    • entries

      protected Map<K,Map.Entry<K,V>> entries
    • modCount

      protected transient volatile int modCount
  • Constructor Details

    • 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 recommendations for "standard" constructors in the Map interface.

      See Also:
    • TimeoutMap

      public TimeoutMap(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 recommendations 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

      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(Map<K,Map.Entry<K,V>> pBacking, 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 Details

    • 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 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 Map<K,V>
      Returns:
      true if this map contains no key-value mappings.
    • containsKey

      public boolean containsKey(Object pKey)
      Returns true if this map contains a mapping for the specified pKey.
      Specified by:
      containsKey in interface 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(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 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:
    • 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 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(Object pKey)
      Removes the mapping for this pKey from this map if present (optional operation).
      Specified by:
      remove in interface 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 Map<K,V>
    • removeExpiredEntries

      protected void removeExpiredEntries()
      Removes any expired mappings.
    • values

      public Collection<V> values()
      Specified by:
      values in interface Map<K,V>
    • entrySet

      public Set<Map.Entry<K,V>> entrySet()
      Specified by:
      entrySet in interface Map<K,V>
    • keySet

      public Set<K> keySet()
      Specified by:
      keySet in interface Map<K,V>
    • newKeyIterator

      protected Iterator<K> newKeyIterator()
    • newValueIterator

      protected Iterator<V> newValueIterator()
    • newEntryIterator

      protected Iterator<Map.Entry<K,V>> newEntryIterator()
    • processRemoved

      public void processRemoved(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(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 Map<K,V>
      Overrides:
      containsValue in class 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 Object clone() throws CloneNotSupportedException
      Returns a shallow copy of this AbstractMap instance: the keys and values themselves are not cloned.
      Overrides:
      clone in class AbstractMap<K,V>
      Returns:
      a shallow copy of this map.
      Throws:
      CloneNotSupportedException
    • removeEntry

      protected Map.Entry<K,V> removeEntry(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.