Package net.jodah.expiringmap

Class ExpiringMap<K,V>

java.lang.Object

net.jodah.expiringmap.ExpiringMap<K,V>

Type Parameters:

K - Key type

V - Value type

All Implemented Interfaces:

ConcurrentMap<K,V>, Map<K,V>

public class ExpiringMap<K,V>
extends Object
implements ConcurrentMap<K,V>

A thread-safe map that expires entries. Optional features include expiration policies, variable entry expiration, lazy entry loading, and expiration listeners.

Entries are tracked by expiration time and expired by a single thread.

Expiration listeners are called synchronously as entries are expired and block write operations to the map until they completed. Asynchronous expiration listeners are called on a separate thread pool and do not block map operations.

When variable expiration is disabled (default), put/remove operations have a time complexity O(1). When variable expiration is enabled, put/remove operations have time complexity of O(log n).

Example usages:

 
 Map<String, Integer> map = ExpiringMap.create();
 Map<String, Integer> map = ExpiringMap.builder().expiration(30, TimeUnit.SECONDS).build();
 Map<String, Connection> map = ExpiringMap.builder()
   .expiration(10, TimeUnit.MINUTES)
   .entryLoader(new EntryLoader<String, Connection>() {
     public Connection load(String address) {
       return new Connection(address);
     }
   })
   .expirationListener(new ExpirationListener<String, Connection>() {
     public void expired(String key, Connection connection) {
       connection.close();
     }
   })
   .build();
 
 

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ExpiringMap.Builder<K,V>	Builds ExpiringMap instances.

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

Map.Entry<K extends Object,V extends Object>

Method Summary

Modifier and Type	Method	Description
void	addAsyncExpirationListener(ExpirationListener<K,V> listener)	Adds an asynchronous expiration listener.
void	addExpirationListener(ExpirationListener<K,V> listener)	Adds an expiration listener.
static ExpiringMap.Builder<Object,Object>	builder()	Creates an ExpiringMap builder.
void	clear()
boolean	containsKey(Object key)
boolean	containsValue(Object value)
static <K,V> ExpiringMap<K,V>	create()	Creates a new instance of ExpiringMap with ExpirationPolicy.CREATED and an expiration of 60 seconds.
Set<Map.Entry<K,V>>	entrySet()	Returns a copy of the map's entries, which can be iterated over safely by multiple threads.
boolean	equals(Object obj)
V	get(Object key)
long	getExpectedExpiration(K key)	Gets the expected expiration, in milliseconds from the current time, for the entry corresponding to the given key.
long	getExpiration()	Returns the map's default expiration duration in milliseconds.
long	getExpiration(K key)	Gets the expiration duration in milliseconds for the entry corresponding to the given key.
ExpirationPolicy	getExpirationPolicy(K key)	Gets the ExpirationPolicy for the entry corresponding to the given key.
int	getMaxSize()	Gets the maximum size of the map.
int	hashCode()
boolean	isEmpty()
Set<K>	keySet()	Returns a copy of the map's keys, which can be iterated over safely by multiple threads.
V	put(K key, V value)	Puts value in the map for key.
V	put(K key, V value, long duration, TimeUnit timeUnit)
V	put(K key, V value, ExpirationPolicy expirationPolicy)
V	put(K key, V value, ExpirationPolicy expirationPolicy, long duration, TimeUnit timeUnit)	Puts value in the map for key.
void	putAll(Map<? extends K,? extends V> map)
V	putIfAbsent(K key, V value)
V	remove(Object key)
boolean	remove(Object key, Object value)
void	removeAsyncExpirationListener(ExpirationListener<K,V> listener)	Removes an asynchronous expiration listener.
void	removeExpirationListener(ExpirationListener<K,V> listener)	Removes an expiration listener.
V	replace(K key, V value)
boolean	replace(K key, V oldValue, V newValue)
void	resetExpiration(K key)	Resets expiration for the entry corresponding to key.
void	setExpiration(long duration, TimeUnit timeUnit)	Updates the default map entry expiration.
void	setExpiration(K key, long duration, TimeUnit timeUnit)	Sets the expiration duration for the entry corresponding to the given key.
void	setExpirationPolicy(K key, ExpirationPolicy expirationPolicy)	Sets the expiration policy for the entry corresponding to the given key.
void	setExpirationPolicy(ExpirationPolicy expirationPolicy)	Sets the global expiration policy for the map.
void	setMaxSize(int maxSize)	Sets the maximum size of the map.
static void	setThreadFactory(ThreadFactory threadFactory)	Sets the ThreadFactory that is used to create expiration and listener callback threads for all ExpiringMap instances.
int	size()
String	toString()
Collection<V>	values()	Returns a copy of the map's values, which can be iterated over safely by multiple threads.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.concurrent.ConcurrentMap

compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, replaceAll

Method Detail

setThreadFactory

public static void setThreadFactory(ThreadFactory threadFactory)

Sets the ThreadFactory that is used to create expiration and listener callback threads for all ExpiringMap instances.

Parameters:

threadFactory -

Throws:

NullPointerException - if threadFactory is null

builder

public static ExpiringMap.Builder<Object,Object> builder()

Creates an ExpiringMap builder.

Returns:

New ExpiringMap builder

create

public static <K,V> ExpiringMap<K,V> create()

Creates a new instance of ExpiringMap with ExpirationPolicy.CREATED and an expiration of 60 seconds.

addExpirationListener

public void addExpirationListener(ExpirationListener<K,V> listener)

Adds an expiration listener.

Parameters:

listener - to add

Throws:

NullPointerException - if listener is null

addAsyncExpirationListener

public void addAsyncExpirationListener(ExpirationListener<K,V> listener)

Adds an asynchronous expiration listener.

Parameters:

listener - to add

Throws:

NullPointerException - if listener is null

clear

public void clear()

Specified by:

clear in interface Map<K,V>

containsKey

public boolean containsKey(Object key)

Specified by:

containsKey in interface Map<K,V>

containsValue

public boolean containsValue(Object value)

Specified by:

containsValue in interface Map<K,V>

entrySet

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

Returns a copy of the map's entries, which can be iterated over safely by multiple threads.

Specified by:

entrySet in interface Map<K,V>

Returns:

Copied set of map entries.

equals

public boolean equals(Object obj)

Specified by:

equals in interface Map<K,V>

Overrides:

equals in class Object

get

public V get(Object key)

Specified by:

get in interface Map<K,V>

getExpiration

public long getExpiration()

Returns the map's default expiration duration in milliseconds.

Returns:

The expiration duration (milliseconds)

getExpiration

public long getExpiration(K key)

Gets the expiration duration in milliseconds for the entry corresponding to the given key.

Parameters:

key -

Returns:

The expiration duration in milliseconds

Throws:

NullPointerException - if key is null

NoSuchElementException - If no entry exists for the given key

getExpirationPolicy

public ExpirationPolicy getExpirationPolicy(K key)

Gets the ExpirationPolicy for the entry corresponding to the given key.

Parameters:

key -

Returns:

The ExpirationPolicy for the key

Throws:

NullPointerException - if key is null

NoSuchElementException - If no entry exists for the given key

getExpectedExpiration

public long getExpectedExpiration(K key)

Gets the expected expiration, in milliseconds from the current time, for the entry corresponding to the given key.

Parameters:

key -

Returns:

The expiration duration in milliseconds

Throws:

NullPointerException - if key is null

NoSuchElementException - If no entry exists for the given key

getMaxSize

public int getMaxSize()

Gets the maximum size of the map. Once this size has been reached, adding an additional entry will expire the first entry in line for expiration based on the expiration policy.

Returns:

The maximum size of the map.

hashCode

public int hashCode()

Specified by:

hashCode in interface Map<K,V>

Overrides:

hashCode in class Object

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface Map<K,V>

keySet

public Set<K> keySet()

Returns a copy of the map's keys, which can be iterated over safely by multiple threads.

Specified by:

keySet in interface Map<K,V>

Returns:

Copied set of map keys.

put

public V put(K key,
             V value)

Puts value in the map for key. Resets the entry's expiration unless an entry already exists for the same key and value.

Specified by:

put in interface Map<K,V>

Parameters:

key - to put value for

value - to put for key

Returns:

the old value

Throws:

NullPointerException - if key is null

put

public V put(K key,
             V value,
             ExpirationPolicy expirationPolicy)

See Also:

