org.apache.commons.collections4.map

## Class PassiveExpiringMap<K,V>

- java.lang.Object
- - org.apache.commons.collections4.map.AbstractIterableMap<K,V>
  - - org.apache.commons.collections4.map.AbstractMapDecorator<K,V>
    - - org.apache.commons.collections4.map.PassiveExpiringMap<K,V>

- Type Parameters:
    `K` - the type of the keys in this map
    `V` - the type of the values in this map
  All Implemented Interfaces:
    Serializable, Map<K,V>, Get<K,V>, IterableGet<K,V>, IterableMap<K,V>, Put<K,V>

      public class PassiveExpiringMap<K,V>
      extends AbstractMapDecorator<K,V>
      implements Serializable

  Decorates a `Map` to evict expired entries once their expiration time has been reached.

  When putting a key-value pair in the map this decorator uses a `PassiveExpiringMap.ExpirationPolicy` to determine how long the entry should remain alive as defined by an expiration time value.

  When accessing the mapped value for a key, its expiration time is checked, and if it is a negative value or if it is greater than the current time, the mapped value is returned. Otherwise, the key is removed from the decorated map, and `null` is returned.

  When invoking methods that involve accessing the entire map contents (i.e `containsKey(Object)`, `entrySet()`, etc.) this decorator removes all expired entries prior to actually completing the invocation.

  Note that `PassiveExpiringMap` is not synchronized and is not thread-safe. If you wish to use this map from multiple threads concurrently, you must use appropriate synchronization. The simplest approach is to wrap this map using `Collections.synchronizedMap(Map)`. This class may throw exceptions when accessed by concurrent threads without synchronization.

  Since:
    4.0
  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `PassiveExpiringMap.ConstantTimeToLiveExpirationPolicy<K,V>` A `ExpirationPolicy` that returns a expiration time that is a constant about of time in the future from the current time.
    `static interface` | `PassiveExpiringMap.ExpirationPolicy<K,V>` A policy to determine the expiration time for key-value entries.

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

      `Map.Entry<K,V>`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PassiveExpiringMap()` Default constructor.
    `PassiveExpiringMap(long timeToLiveMillis)` Construct a map decorator that decorates the given map using the given time-to-live value measured in milliseconds to create and use a `PassiveExpiringMap.ConstantTimeToLiveExpirationPolicy` expiration policy.
    `PassiveExpiringMap(long timeToLiveMillis, Map<K,V> map)` Construct a map decorator using the given time-to-live value measured in milliseconds to create and use a `PassiveExpiringMap.ConstantTimeToLiveExpirationPolicy` expiration policy.
    `PassiveExpiringMap(long timeToLive, TimeUnit timeUnit)` Construct a map decorator using the given time-to-live value measured in the given time units of measure to create and use a `PassiveExpiringMap.ConstantTimeToLiveExpirationPolicy` expiration policy.
    `PassiveExpiringMap(long timeToLive, TimeUnit timeUnit, Map<K,V> map)` Construct a map decorator that decorates the given map using the given time-to-live value measured in the given time units of measure to create `PassiveExpiringMap.ConstantTimeToLiveExpirationPolicy` expiration policy.
    `PassiveExpiringMap(Map<K,V> map)` Constructs a map decorator that decorates the given map and results in entries NEVER expiring.
    `PassiveExpiringMap(PassiveExpiringMap.ExpirationPolicy<K,V> expiringPolicy)` Construct a map decorator using the given expiration policy to determine expiration times.
    `PassiveExpiringMap(PassiveExpiringMap.ExpirationPolicy<K,V> expiringPolicy, Map<K,V> map)` Construct a map decorator that decorates the given map and uses the given expiration policy to determine expiration times.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clear()` Normal `Map.clear()` behavior with the addition of clearing all expiration entries as well.
    `boolean` | `containsKey(Object key)` All expired entries are removed from the map prior to determining the contains result.
    `boolean` | `containsValue(Object value)` All expired entries are removed from the map prior to determining the contains result.
    `Set<Map.Entry<K,V>>` | `entrySet()` All expired entries are removed from the map prior to returning the entry set.
    `V` | `get(Object key)` All expired entries are removed from the map prior to returning the entry value.
    `boolean` | `isEmpty()` All expired entries are removed from the map prior to determining if it is empty.
    `Set<K>` | `keySet()` All expired entries are removed from the map prior to returning the key set.
    `V` | `put(K key, V value)` Add the given key-value pair to this map as well as recording the entry's expiration time based on the current time in milliseconds and this map's `expiringPolicy`.
    `void` | `putAll(Map<? extends K,? extends V> mapToCopy)`
    `V` | `remove(Object key)` Normal `Map.remove(Object)` behavior with the addition of removing any expiration entry as well.
    `int` | `size()` All expired entries are removed from the map prior to returning the size.
    `Collection<V>` | `values()` All expired entries are removed from the map prior to returning the value collection.

    - ### Methods inherited from class org.apache.commons.collections4.map.AbstractMapDecorator

      `decorated, equals, hashCode, toString`

    - ### Methods inherited from class org.apache.commons.collections4.map.AbstractIterableMap

      `mapIterator`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface java.util.Map

      `compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll`

