org.apache.commons.collections4.map

Class LRUMap<K,V>

java.lang.Object

java.util.AbstractMap<K,V>

org.apache.commons.collections4.map.AbstractHashedMap<K,V>

org.apache.commons.collections4.map.AbstractLinkedMap<K,V>

org.apache.commons.collections4.map.LRUMap<K,V>

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.util.Map<K,V>, BoundedMap<K,V>, Get<K,V>, IterableGet<K,V>, IterableMap<K,V>, OrderedMap<K,V>, Put<K,V>

public class LRUMap<K,V>
extends AbstractLinkedMap<K,V>
implements BoundedMap<K,V>, java.io.Serializable, java.lang.Cloneable

A Map implementation with a fixed maximum size which removes the least recently used entry if an entry is added when full.

The least recently used algorithm works on the get and put operations only. Iteration of any kind, including setting the value by iteration, does not change the order. Queries such as containsKey and containsValue or access via views also do not change the order.

A somewhat subtle ramification of the least recently used algorithm is that calls to get(Object) stand a very good chance of modifying the map's iteration order and thus invalidating any iterators currently in use. It is therefore suggested that iterations over an LRUMap instance access entry values only through a MapIterator or AbstractHashedMap.entrySet() iterator.

The map implements OrderedMap and entries may be queried using the bidirectional OrderedMapIterator. The order returned is least recently used to most recently used. Iterators from map views can also be cast to OrderedIterator if required.

All the available iterators can be reset back to the start by casting to ResettableIterator and calling reset().

Note that LRUMap 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 NullPointerException's when accessed by concurrent threads.

Since:

3.0 (previously in main package v1.0)

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class java.util.AbstractMap

java.util.AbstractMap.SimpleEntry<K,V>, java.util.AbstractMap.SimpleImmutableEntry<K,V>

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

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

Constructor Summary

Constructors

Constructor and Description
LRUMap() Constructs a new empty map with a maximum size of 100.
LRUMap(int maxSize) Constructs a new, empty map with the specified maximum size.
LRUMap(int maxSize, boolean scanUntilRemovable) Constructs a new, empty map with the specified maximum size.
LRUMap(int maxSize, float loadFactor) Constructs a new, empty map with the specified max capacity and load factor.
LRUMap(int maxSize, float loadFactor, boolean scanUntilRemovable) Constructs a new, empty map with the specified max capacity and load factor.
LRUMap(int maxSize, int initialSize) Constructs a new, empty map with the specified maximum size.
LRUMap(int maxSize, int initialSize, float loadFactor) Constructs a new, empty map with the specified max / initial capacity and load factor.
LRUMap(int maxSize, int initialSize, float loadFactor, boolean scanUntilRemovable) Constructs a new, empty map with the specified max / initial capacity and load factor.
LRUMap(java.util.Map<? extends K,? extends V> map) Constructor copying elements from another map.
LRUMap(java.util.Map<? extends K,? extends V> map, boolean scanUntilRemovable) Constructor copying elements from another map.

Method Summary

Modifier and Type	Method and Description
LRUMap<K,V>	clone() Clones the map without cloning the keys or values.
V	get(java.lang.Object key) Gets the value mapped to the key specified.
V	get(java.lang.Object key, boolean updateToMRU) Gets the value mapped to the key specified.
boolean	isFull() Returns true if this map is full and no new mappings can be added.
boolean	isScanUntilRemovable() Whether this LRUMap will scan until a removable entry is found when the map is full.
int	maxSize() Gets the maximum size of the map (the bound).

Methods inherited from class org.apache.commons.collections4.map.AbstractLinkedMap

clear, containsValue, firstKey, lastKey, mapIterator, nextKey, previousKey

Methods inherited from class org.apache.commons.collections4.map.AbstractHashedMap

containsKey, entrySet, equals, hashCode, isEmpty, keySet, put, putAll, remove, size, toString, values

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map

clear, compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, entrySet, equals, forEach, getOrDefault, hashCode, isEmpty, keySet, merge, put, putAll, putIfAbsent, remove, remove, replace, replace, replaceAll, size, values

Methods inherited from interface org.apache.commons.collections4.Put

clear, put, putAll

Methods inherited from interface org.apache.commons.collections4.IterableGet

mapIterator

Methods inherited from interface org.apache.commons.collections4.Get

containsKey, containsValue, entrySet, isEmpty, keySet, remove, size, values

Constructor Detail

LRUMap

public LRUMap()

Constructs a new empty map with a maximum size of 100.

LRUMap

public LRUMap(int maxSize)

Constructs a new, empty map with the specified maximum size.

Parameters:

maxSize - the maximum size of the map

Throws:

java.lang.IllegalArgumentException - if the maximum size is less than one

LRUMap

public LRUMap(int maxSize,
              int initialSize)

