@GwtCompatible(emulated=true) public final class MapMaker extends Object
ConcurrentMap
instances that can have keys or values automatically wrapped
in weak references.
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()
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()
or weakValues()
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 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 Entry
, 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 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)
.
Constructor and Description |
---|
MapMaker()
Constructs a new
MapMaker instance with default settings, including strong keys, strong
values, and no automatic eviction of any kind. |
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.
|
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). |
public MapMaker()
MapMaker
instance with default settings, including strong keys, strong
values, and no automatic eviction of any kind.@CanIgnoreReturnValue public MapMaker initialCapacity(int initialCapacity)
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.IllegalArgumentException
- if initialCapacity
is negativeIllegalStateException
- if an initial capacity was already set@CanIgnoreReturnValue public MapMaker concurrencyLevel(int concurrencyLevel)
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.
IllegalArgumentException
- if concurrencyLevel
is nonpositiveIllegalStateException
- if a concurrency level was already set@CanIgnoreReturnValue @GwtIncompatible public MapMaker weakKeys()
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.
IllegalStateException
- if the key strength was already setWeakReference
@CanIgnoreReturnValue @GwtIncompatible public MapMaker weakValues()
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.
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.
IllegalStateException
- if the value strength was already setWeakReference
public <K,V> ConcurrentMap<K,V> makeMap()
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.
Copyright © 2010–2019. All rights reserved.