Class 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:
Serializable
,Map<K,
,V> Get<K,
,V> IterableGet<K,
,V> IterableMap<K,
,V> Put<K,
V>
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:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic class
AExpirationPolicy
that returns a expiration time that is a constant about of time in the future from the current time.static interface
A policy to determine the expiration time for key-value entries. -
Field Summary
FieldsModifier and TypeFieldDescriptionmap used to manage expiration times for the actual map entries.private final PassiveExpiringMap.ExpirationPolicy
<K, V> the policy used to determine time-to-live values for map entries.private static final long
Serialization versionFields inherited from class org.apache.commons.collections4.map.AbstractMapDecorator
map
-
Constructor Summary
ConstructorsConstructorDescriptionDefault 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, 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, 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 createPassiveExpiringMap.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 aPassiveExpiringMap.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
Modifier and TypeMethodDescriptionvoid
clear()
NormalMap.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.entrySet()
All expired entries are removed from the map prior to returning the entry set.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
Determines if the given expiration time is less thannow
.keySet()
All expired entries are removed from the map prior to returning the key set.private long
now()
The current time in milliseconds.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
private void
Read the map in using a custom routine.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
(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, TimeUnit timeUnit) First validate the input parameters.values()
All expired entries are removed from the map prior to returning the value collection.private void
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 Details
-
serialVersionUID
private static final long serialVersionUIDSerialization version- See Also:
-
expirationMap
map used to manage expiration times for the actual map entries. -
expiringPolicy
the policy used to determine time-to-live values for map entries.
-
-
Constructor Details
-
PassiveExpiringMap
public PassiveExpiringMap()Default constructor. Constructs a map decorator that results in entries NEVER expiring. -
PassiveExpiringMap
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
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 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
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:
NullPointerException
- if the map is null.
-
PassiveExpiringMap
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:
NullPointerException
- if the time unit is null.
-
PassiveExpiringMap
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:
NullPointerException
- if the map or time unit is null.
-
PassiveExpiringMap
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 Details
-
validateAndConvertToMillis
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:
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
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 interfaceMap<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:
-
containsValue
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 interfaceMap<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:
-
entrySet
All expired entries are removed from the map prior to returning the entry set. -
get
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 interfaceMap<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:
-
isEmpty
public boolean isEmpty()All expired entries are removed from the map prior to determining if it is empty. -
isExpired
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
All expired entries are removed from the map prior to returning the key set. -
now
private long now()The current time in milliseconds. -
put
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 interfaceMap<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:
-
putAll
-
remove
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 interfaceMap<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:
-
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:
-
removeIfExpired
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
Read the map in using a custom routine.- Parameters:
in
- the input stream- Throws:
IOException
- if an error occurs while reading from the streamClassNotFoundException
- if an object read from the stream can not be loaded
-
writeObject
Write the map out using a custom routine.- Parameters:
out
- the output stream- Throws:
IOException
- if an error occurs while writing to the stream
-
values
All expired entries are removed from the map prior to returning the value collection.
-