Constructs a new, empty map with the specified maximum size.

Parameters:

maxSize - the maximum size of the map

initialSize - the initial size of the map

Throws:

java.lang.IllegalArgumentException - if the maximum size is less than one

java.lang.IllegalArgumentException - if the initial size is negative or larger than the maximum size

Since:

4.1

LRUMap

public LRUMap(int maxSize,
              boolean scanUntilRemovable)

Constructs a new, empty map with the specified maximum size.

Parameters:

maxSize - the maximum size of the map

scanUntilRemovable - scan until a removeable entry is found, default false

Throws:

java.lang.IllegalArgumentException - if the maximum size is less than one

Since:

3.1

LRUMap

public LRUMap(int maxSize,
              float loadFactor)

Constructs a new, empty map with the specified max capacity and load factor.

Parameters:

maxSize - the maximum size of the map

loadFactor - the load factor

Throws:

java.lang.IllegalArgumentException - if the maximum size is less than one

java.lang.IllegalArgumentException - if the load factor is less than zero

LRUMap

public LRUMap(int maxSize,
              int initialSize,
              float loadFactor)

Constructs a new, empty map with the specified max / initial capacity and load factor.

Parameters:

maxSize - the maximum size of the map

initialSize - the initial size of the map

loadFactor - the load factor

Throws:

java.lang.IllegalArgumentException - if the maximum size is less than one

java.lang.IllegalArgumentException - if the initial size is negative or larger than the maximum size

java.lang.IllegalArgumentException - if the load factor is less than zero

Since:

4.1

LRUMap

public LRUMap(int maxSize,
              float loadFactor,
              boolean scanUntilRemovable)

Constructs a new, empty map with the specified max capacity and load factor.

Parameters:

maxSize - the maximum size of the map

loadFactor - the load factor

scanUntilRemovable - scan until a removeable entry is found, default false

Throws:

java.lang.IllegalArgumentException - if the maximum size is less than one

java.lang.IllegalArgumentException - if the load factor is less than zero

Since:

3.1

LRUMap

public LRUMap(int maxSize,
              int initialSize,
              float loadFactor,
              boolean scanUntilRemovable)

Constructs a new, empty map with the specified max / initial capacity and load factor.

Parameters:

maxSize - the maximum size of the map

initialSize - the initial size of the map

loadFactor - the load factor

scanUntilRemovable - scan until a removeable entry is found, default false

Throws:

java.lang.IllegalArgumentException - if the maximum size is less than one

java.lang.IllegalArgumentException - if the initial size is negative or larger than the maximum size

java.lang.IllegalArgumentException - if the load factor is less than zero

Since:

4.1

LRUMap

public LRUMap(java.util.Map<? extends K,? extends V> map)

Constructor copying elements from another map.

The maximum size is set from the map's size.

Parameters:

map - the map to copy

Throws:

java.lang.NullPointerException - if the map is null

java.lang.IllegalArgumentException - if the map is empty

LRUMap

public LRUMap(java.util.Map<? extends K,? extends V> map,
              boolean scanUntilRemovable)

Constructor copying elements from another map.

The maximum size is set from the map's size.

Parameters:

map - the map to copy

scanUntilRemovable - scan until a removeable entry is found, default false

Throws:

java.lang.NullPointerException - if the map is null

java.lang.IllegalArgumentException - if the map is empty

Since:

3.1

Method Detail

get

public V get(java.lang.Object key)

Gets the value mapped to the key specified.

This operation changes the position of the key in the map to the most recently used position (last).

Specified by:

get in interface java.util.Map<K,V>

Specified by:

get in interface Get<K,V>

Overrides:

get in class AbstractHashedMap<K,V>

Parameters:

key - the key

Returns:

the mapped value, null if no match

See Also:

Map.get(Object)

get

public V get(java.lang.Object key,
             boolean updateToMRU)

Gets the value mapped to the key specified.

If updateToMRU is true, the position of the key in the map is changed to the most recently used position (last), otherwise the iteration order is not changed by this operation.

Parameters:

key - the key

updateToMRU - whether the key shall be updated to the most recently used position

Returns:

the mapped value, null if no match

Since:

4.1

isFull

public boolean isFull()

Returns true if this map is full and no new mappings can be added.

Specified by:

isFull in interface BoundedMap<K,V>

Returns:

true if the map is full

maxSize

public int maxSize()

Gets the maximum size of the map (the bound).

Specified by:

maxSize in interface BoundedMap<K,V>

Returns:

the maximum number of elements the map can hold

isScanUntilRemovable

public boolean isScanUntilRemovable()

Whether this LRUMap will scan until a removable entry is found when the map is full.

Returns:

true if this map scans

Since:

3.1

clone

public LRUMap<K,V> clone()

Clones the map without cloning the keys or values.

Returns:

a shallow clone