K
- the key typeV
- the value type@ThreadSafe abstract class CopyOnWriteMap<K,V> extends AbstractCopyOnWriteMap<K,V,java.util.Map<K,V>>
A thread-safe variant of Map
in which all mutative operations (the "destructive" operations described by Map
put, remove and so on) are implemented by making a fresh copy of the underlying map.
This is ordinarily too costly, but may be more efficient than alternatives when traversal operations vastly out-number
mutations, and is useful when you cannot or don't want to synchronize traversals, yet need to preclude interference among concurrent
threads. The "snapshot" style iterators on the collections returned by AbstractCopyOnWriteMap.entrySet()
, AbstractCopyOnWriteMap.keySet()
and AbstractCopyOnWriteMap.values()
use a
reference to the internal map at the point that the iterator was created. This map never changes during the lifetime of the iterator, so
interference is impossible and the iterator is guaranteed not to throw ConcurrentModificationException. The iterators will not
reflect additions, removals, or changes to the list since the iterator was created. Removing elements via these iterators is not
supported. The mutable operations on these collections (remove, retain etc.) are supported but as with the Map
interface, add and addAll are not and throw UnsupportedOperationException
.
The actual copy is performed by an abstract
copy(java.util.Map)
method. The method is responsible for the underlying Map implementation (for instance a HashMap
, TreeMap
, LinkedHashMap
etc.) and therefore the semantics of what this map will
cope with as far as null keys and values, iteration ordering etc. See the note below about suitable candidates for underlying Map
implementations
There are supplied implementations for the common j.u.c Map
implementations via the CopyOnWriteMap
static
CopyOnWriteMap.Builder
.
Collection views of the keys, values and entries are optionally live
or stable
. Live
views are modifiable will cause a copy if a modifying method is called on them. Methods on these will reflect the current state of the
collection, although iterators will be snapshot style. If the collection views are stable they are unmodifiable, and will be a snapshot
of the state of the map at the time the collection was asked for.
Please note that the thread-safety guarantees are limited to the thread-safety of the non-mutative (non-destructive)
operations of the underlying map implementation. For instance some implementations such as WeakHashMap
and LinkedHashMap
with access ordering are actually structurally modified by the AbstractCopyOnWriteMap.get(Object)
method and are therefore not
suitable candidates as delegates for this class.
Modifier and Type | Class and Description |
---|---|
static class |
CopyOnWriteMap.Builder<K,V>
Build a
CopyOnWriteMap and specify all the options. |
(package private) static class |
CopyOnWriteMap.Hash<K,V>
Uses
HashMap instances as its internal storage. |
(package private) static class |
CopyOnWriteMap.Linked<K,V>
Uses
LinkedHashMap instances as its internal storage. |
AbstractCopyOnWriteMap.CollectionView<E>, AbstractCopyOnWriteMap.Immutable, AbstractCopyOnWriteMap.Mutable, AbstractCopyOnWriteMap.View<K,V>
Modifier and Type | Field and Description |
---|---|
private static long |
serialVersionUID |
Modifier | Constructor and Description |
---|---|
protected |
CopyOnWriteMap()
Deprecated.
since 0.0.12 use the versions that explicitly specify View.Type
|
protected |
CopyOnWriteMap(AbstractCopyOnWriteMap.View.Type viewType)
Create a new empty
CopyOnWriteMap . |
protected |
CopyOnWriteMap(java.util.Map<? extends K,? extends V> map)
Deprecated.
since 0.0.12 use the versions that explicitly specify View.Type
|
protected |
CopyOnWriteMap(java.util.Map<? extends K,? extends V> map,
AbstractCopyOnWriteMap.View.Type viewType)
Create a new
CopyOnWriteMap with the supplied Map to initialize the values. |
Modifier and Type | Method and Description |
---|---|
static <K,V> CopyOnWriteMap.Builder<K,V> |
builder()
Get a
CopyOnWriteMap.Builder for a CopyOnWriteMap instance. |
protected abstract <N extends java.util.Map<? extends K,? extends V>> |
copy(N map)
Copy function, implemented by sub-classes.
|
static <K,V> CopyOnWriteMap<K,V> |
newHashMap()
Creates a new
CopyOnWriteMap with an underlying HashMap . |
static <K,V> CopyOnWriteMap<K,V> |
newHashMap(java.util.Map<? extends K,? extends V> map)
Creates a new
CopyOnWriteMap with an underlying HashMap using the supplied map as the initial values. |
static <K,V> CopyOnWriteMap<K,V> |
newLinkedMap()
Creates a new
CopyOnWriteMap with an underlying LinkedHashMap . |
static <K,V> CopyOnWriteMap<K,V> |
newLinkedMap(java.util.Map<? extends K,? extends V> map)
Creates a new
CopyOnWriteMap with an underlying LinkedHashMap using the supplied map as the initial
values. |
clear, containsKey, containsValue, copy, entrySet, equals, get, getDelegate, hashCode, isEmpty, keySet, put, putAll, putIfAbsent, remove, remove, replace, replace, set, size, toString, values
private static final long serialVersionUID
@Deprecated protected CopyOnWriteMap(java.util.Map<? extends K,? extends V> map)
CopyOnWriteMap
with the supplied Map
to initialize the values.map
- the initial map to initialize with@Deprecated protected CopyOnWriteMap()
CopyOnWriteMap
.protected CopyOnWriteMap(java.util.Map<? extends K,? extends V> map, AbstractCopyOnWriteMap.View.Type viewType)
CopyOnWriteMap
with the supplied Map
to initialize the values. This map may be optionally modified using
any of the key, entry or value viewsmap
- the initial map to initialize withprotected CopyOnWriteMap(AbstractCopyOnWriteMap.View.Type viewType)
CopyOnWriteMap
. This map may be optionally modified using any of the key, entry or value viewspublic static <K,V> CopyOnWriteMap.Builder<K,V> builder()
CopyOnWriteMap.Builder
for a CopyOnWriteMap instance.K
- key typeV
- value typepublic static <K,V> CopyOnWriteMap<K,V> newHashMap()
Creates a new CopyOnWriteMap
with an underlying HashMap
.
This map has stable
views.
public static <K,V> CopyOnWriteMap<K,V> newHashMap(java.util.Map<? extends K,? extends V> map)
Creates a new CopyOnWriteMap
with an underlying HashMap
using the supplied map as the initial values.
This map has stable
views.
public static <K,V> CopyOnWriteMap<K,V> newLinkedMap()
Creates a new CopyOnWriteMap
with an underlying LinkedHashMap
. Iterators for this map will be return
elements in insertion order.
This map has stable
views.
public static <K,V> CopyOnWriteMap<K,V> newLinkedMap(java.util.Map<? extends K,? extends V> map)
Creates a new CopyOnWriteMap
with an underlying LinkedHashMap
using the supplied map as the initial
values. Iterators for this map will be return elements in insertion order.
This map has stable
views.
protected abstract <N extends java.util.Map<? extends K,? extends V>> java.util.Map<K,V> copy(N map)
AbstractCopyOnWriteMap