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:

java.io.Serializable, java.util.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 java.io.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

java.util.Map.Entry<K,V>

Field Summary

Fields

Modifier and Type	Field and Description
private java.util.Map<java.lang.Object,java.lang.Long>	expirationMap map used to manage expiration times for the actual map entries.
private PassiveExpiringMap.ExpirationPolicy<K,V>	expiringPolicy the policy used to determine time-to-live values for map entries.
private static long	serialVersionUID Serialization version

Fields inherited from class org.apache.commons.collections4.map.AbstractMapDecorator

map

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, java.util.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, java.util.concurrent.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, java.util.concurrent.TimeUnit timeUnit, java.util.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(java.util.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, java.util.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

Modifier and Type	Method and Description
void	clear() Normal Map.clear() behavior with the addition of clearing all expiration entries as well.
boolean	containsKey(java.lang.Object key) All expired entries are removed from the map prior to determining the contains result.
boolean	containsValue(java.lang.Object value) All expired entries are removed from the map prior to determining the contains result.
java.util.Set<java.util.Map.Entry<K,V>>	entrySet() All expired entries are removed from the map prior to returning the entry set.
V	get(java.lang.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.
private boolean	isExpired(long now, java.lang.Long expirationTimeObject) Determines if the given expiration time is less than now.
java.util.Set<K>	keySet() All expired entries are removed from the map prior to returning the key set.
private long	now() The current time in milliseconds.
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(java.util.Map<? extends K,? extends V> mapToCopy)
private void	readObject(java.io.ObjectInputStream in) Read the map in using a custom routine.
V	remove(java.lang.Object key) Normal Map.remove(Object) behavior with the addition of removing any expiration entry as well.
private void	removeAllExpired(long now) Removes all entries in the map whose expiration time is less than now.
private void	removeIfExpired(java.lang.Object key, long now) Removes the entry with the given key if the entry's expiration time is less than now.
int	size() All expired entries are removed from the map prior to returning the size.
private static long	validateAndConvertToMillis(long timeToLive, java.util.concurrent.TimeUnit timeUnit) First validate the input parameters.
java.util.Collection<V>	values() All expired entries are removed from the map prior to returning the value collection.
private void	writeObject(java.io.ObjectOutputStream out) Write the map out using a custom routine.

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

Field Detail

serialVersionUID

private static final long serialVersionUID

Serialization version

See Also:

Constant Field Values

expirationMap

private final java.util.Map<java.lang.Object,java.lang.Long> expirationMap

map used to manage expiration times for the actual map entries.

expiringPolicy

private final PassiveExpiringMap.ExpirationPolicy<K,V> expiringPolicy

the policy used to determine time-to-live values for map entries.

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:

java.lang.NullPointerException - if expiringPolicy is null

PassiveExpiringMap

public PassiveExpiringMap(PassiveExpiringMap.ExpirationPolicy<K,V> expiringPolicy,
                          java.util.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:

java.lang.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,
                          java.util.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:

java.lang.NullPointerException - if the map is null.

PassiveExpiringMap

public PassiveExpiringMap(long timeToLive,
                          java.util.concurrent.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:

java.lang.NullPointerException - if the time unit is null.

PassiveExpiringMap

public PassiveExpiringMap(long timeToLive,
                          java.util.concurrent.TimeUnit timeUnit,
                          java.util.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:

java.lang.NullPointerException - if the map or time unit is null.

PassiveExpiringMap

public PassiveExpiringMap(java.util.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:

java.lang.NullPointerException - if the map is null.

Method Detail

validateAndConvertToMillis

private static long validateAndConvertToMillis(long timeToLive,
                                               java.util.concurrent.TimeUnit timeUnit)

First validate the input parameters. If the parameters are valid, convert the given time measured in the given units to the same time measured in milliseconds.

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:

java.lang.NullPointerException - if the time unit is null.

clear

public void clear()

Normal Map.clear() behavior with the addition of clearing all expiration entries as well.

Specified by:

clear in interface java.util.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(java.lang.Object key)

All expired entries are removed from the map prior to determining the contains result.

Specified by:

containsKey in interface java.util.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(java.lang.Object value)

All expired entries are removed from the map prior to determining the contains result.

Specified by:

containsValue in interface java.util.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 java.util.Set<java.util.Map.Entry<K,V>> entrySet()

All expired entries are removed from the map prior to returning the entry set.

Specified by:

entrySet in interface java.util.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(java.lang.Object key)

All expired entries are removed from the map prior to returning the entry value.

Specified by:

get in interface java.util.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 java.util.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()

isExpired

private boolean isExpired(long now,
                          java.lang.Long expirationTimeObject)

Determines if the given expiration time is less than now.

Parameters:

now - the time in milliseconds used to compare against the expiration time.

expirationTimeObject - the expiration time value retrieved from expirationMap, can be null.

Returns:

true if expirationTimeObject is ≥ 0 and expirationTimeObject < now. false otherwise.

keySet

public java.util.Set<K> keySet()

All expired entries are removed from the map prior to returning the key set.

Specified by:

keySet in interface java.util.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()

now

private long now()

The current time in milliseconds.

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 java.util.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(java.util.Map<? extends K,? extends V> mapToCopy)

Specified by:

putAll in interface java.util.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(java.lang.Object key)

Normal Map.remove(Object) behavior with the addition of removing any expiration entry as well.

Specified by:

remove in interface java.util.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)

removeAllExpired

private void removeAllExpired(long now)

Removes all entries in the map whose expiration time is less than now. The exceptions are entries with negative expiration times; those entries are never removed.

See Also:

isExpired(long, Long)

removeIfExpired

private void removeIfExpired(java.lang.Object key,
                             long now)

Removes the entry with the given key if the entry's expiration time is less than now. If the entry has a negative expiration time, the entry is never removed.

size

public int size()

All expired entries are removed from the map prior to returning the size.

Specified by:

size in interface java.util.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()

readObject

private void readObject(java.io.ObjectInputStream in)
                 throws java.io.IOException,
                        java.lang.ClassNotFoundException

Read the map in using a custom routine.

Parameters:

in - the input stream

Throws:

java.io.IOException - if an error occurs while reading from the stream

java.lang.ClassNotFoundException - if an object read from the stream can not be loaded

writeObject

private void writeObject(java.io.ObjectOutputStream out)
                  throws java.io.IOException

Write the map out using a custom routine.

Parameters:

out - the output stream

Throws:

java.io.IOException - if an error occurs while writing to the stream

values

public java.util.Collection<V> values()

All expired entries are removed from the map prior to returning the value collection.

Specified by:

values in interface java.util.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()