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 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 extends java.lang.Object,​V extends java.lang.Object>, java.util.AbstractMap.SimpleImmutableEntry<K extends java.lang.Object,​V extends java.lang.Object>
      • Nested classes/interfaces inherited from interface java.util.Map

        java.util.Map.Entry<K extends java.lang.Object,​V extends java.lang.Object>
    • Field Summary

      Fields 
      Modifier and Type Field 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 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.
      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

        compute, computeIfAbsent, computeIfPresent, containsValue, equals, forEach, getOrDefault, hashCode, merge, putAll, putIfAbsent, remove, replace, replace, replaceAll
    • 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 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>
        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.