org.apache.commons.collections4.map
Class PassiveExpiringMap<K,V>

java.lang.Object
  extended by org.apache.commons.collections4.map.AbstractIterableMap<K,V>
      extended by org.apache.commons.collections4.map.AbstractMapDecorator<K,V>
          extended by org.apache.commons.collections4.map.PassiveExpiringMap<K,V>
Type Parameters:
K - the type of the keys in the map
V - the type of the values in the 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.ConstantTimeToLiveExpirationPolicy 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
Version:
$Id: PassiveExpiringMap.java 1481598 2013-05-12 16:28:28Z tn $
See Also:
Serialized Form

Nested Class Summary
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
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
 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)
          Note that the return type is Object, rather than V as in the Map interface.
 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
 

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.

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:
IllegalArgumentException - if the map 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:
IllegalArgumentException - 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:
IllegalArgumentException - 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:
IllegalArgumentException - if the time unit is null.
IllegalArgumentException - if the map 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:
IllegalArgumentException - 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>
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>
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>
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>
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>
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>
See Also:
Map.keySet()

put

public V put(K key,
             V value)
Description copied from interface: Put
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>
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>
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>
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>
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>
See Also:
Map.values()


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