com.google.common.collect

Class MapMaker

java.lang.Object

com.google.common.collect.GenericMapMaker<Object,Object>

com.google.common.collect.MapMaker

@GwtCompatible(emulated=true)
public final class MapMaker
extends GenericMapMaker<Object,Object>

A builder of ConcurrentMap instances having any combination of the following features:

• keys or values automatically wrapped in weak or soft references
• notification of evicted (or otherwise removed) entries
• on-demand computation of values for keys not already present

Usage example:

   ConcurrentMap<Request, Stopwatch> timers = new MapMaker()
       .concurrencyLevel(4)
       .weakKeys()
       .makeMap();

These features are all optional; new MapMaker().makeMap() returns a valid concurrent map that behaves similarly to a ConcurrentHashMap.

The returned map is implemented as a hash table with similar performance characteristics to ConcurrentHashMap. It supports all optional operations of the ConcurrentMap interface. It does not permit null keys or values.

Note: by default, the returned map uses equality comparisons (the equals method) to determine equality for keys or values. However, if weakKeys() was specified, the map uses identity (==) comparisons instead for keys. Likewise, if weakValues() or softValues() was specified, the map uses identity comparisons for values.

The view collections of the returned map have weakly consistent iterators. This means that they are safe for concurrent use, but if other threads modify the map after the iterator is created, it is undefined which of these changes, if any, are reflected in that iterator. These iterators never throw ConcurrentModificationException.

If weakKeys(), weakValues(), or softValues() are requested, it is possible for a key or value present in the map to be reclaimed by the garbage collector. Entries with reclaimed keys or values may be removed from the map on each map modification or on occasional map accesses; such entries may be counted by Map.size(), but will never be visible to read or write operations. A partially-reclaimed entry is never exposed to the user. Any Map.Entry instance retrieved from the map's entry set is a snapshot of that entry's state at the time of retrieval; such entries do, however, support Map.Entry.setValue(V), which simply calls Map.put(K, V) on the entry's key.

The maps produced by MapMaker are serializable, and the deserialized maps retain all the configuration properties of the original map. During deserialization, if the original map had used soft or weak references, the entries are reconstructed as they were, but it's not unlikely they'll be quickly garbage-collected before they are ever accessed.

new MapMaker().weakKeys().makeMap() is a recommended replacement for WeakHashMap, but note that it compares keys using object identity whereas WeakHashMap uses Object.equals(java.lang.Object).

Since:

2.0 (imported from Google Collections Library)

Author:

Bob Lee, Charles Fry, Kevin Bourrillion

Constructor Summary

Constructors

Constructor and Description
MapMaker() Constructs a new MapMaker instance with default settings, including strong keys, strong values, and no automatic eviction of any kind.

Method Summary

Methods

Modifier and Type	Method and Description
MapMaker	concurrencyLevel(int concurrencyLevel) Guides the allowed concurrency among update operations.
MapMaker	initialCapacity(int initialCapacity) Sets the minimum total size for the internal hash tables.
<K,V> ConcurrentMap<K,V>	makeMap() Builds a thread-safe map, without on-demand computation of values.
MapMaker	softValues() Deprecated. Caching functionality in MapMaker has been moved to CacheBuilder, with softValues() being replaced by CacheBuilder.softValues(). Note that CacheBuilder is simply an enhanced API for an implementation which was branched from MapMaker. This method is scheduled for deletion in September 2014.
String	toString() Returns a string representation for this MapMaker instance.
MapMaker	weakKeys() Specifies that each key (not value) stored in the map should be wrapped in a WeakReference (by default, strong references are used).
MapMaker	weakValues() Specifies that each value (not key) stored in the map should be wrapped in a WeakReference (by default, strong references are used).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MapMaker

public MapMaker()

Constructs a new MapMaker instance with default settings, including strong keys, strong values, and no automatic eviction of any kind.

Method Detail

initialCapacity

public MapMaker initialCapacity(int initialCapacity)

Sets the minimum total size for the internal hash tables. For example, if the initial capacity is 60, and the concurrency level is 8, then eight segments are created, each having a hash table of size eight. Providing a large enough estimate at construction time avoids the need for expensive resizing operations later, but setting this value unnecessarily high wastes memory.

Specified by:

