CopyOnWriteMap (Atlassian Concurrency Utilities 4.0.1 API)

java.lang.Object
- io.atlassian.util.concurrent.CopyOnWriteMap<K,V>

Type Parameters:

K - the key type

V - the value type

All Implemented Interfaces:

Serializable, ConcurrentMap<K,V>, Map<K,V>
```
@ThreadSafe
public abstract class CopyOnWriteMap<K,V>
extends Object
```
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 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 get(Object) method and are therefore not suitable candidates as delegates for this class.

Author:

Jed Wesley-Smith

See Also:

Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`protected static class`	`AbstractCopyOnWriteMap.CollectionView<E>`
`static class`	`AbstractCopyOnWriteMap.View<K,V>` Provides access to the views of the underlying key, value and entry collections.
`static class`	`CopyOnWriteMap.Builder<K,V>` Build a `CopyOnWriteMap` and specify all the options.

Nested classes/interfaces inherited from interface java.util.Map
Map.Entry<K,V>

Constructor Summary

Constructors
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(Map<? extends K,? extends V> map)` Deprecated. since 0.0.12 use the versions that explicitly specify View.Type
`protected`	`CopyOnWriteMap(Map<? extends K,? extends V> map, AbstractCopyOnWriteMap.View.Type viewType)` Create a new `CopyOnWriteMap` with the supplied `Map` to initialize the values.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`static <K,V> CopyOnWriteMap.Builder<K,V>`	`builder()` Get a `CopyOnWriteMap.Builder` for a `CopyOnWriteMap` instance.
`void`	`clear()` Return a new copy containing no elements
`boolean`	`containsKey(Object key)`
`boolean`	`containsValue(Object value)`
`protected M`	`copy()` Create a copy of the underlying map.
`protected abstract <N extends Map<? extends K,? extends V>> Map<K,V>`	`copy(N map)` Copy function, implemented by sub-classes.
`Set<Map.Entry<K,V>>`	`entrySet()`
`boolean`	`equals(Object o)`
`V`	`get(Object key)`
`protected M`	`getDelegate()` Return the internal delegate map.
`int`	`hashCode()`
`boolean`	`isEmpty()`
`Set<K>`	`keySet()`
`static <K,V> CopyOnWriteMap<K,V>`	`newHashMap()` Creates a new `CopyOnWriteMap` with an underlying `HashMap`.
`static <K,V> CopyOnWriteMap<K,V>`	`newHashMap(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(Map<? extends K,? extends V> map)` Creates a new `CopyOnWriteMap` with an underlying `LinkedHashMap` using the supplied map as the initial values.
`V`	`put(K key, V value)` Add this key and its value to the map
`void`	`putAll(Map<? extends K,? extends V> t)`
`V`	`putIfAbsent(K key, V value)` If the key is not currently contained in the map add it.
`V`	`remove(Object key)`
`boolean`	`remove(Object key, Object value)`
`V`	`replace(K key, V value)` Replace the value of the key if the key is present returning the value.
`boolean`	`replace(K key, V oldValue, V newValue)` Attempt to replace the value of the key with newValues so long as the key is still associated with old value
`protected void`	`set(M map)` Set the contained map
`int`	`size()`
`String`	`toString()`
`Collection<V>`	`values()`

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.concurrent.ConcurrentMap
compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, replaceAll

- Constructor Detail
  - CopyOnWriteMap
```
@Deprecated
protected CopyOnWriteMap(Map<? extends K,? extends V> map)
```
    Deprecated. since 0.0.12 use the versions that explicitly specify View.Type
    
    Create a new CopyOnWriteMap with the supplied Map to initialize the values.
    
    Parameters:
    
    map - the initial map to initialize with
  - CopyOnWriteMap
```
@Deprecated
protected CopyOnWriteMap()
```
    Deprecated. since 0.0.12 use the versions that explicitly specify View.Type
    
    Create a new empty CopyOnWriteMap.
  - CopyOnWriteMap
```
protected CopyOnWriteMap(Map<? extends K,? extends V> map,
                         AbstractCopyOnWriteMap.View.Type viewType)
```
    Create a new CopyOnWriteMap with the supplied Map to initialize the values. This map may be optionally modified using any of the key, entry or value views
    
    Parameters:
    
    map - the initial map to initialize with
    
    viewType - a View.Type.
  - CopyOnWriteMap
```
protected CopyOnWriteMap(AbstractCopyOnWriteMap.View.Type viewType)
```
    Create a new empty CopyOnWriteMap. This map may be optionally modified using any of the key, entry or value views
    
    Parameters:
    
    viewType - a View.Type.
- Method Detail
  - builder
```
public static <K,V> CopyOnWriteMap.Builder<K,V> builder()
```
    Get a CopyOnWriteMap.Builder for a CopyOnWriteMap instance.
    
    Type Parameters:
    
    K - key type
    
    V - value type
    
    Returns:
    
    a fresh builder
  - newHashMap
```
public static <K,V> CopyOnWriteMap<K,V> newHashMap()
```
    Creates a new CopyOnWriteMap with an underlying HashMap.
    This map has stable views.
    
    Returns:
    
    a CopyOnWriteMap.
  - newHashMap
```
public static <K,V> CopyOnWriteMap<K,V> newHashMap(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.
    
    Parameters:
    
    map - a Map object.
    
    Returns:
    
    a CopyOnWriteMap.
  - newLinkedMap
```
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.
    
    Returns:
    
    a CopyOnWriteMap.
  - newLinkedMap
```
public static <K,V> CopyOnWriteMap<K,V> newLinkedMap(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.
    
    Parameters:
    
    map - a Map object.
    
    Returns:
    
    a CopyOnWriteMap.
  - copy
```
protected abstract <N extends Map<? extends K,? extends V>> Map<K,V> copy(N map)
```
    Copy function, implemented by sub-classes.
    
    Type Parameters:
    
    N - the map to copy and return.
    
    Parameters:
    
    map - the initial values of the newly created map.
    
    Returns:
    
    a new map. Will never be modified after construction.
  - clear
```
public final void clear()
```
    Return a new copy containing no elements
    
    Specified by:
    
    clear in interface Map<K,V>
  - remove
```
public final V remove(Object key)
```
    Specified by:
    
    remove in interface Map<K,V>
  - remove
```
public final boolean remove(Object key,
                            Object value)
```
    Specified by:
    
    remove in interface ConcurrentMap<K,V>
    
    Specified by:
    
    remove in interface Map<K,V>
  - replace
```
public final boolean replace(K key,
                             V oldValue,
                             V newValue)
```
    Attempt to replace the value of the key with newValues so long as the key is still associated with old value
    
    Specified by:
    
    replace in interface ConcurrentMap<K,V>
    
    Specified by:
    
    replace in interface Map<K,V>
    
    Parameters:
    
    key - a K key to to define a new association for.
    
    oldValue - if this value is still present replace it with newValue.
    
    newValue - a V to add to the map.
    
    Returns:
    
    a boolean if the replacement is successful
  - replace
```
public final V replace(K key,
                       V value)
```
    Replace the value of the key if the key is present returning the value.
    
    Specified by:
    
    replace in interface ConcurrentMap<K,V>
    
    Specified by:
    
    replace in interface Map<K,V>
    
    Parameters:
    
    key - a K key.
    
    value - a V value.
    
    Returns:
    
    a V if the key is present or null if it is not.
  - put
```
public final V put(K key,
                   V value)
```
    Add this key and its value to the map
    
    Specified by:
    
    put in interface Map<K,V>
    
    Parameters:
    
    key - a K key.
    
    value - a V value.
    
    Returns:
    
    a V value added.
  - putIfAbsent
```
public final V putIfAbsent(K key,
                           V value)
```
    If the key is not currently contained in the map add it. Returns the current value associated with the key whether or not the put succeeds.
    
    Specified by:
    
    putIfAbsent in interface ConcurrentMap<K,V>
    
    Specified by:
    
    putIfAbsent in interface Map<K,V>
    
    Parameters:
    
    key - a K key.
    
    value - a V value.
    
    Returns:
    
    a V associated with the key, may or may not be the input value to this method.
  - putAll
```
public final void putAll(Map<? extends K,? extends V> t)
```
    Specified by:
    
    putAll in interface Map<K,V>
  - copy
```
protected M copy()
```
    Create a copy of the underlying map.
    
    Returns:
    
    a M map.
  - set
```
protected final void set(M map)
```
    Set the contained map
    
    Parameters:
    
    map - a M contained by this class.
  - entrySet
```
public final Set<Map.Entry<K,V>> entrySet()
```
    Specified by:
    
    entrySet in interface Map<K,V>
  - keySet
```
public final Set<K> keySet()
```
    Specified by:
    
    keySet in interface Map<K,V>
  - values
```
public final Collection<V> values()
```
    Specified by:
    
    values in interface Map<K,V>
  - containsKey
```
public final boolean containsKey(Object key)
```
    Specified by:
    
    containsKey in interface Map<K,V>
  - containsValue
```
public final boolean containsValue(Object value)
```
    Specified by:
    
    containsValue in interface Map<K,V>
  - get
```
public final V get(Object key)
```
    Specified by:
    
    get in interface Map<K,V>
  - isEmpty
```
public final boolean isEmpty()
```
    Specified by:
    
    isEmpty in interface Map<K,V>
  - size
```
public final int size()
```
    Specified by:
    
    size in interface Map<K,V>
  - equals
```
public final boolean equals(Object o)
```
    Specified by:
    
    equals in interface Map<K,V>
    
    Overrides:
    
    equals in class Object
  - hashCode
```
public final int hashCode()
```
    Specified by:
    
    hashCode in interface Map<K,V>
    
    Overrides:
    
    hashCode in class Object
  - getDelegate
```
protected final M getDelegate()
```
    Return the internal delegate map.
    
    Returns:
    
    a M map.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class CopyOnWriteMap<K,V>

Nested Class Summary

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

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.concurrent.ConcurrentMap

Constructor Detail

CopyOnWriteMap

CopyOnWriteMap

CopyOnWriteMap

CopyOnWriteMap

Method Detail

builder

newHashMap

newHashMap

newLinkedMap

newLinkedMap

copy

clear

remove

remove

replace

replace

put

putIfAbsent

putAll

copy

set

entrySet

keySet

values

containsKey

containsValue

get

isEmpty

size

equals

hashCode

getDelegate

toString