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
#entrySet(),
#keySet() and
#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(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
Mapimplementations via the
CopyOnWriteMaps static
Builder.
Collection views of the keys, values and entries are optionally
View.Type.LIVE or
View.Type.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
#get(Object) method and are
therefore not suitable candidates as delegates for this class.