Package com.twelvemonkeys.util

Class 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 AbstractDecoratedMap<K,​V>
implements ExpiringMap<K,​V>, java.io.Serializable, java.lang.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 $
    See Also:
    Serialized Form

    • Constructor Summary

      Constructors 
      Constructor 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

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void clear()
      Removes all mappings from this map.
      boolean containsKey​(java.lang.Object pKey)
      Returns true if this map contains a mapping for the specified pKey.
      (package private) TimeoutMap.TimedEntry createEntry​(K pKey, V 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.
      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 void removeExpiredEntries()
      Removes any expired mappings.
      private void removeExpiredEntriesSynced​(long pTime)
      Okay, I guess this do resemble DCL...
      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

        compute, computeIfAbsent, computeIfPresent, containsValue, equals, forEach, getOrDefault, hashCode, merge, putAll, putIfAbsent, remove, replace, replace, replaceAll

    • Field Detail

      • expiryTime

        protected long expiryTime
        Expiry time

      • nextExpiryTime

        private volatile long nextExpiryTime

    • 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 recommendations 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 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(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>
        Overrides:
        size in class AbstractDecoratedMap<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>
        Overrides:
        isEmpty in class AbstractDecoratedMap<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>
        Overrides:
        containsKey in class AbstractDecoratedMap<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>
        Specified by:
        get in class AbstractDecoratedMap<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>
        Specified by:
        put in class AbstractDecoratedMap<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>
        Specified by:
        remove in class AbstractDecoratedMap<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>
        Overrides:
        clear in class AbstractDecoratedMap<K,​V>

      • removeExpiredEntries

        protected void removeExpiredEntries()
        Removes any expired mappings.

      • removeExpiredEntriesSynced

        private void removeExpiredEntriesSynced​(long pTime)
        Okay, I guess this do resemble DCL...
        Parameters:
        pTime - now

      • values

        public java.util.Collection<V> values()
        Specified by:
        values in interface java.util.Map<K,​V>
        Overrides:
        values in class AbstractDecoratedMap<K,​V>

      • entrySet

        public java.util.Set<java.util.Map.Entry<K,​V>> entrySet()
        Specified by:
        entrySet in interface java.util.Map<K,​V>
        Overrides:
        entrySet in class AbstractDecoratedMap<K,​V>

      • keySet

        public java.util.Set<K> keySet()
        Specified by:
        keySet in interface java.util.Map<K,​V>
        Overrides:
        keySet in class AbstractDecoratedMap<K,​V>

      • 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