put(Object, Object, ExpirationPolicy, long, TimeUnit)

put

public V put(K key,
             V value,
             long duration,
             TimeUnit timeUnit)

See Also:

put(Object, Object, ExpirationPolicy, long, TimeUnit)

put

public V put(K key,
             V value,
             ExpirationPolicy expirationPolicy,
             long duration,
             TimeUnit timeUnit)

Puts value in the map for key. Resets the entry's expiration unless an entry already exists for the same key and value. Requires that variable expiration be enabled.

Parameters:

key - Key to put value for

value - Value to put for key

duration - the length of time after an entry is created that it should be removed

timeUnit - the unit that duration is expressed in

Returns:

the old value

Throws:

UnsupportedOperationException - If variable expiration is not enabled

NullPointerException - if key, expirationPolicy or timeUnit are null

putAll

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

Specified by:

putAll in interface Map<K,V>

putIfAbsent

public V putIfAbsent(K key,
                     V value)

Specified by:

putIfAbsent in interface ConcurrentMap<K,V>

Specified by:

putIfAbsent in interface Map<K,V>

remove

public V remove(Object key)

Specified by:

remove in interface Map<K,V>

remove

public boolean remove(Object key,
                      Object value)

Specified by:

remove in interface ConcurrentMap<K,V>

Specified by:

remove in interface Map<K,V>

replace

public V replace(K key,
                 V value)

Specified by:

replace in interface ConcurrentMap<K,V>

Specified by:

replace in interface Map<K,V>

replace

public boolean replace(K key,
                       V oldValue,
                       V newValue)

Specified by:

replace in interface ConcurrentMap<K,V>

Specified by:

replace in interface Map<K,V>

removeExpirationListener

public void removeExpirationListener(ExpirationListener<K,V> listener)

Removes an expiration listener.

Parameters:

listener -

Throws:

NullPointerException - if listener is null

removeAsyncExpirationListener

public void removeAsyncExpirationListener(ExpirationListener<K,V> listener)

Removes an asynchronous expiration listener.

Parameters:

listener -

Throws:

NullPointerException - if listener is null

resetExpiration

public void resetExpiration(K key)

Resets expiration for the entry corresponding to key.

Parameters:

key - to reset expiration for

Throws:

NullPointerException - if key is null

setExpiration

public void setExpiration(K key,
                          long duration,
                          TimeUnit timeUnit)

Sets the expiration duration for the entry corresponding to the given key. Supported only if variable expiration is enabled.

Parameters:

key - Key to set expiration for

duration - the length of time after an entry is created that it should be removed

timeUnit - the unit that duration is expressed in

Throws:

NullPointerException - if key or timeUnit are null

UnsupportedOperationException - If variable expiration is not enabled

setExpiration

public void setExpiration(long duration,
                          TimeUnit timeUnit)

Updates the default map entry expiration. Supported only if variable expiration is enabled.

Parameters:

duration - the length of time after an entry is created that it should be removed

timeUnit - the unit that duration is expressed in

Throws:

NullPointerException - timeUnit is null

UnsupportedOperationException - If variable expiration is not enabled

setExpirationPolicy

public void setExpirationPolicy(ExpirationPolicy expirationPolicy)

Sets the global expiration policy for the map. Individual expiration policies may override the global policy.

Parameters:

expirationPolicy -

Throws:

NullPointerException - expirationPolicy is null

setExpirationPolicy

public void setExpirationPolicy(K key,
                                ExpirationPolicy expirationPolicy)

Sets the expiration policy for the entry corresponding to the given key.

Parameters:

key - to set policy for

expirationPolicy - to set

Throws:

NullPointerException - if key or expirationPolicy are null

UnsupportedOperationException - If variable expiration is not enabled

setMaxSize

public void setMaxSize(int maxSize)

Sets the maximum size of the map. Once this size has been reached, adding an additional entry will expire the first entry in line for expiration based on the expiration policy.

Parameters:

maxSize - The maximum size of the map.

size

public int size()

Specified by:

size in interface Map<K,V>

toString

public String toString()

Overrides:

toString in class Object

values

public Collection<V> values()

Returns a copy of the map's values, which can be iterated over safely by multiple threads.

Specified by:

values in interface Map<K,V>

Returns:

Copied set of map values.