initialCapacity in class GenericMapMaker<Object,Object>

Throws:

IllegalArgumentException - if initialCapacity is negative

IllegalStateException - if an initial capacity was already set

concurrencyLevel

public MapMaker concurrencyLevel(int concurrencyLevel)

Guides the allowed concurrency among update operations. Used as a hint for internal sizing. The table is internally partitioned to try to permit the indicated number of concurrent updates without contention. Because assignment of entries to these partitions is not necessarily uniform, the actual concurrency observed may vary. Ideally, you should choose a value to accommodate as many threads as will ever concurrently modify the table. Using a significantly higher value than you need can waste space and time, and a significantly lower value can lead to thread contention. But overestimates and underestimates within an order of magnitude do not usually have much noticeable impact. A value of one permits only one thread to modify the map at a time, but since read operations can proceed concurrently, this still yields higher concurrency than full synchronization. Defaults to 4.

Note: Prior to Guava release 9.0, the default was 16. It is possible the default will change again in the future. If you care about this value, you should always choose it explicitly.

Specified by:

concurrencyLevel in class GenericMapMaker<Object,Object>

Throws:

IllegalArgumentException - if concurrencyLevel is nonpositive

IllegalStateException - if a concurrency level was already set

weakKeys

@GwtIncompatible(value="java.lang.ref.WeakReference")
public MapMaker weakKeys()

Specifies that each key (not value) stored in the map should be wrapped in a WeakReference (by default, strong references are used).

Warning: when this method is used, the resulting map will use identity (==) comparison to determine equality of keys, which is a technical violation of the Map specification, and may not be what you expect.

Specified by:

weakKeys in class GenericMapMaker<Object,Object>

Throws:

IllegalStateException - if the key strength was already set

See Also:

WeakReference

weakValues

@GwtIncompatible(value="java.lang.ref.WeakReference")
public MapMaker weakValues()

Specifies that each value (not key) stored in the map should be wrapped in a WeakReference (by default, strong references are used).

Weak values will be garbage collected once they are weakly reachable. This makes them a poor candidate for caching; consider softValues() instead.

Warning: when this method is used, the resulting map will use identity (==) comparison to determine equality of values. This technically violates the specifications of the methods containsValue, remove(Object, Object) and replace(K, V, V), and may not be what you expect.

Specified by:

weakValues in class GenericMapMaker<Object,Object>

Throws:

IllegalStateException - if the value strength was already set

See Also:

WeakReference

softValues

@Deprecated
@GwtIncompatible(value="java.lang.ref.SoftReference")
public MapMaker softValues()

Deprecated. Caching functionality in MapMaker has been moved to CacheBuilder, with softValues() being replaced by CacheBuilder.softValues(). Note that CacheBuilder is simply an enhanced API for an implementation which was branched from MapMaker. This method is scheduled for deletion in September 2014.

Specifies that each value (not key) stored in the map should be wrapped in a SoftReference (by default, strong references are used). Softly-referenced objects will be garbage-collected in a globally least-recently-used manner, in response to memory demand.

Warning: in most circumstances it is better to set a per-cache maximum size instead of using soft references. You should only use this method if you are well familiar with the practical consequences of soft references.

Warning: when this method is used, the resulting map will use identity (==) comparison to determine equality of values. This technically violates the specifications of the methods containsValue, remove(Object, Object) and replace(K, V, V), and may not be what you expect.

Specified by:

softValues in class GenericMapMaker<Object,Object>

Throws:

IllegalStateException - if the value strength was already set

See Also:

SoftReference

makeMap

public <K,V> ConcurrentMap<K,V> makeMap()

Builds a thread-safe map, without on-demand computation of values. This method does not alter the state of this MapMaker instance, so it can be invoked again to create multiple independent maps.

The bulk operations putAll, equals, and clear are not guaranteed to be performed atomically on the returned map. Additionally, size and containsValue are implemented as bulk read operations, and thus may fail to observe concurrent writes.

Specified by:

makeMap in class GenericMapMaker<Object,Object>

Returns:

a serializable concurrent map having the requested features

toString

public String toString()

Returns a string representation for this MapMaker instance. The exact form of the returned string is not specificed.

Overrides:

toString in class Object

Returns:

a string representation of the object.