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 mapV
- 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 aMap
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 usingCollections.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 Description static class
PassiveExpiringMap.ConstantTimeToLiveExpirationPolicy<K,V>
AExpirationPolicy
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.
-
Field Summary
Fields Modifier and Type Field 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 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 aPassiveExpiringMap.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 aPassiveExpiringMap.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 createPassiveExpiringMap.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 aPassiveExpiringMap.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
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
clear()
NormalMap.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 thannow
.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'sexpiringPolicy
.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)
NormalMap.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 thannow
.private void
removeIfExpired(java.lang.Object key, long now)
Removes the entry with the given key if the entry's expiration time is less thannow
.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
-
-
-
-
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 aPassiveExpiringMap.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 aPassiveExpiringMap.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 aPassiveExpiringMap.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 thetimeToLive
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 createPassiveExpiringMap.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 thetimeToLive
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 thetimeToLive
parameter, must not be null.- Throws:
java.lang.NullPointerException
- if the time unit is null.
-
clear
public void clear()
NormalMap.clear()
behavior with the addition of clearing all expiration entries as well.
-
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 interfaceGet<K,V>
- Specified by:
containsKey
in interfacejava.util.Map<K,V>
- Overrides:
containsKey
in classAbstractMapDecorator<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 interfaceGet<K,V>
- Specified by:
containsValue
in interfacejava.util.Map<K,V>
- Overrides:
containsValue
in classAbstractMapDecorator<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.
-
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 interfaceGet<K,V>
- Specified by:
get
in interfacejava.util.Map<K,V>
- Overrides:
get
in classAbstractMapDecorator<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.
-
isExpired
private boolean isExpired(long now, java.lang.Long expirationTimeObject)
Determines if the given expiration time is less thannow
.- Parameters:
now
- the time in milliseconds used to compare against the expiration time.expirationTimeObject
- the expiration time value retrieved fromexpirationMap
, can be null.- Returns:
true
ifexpirationTimeObject
is ≥ 0 andexpirationTimeObject
<now
.false
otherwise.
-
keySet
public java.util.Set<K> keySet()
All expired entries are removed from the map prior to returning the key set.
-
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'sexpiringPolicy
.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 interfacejava.util.Map<K,V>
- Specified by:
put
in interfacePut<K,V>
- Overrides:
put
in classAbstractMapDecorator<K,V>
- Parameters:
key
- key with which the specified value is to be associatedvalue
- value to be associated with the specified key- Returns:
- the previous value associated with
key
, ornull
if there was no mapping forkey
. (Anull
return can also indicate that the map previously associatednull
withkey
, if the implementation supportsnull
values.) - See Also:
Map.put(Object, Object)
-
remove
public V remove(java.lang.Object key)
NormalMap.remove(Object)
behavior with the addition of removing any expiration entry as well.- Specified by:
remove
in interfaceGet<K,V>
- Specified by:
remove
in interfacejava.util.Map<K,V>
- Overrides:
remove
in classAbstractMapDecorator<K,V>
- Parameters:
key
- key whose mapping is to be removed from the map- Returns:
- the previous value associated with
key
, ornull
if there was no mapping forkey
. - See Also:
Map.remove(Object)
-
removeAllExpired
private void removeAllExpired(long now)
Removes all entries in the map whose expiration time is less thannow
. 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 thannow
. 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.
-
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 streamjava.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.
-
-