- - ### Constructor Detail

    - #### PassiveExpiringMap

          public PassiveExpiringMap()

      Default constructor. Constructs a map decorator that results in entries NEVER expiring.

    - #### PassiveExpiringMap

          public PassiveExpiringMap(PassiveExpiringMap.ExpirationPolicy<K,V> expiringPolicy)

      Construct a map decorator using the given expiration policy to determine expiration times.
      Parameters:
        `expiringPolicy` - the policy used to determine expiration times of entries as they are added.
      Throws:
        `NullPointerException` - if expiringPolicy is null

    - #### PassiveExpiringMap

          public PassiveExpiringMap(PassiveExpiringMap.ExpirationPolicy<K,V> expiringPolicy,
                                    Map<K,V> map)

      Construct a map decorator that decorates the given map and uses the given expiration policy to determine expiration times. If there are any elements already in the map being decorated, they will NEVER expire unless they are replaced.
      Parameters:
        `expiringPolicy` - the policy used to determine expiration times of entries as they are added.
        `map` - the map to decorate, must not be null.
      Throws:
        `NullPointerException` - if the map or expiringPolicy is null.

    - #### PassiveExpiringMap

          public PassiveExpiringMap(long timeToLiveMillis)

      Construct a map decorator that decorates the given map using the given time-to-live value measured in milliseconds to create and use a `PassiveExpiringMap.ConstantTimeToLiveExpirationPolicy` expiration policy.
      Parameters:
        `timeToLiveMillis` - the constant amount of time (in milliseconds) an entry is available before it expires. A negative value results in entries that NEVER expire. A zero value results in entries that ALWAYS expire.

    - #### PassiveExpiringMap

          public PassiveExpiringMap(long timeToLiveMillis,
                                    Map<K,V> map)

      Construct a map decorator using the given time-to-live value measured in milliseconds to create and use a `PassiveExpiringMap.ConstantTimeToLiveExpirationPolicy` expiration policy. If there are any elements already in the map being decorated, they will NEVER expire unless they are replaced.
      Parameters:
        `timeToLiveMillis` - the constant amount of time (in milliseconds) an entry is available before it expires. A negative value results in entries that NEVER expire. A zero value results in entries that ALWAYS expire.
        `map` - the map to decorate, must not be null.
      Throws:
        `NullPointerException` - if the map is null.

    - #### PassiveExpiringMap

          public PassiveExpiringMap(long timeToLive,
                                    TimeUnit timeUnit)

      Construct a map decorator using the given time-to-live value measured in the given time units of measure to create and use a `PassiveExpiringMap.ConstantTimeToLiveExpirationPolicy` expiration policy.
      Parameters:
        `timeToLive` - the constant amount of time an entry is available before it expires. A negative value results in entries that NEVER expire. A zero value results in entries that ALWAYS expire.
        `timeUnit` - the unit of time for the `timeToLive` parameter, must not be null.
      Throws:
        `NullPointerException` - if the time unit is null.

    - #### PassiveExpiringMap

          public PassiveExpiringMap(long timeToLive,
                                    TimeUnit timeUnit,
                                    Map<K,V> map)

      Construct a map decorator that decorates the given map using the given time-to-live value measured in the given time units of measure to create `PassiveExpiringMap.ConstantTimeToLiveExpirationPolicy` expiration policy. This policy is used to determine expiration times. If there are any elements already in the map being decorated, they will NEVER expire unless they are replaced.
      Parameters:
        `timeToLive` - the constant amount of time an entry is available before it expires. A negative value results in entries that NEVER expire. A zero value results in entries that ALWAYS expire.
        `timeUnit` - the unit of time for the `timeToLive` parameter, must not be null.
        `map` - the map to decorate, must not be null.
      Throws:
        `NullPointerException` - if the map or time unit is null.

    - #### PassiveExpiringMap

          public PassiveExpiringMap(Map<K,V> map)

      Constructs a map decorator that decorates the given map and results in entries NEVER expiring. If there are any elements already in the map being decorated, they also will NEVER expire.
      Parameters:
        `map` - the map to decorate, must not be null.
      Throws:
        `NullPointerException` - if the map is null.

  - ### Method Detail

    - #### clear

          public void clear()

      Normal `Map.clear()` behavior with the addition of clearing all expiration entries as well.
      Specified by:
        `clear` in interface `Map<K,V>`
      Specified by:
        `clear` in interface `Put<K,V>`
      Overrides:
        `clear` in class `AbstractMapDecorator<K,V>`
      See Also:
        `Map.clear()`

    - #### containsKey

          public boolean containsKey(Object key)

      All expired entries are removed from the map prior to determining the contains result.
      Specified by:
        `containsKey` in interface `Map<K,V>`
      Specified by:
        `containsKey` in interface `Get<K,V>`
      Overrides:
        `containsKey` in class `AbstractMapDecorator<K,V>`
      Parameters:
        `key` - key whose presence in this map is to be tested
      Returns:
        `true` if this map contains a mapping for the specified key
      See Also:
        `Map.containsKey(Object)`

    - #### containsValue

          public boolean containsValue(Object value)

      All expired entries are removed from the map prior to determining the contains result.
      Specified by:
        `containsValue` in interface `Map<K,V>`
      Specified by:
        `containsValue` in interface `Get<K,V>`
      Overrides:
        `containsValue` in class `AbstractMapDecorator<K,V>`
      Parameters:
        `value` - value whose presence in this map is to be tested
      Returns:
        `true` if this map maps one or more keys to the specified value
      See Also:
        `Map.containsValue(Object)`

    - #### entrySet

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

      All expired entries are removed from the map prior to returning the entry set.
      Specified by:
        `entrySet` in interface `Map<K,V>`
      Specified by:
        `entrySet` in interface `Get<K,V>`
      Overrides:
        `entrySet` in class `AbstractMapDecorator<K,V>`
      Returns:
        a set view of the mappings contained in this map
      See Also:
        `Map.entrySet()`

    - #### get

          public V get(Object key)

      All expired entries are removed from the map prior to returning the entry value.
      Specified by:
        `get` in interface `Map<K,V>`
      Specified by:
        `get` in interface `Get<K,V>`
      Overrides:
        `get` in class `AbstractMapDecorator<K,V>`
      Parameters:
        `key` - the key whose associated value is to be returned
      Returns:
        the value to which the specified key is mapped, or `null` if this map contains no mapping for the key
      See Also:
        `Map.get(Object)`

    - #### isEmpty

          public boolean isEmpty()

      All expired entries are removed from the map prior to determining if it is empty.
      Specified by:
        `isEmpty` in interface `Map<K,V>`
      Specified by:
        `isEmpty` in interface `Get<K,V>`
      Overrides:
        `isEmpty` in class `AbstractMapDecorator<K,V>`
      Returns:
        `true` if this map contains no key-value mappings
      See Also:
        `Map.isEmpty()`

    - #### keySet

          public Set<K> keySet()

      All expired entries are removed from the map prior to returning the key set.
      Specified by:
        `keySet` in interface `Map<K,V>`
      Specified by:
        `keySet` in interface `Get<K,V>`
      Overrides:
        `keySet` in class `AbstractMapDecorator<K,V>`
      Returns:
        a set view of the keys contained in this map
      See Also:
        `Map.keySet()`

    - #### put

          public V put(K key,
                       V value)

      Add the given key-value pair to this map as well as recording the entry's expiration time based on the current time in milliseconds and this map's `expiringPolicy`.

      Note that the return type is Object, rather than V as in the Map interface. See the class Javadoc for further info.

      Specified by:
        `put` in interface `Map<K,V>`
      Specified by:
        `put` in interface `Put<K,V>`
      Overrides:
        `put` in class `AbstractMapDecorator<K,V>`
      Parameters:
        `key` - key with which the specified value is to be associated
        `value` - value to be associated with the specified key
      Returns:
        the previous value associated with `key`, or `null` if there was no mapping for `key`. (A `null` return can also indicate that the map previously associated `null` with `key`, if the implementation supports `null` values.)
      See Also:
        `Map.put(Object, Object)`

    - #### putAll

          public void putAll(Map<? extends K,? extends V> mapToCopy)

      Specified by:
        `putAll` in interface `Map<K,V>`
      Specified by:
        `putAll` in interface `Put<K,V>`
      Overrides:
        `putAll` in class `AbstractMapDecorator<K,V>`
      Parameters:
        `mapToCopy` - mappings to be stored in this map
      See Also:
        `Map.putAll(Map)`

    - #### remove

          public V remove(Object key)

      Normal `Map.remove(Object)` behavior with the addition of removing any expiration entry as well.
      Specified by:
        `remove` in interface `Map<K,V>`
      Specified by:
        `remove` in interface `Get<K,V>`
      Overrides:
        `remove` in class `AbstractMapDecorator<K,V>`
      Parameters:
        `key` - key whose mapping is to be removed from the map
      Returns:
        the previous value associated with `key`, or `null` if there was no mapping for `key`.
      See Also:
        `Map.remove(Object)`

    - #### size

          public int size()

      All expired entries are removed from the map prior to returning the size.
      Specified by:
        `size` in interface `Map<K,V>`
      Specified by:
        `size` in interface `Get<K,V>`
      Overrides:
        `size` in class `AbstractMapDecorator<K,V>`
      Returns:
        the number of key-value mappings in this map
      See Also:
        `Map.size()`

    - #### values

          public Collection<V> values()

      All expired entries are removed from the map prior to returning the value collection.
      Specified by:
        `values` in interface `Map<K,V>`
      Specified by:
        `values` in interface `Get<K,V>`
      Overrides:
        `values` in class `AbstractMapDecorator<K,V>`
      Returns:
        a collection view of the values contained in this map
      See Also:
        `Map.values()`

Copyright © 2001–2019 The Apache Software Foundation. All rights reserved.