com.googlecode.concurrentlinkedhashmap
Class ConcurrentLinkedHashMap<K,V>

java.lang.Object
  java.util.AbstractMap<K,V>
      com.googlecode.concurrentlinkedhashmap.ConcurrentLinkedHashMap<K,V>

Type Parameters:

K - the type of keys maintained by this map

V - the type of mapped values

All Implemented Interfaces:

java.io.Serializable, java.util.concurrent.ConcurrentMap<K,V>, java.util.Map<K,V>

@ThreadSafe
public final class ConcurrentLinkedHashMap<K,V>
extends java.util.AbstractMap<K,V>
implements java.util.concurrent.ConcurrentMap<K,V>, java.io.Serializable

A hash table supporting full concurrency of retrievals, adjustable expected concurrency for updates, and a maximum capacity to bound the map by. This implementation differs from ConcurrentHashMap in that it maintains a page replacement algorithm that is used to evict an entry when the map has exceeded its capacity. Unlike the Java Collections Framework, this map does not have a publicly visible constructor and instances are created through a ConcurrentLinkedHashMap.Builder.

An entry is evicted from the map when the weighted capacity exceeds a threshold determined by a CapacityLimiter. The default limiter bounds the map by its maximum weighted capacity. A Weigher instance determines how many units of capacity that a value consumes. The default weigher assigns each value a weight of 1 to bound the map by the total number of key-value pairs. A map that holds collections may choose to weigh values by the number of elements in the collection and bound the map by the total number of elements that it contains. A change to a value that modifies its weight requires that an update operation is performed on the map.

An EvictionListener may be supplied for notification when an entry is evicted from the map. This listener is invoked on a caller's thread and will not block other threads from operating on the map. An implementation should be aware that the caller's thread will not expect long execution times or failures as a side effect of the listener being notified. Execution safety and a fast turn around time can be achieved by performing the operation asynchronously, such as by submitting a task to an ExecutorService.

The concurrency level determines the number of threads that can concurrently modify the table. Using a significantly higher or lower value than needed can waste space or lead to thread contention, but an estimate within an order of magnitude of the ideal value does not usually have a noticeable impact. Because placement in hash tables is essentially random, the actual concurrency will vary.

This class and its views and iterators implement all of the optional methods of the Map and Iterator interfaces.

Like Hashtable but unlike HashMap, this class does not allow null to be used as a key or value. Unlike LinkedHashMap, this class does not provide predictable iteration order.

Author:

ben.manes@gmail.com (Ben Manes)

See Also:

http://code.google.com/p/concurrentlinkedhashmap/, Serialized Form

Nested Class Summary

static class

ConcurrentLinkedHashMap.Builder<K,V> A builder that creates ConcurrentLinkedHashMap instances.

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

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

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

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

Method Summary

int	capacity() Retrieves the maximum weighted capacity of the map.
void	clear()
boolean	containsKey(java.lang.Object key)
boolean	containsValue(java.lang.Object value)
java.util.Set<java.util.Map.Entry<K,V>>	entrySet()
void	evictWith(CapacityLimiter capacityLimiter) Evicts entries from the map while it exceeds the capacity limiter's constraint or until the map is empty.
V	get(java.lang.Object key)
boolean	isEmpty()
java.util.Set<K>	keySet()
V	put(K key, V value)
V	putIfAbsent(K key, V value)
V	remove(java.lang.Object key)
boolean	remove(java.lang.Object key, java.lang.Object value)
V	replace(K key, V value)
boolean	replace(K key, V oldValue, V newValue)
void	setCapacity(int capacity) Sets the maximum weighted capacity of the map and eagerly evicts entries until it shrinks to the appropriate size.
int	size()
java.util.Collection<V>	values()
int	weightedSize() Returns the weighted size of this map.

Methods inherited from class java.util.AbstractMap

clone, equals, hashCode, putAll, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Map

equals, hashCode, putAll

Method Detail

capacity

public int capacity()

Retrieves the maximum weighted capacity of the map.

Returns:

the maximum weighted capacity

setCapacity

public void setCapacity(int capacity)

Sets the maximum weighted capacity of the map and eagerly evicts entries until it shrinks to the appropriate size.

Parameters:

capacity - the maximum weighted capacity of the map

Throws:

java.lang.IllegalArgumentException - if the capacity is negative

evictWith

public void evictWith(CapacityLimiter capacityLimiter)

Evicts entries from the map while it exceeds the capacity limiter's constraint or until the map is empty.

Parameters:

capacityLimiter - the algorithm to determine whether to evict an entry

Throws:

java.lang.NullPointerException - if the capacity limiter is null

isEmpty

public boolean isEmpty()

Specified by:

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

Overrides:

isEmpty in class java.util.AbstractMap<K,V>

size

public int size()

Specified by:

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

Overrides:

size in class java.util.AbstractMap<K,V>

weightedSize

public int weightedSize()

Returns the weighted size of this map.

Returns:

the combined weight of the values in this map

clear

public void clear()

Specified by:

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

Overrides:

clear in class java.util.AbstractMap<K,V>

containsKey

public boolean containsKey(java.lang.Object key)

Specified by:

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

Overrides:

containsKey in class java.util.AbstractMap<K,V>

containsValue

public boolean containsValue(java.lang.Object value)

Specified by:

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

Overrides:

containsValue in class java.util.AbstractMap<K,V>

get

public V get(java.lang.Object key)

Specified by:

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

Overrides:

get in class java.util.AbstractMap<K,V>

put

public V put(K key,
             V value)

Specified by:

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

Overrides:

put in class java.util.AbstractMap<K,V>

putIfAbsent

public V putIfAbsent(K key,
                     V value)

Specified by:

putIfAbsent in interface java.util.concurrent.ConcurrentMap<K,V>

remove

public V remove(java.lang.Object key)

Specified by:

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

Overrides:

remove in class java.util.AbstractMap<K,V>

remove

public boolean remove(java.lang.Object key,
                      java.lang.Object value)

Specified by:

remove in interface java.util.concurrent.ConcurrentMap<K,V>

replace

public V replace(K key,
                 V value)

Specified by:

replace in interface java.util.concurrent.ConcurrentMap<K,V>

replace

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

Specified by:

replace in interface java.util.concurrent.ConcurrentMap<K,V>

keySet

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

Specified by:

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

Overrides:

keySet in class java.util.AbstractMap<K,V>

values

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

Specified by:

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

Overrides:

values in class java.util.AbstractMap<K,V>

entrySet

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

Specified by:

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

Specified by:

entrySet in class java.util.AbstractMap<K,V>