com.atlassian.util.concurrent
Class CopyOnWriteMap<K,V>

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

Type Parameters:

K - the key type

V - the value type

All Implemented Interfaces:

java.io.Serializable, java.util.concurrent.ConcurrentMap<K,V>, java.util.Map<K,V>

@ThreadSafe
public abstract class CopyOnWriteMap<K,V>
extends java.lang.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 CopyOnWriteMaps 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

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

java.util.Map.Entry<K,V>

Constructor Summary

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.

Method Summary

static <K,V> CopyOnWriteMap.Builder<K,V>	builder() Get a CopyOnWriteMap.Builder for a CopyOnWriteMap instance.
void	clear()
boolean	containsKey(java.lang.Object key)
boolean	containsValue(java.lang.Object value)
protected M	copy()
protected abstract <N extends java.util.Map<? extends K,? extends V>> java.util.Map<K,V>	copy(N map) Copy function, implemented by sub-classes.
java.util.Set<java.util.Map.Entry<K,V>>	entrySet()
boolean	equals(java.lang.Object o)
V	get(java.lang.Object key)
protected M	getDelegate()
int	hashCode()
boolean	isEmpty()
java.util.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(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.
V	put(K key, V value)
void	putAll(java.util.Map<? extends K,? extends V> t)
V	putIfAbsent(K key, V value)
V	remove(java.lang.Object key)
boolean	remove(java.lang.Object key, java.lang.Object value)
V	replace(K key, V value)
boolean	replace(K key, V oldValue, V newValue)
protected void	set(M map)
int	size()
java.lang.String	toString()
java.util.Collection<V>	values()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

CopyOnWriteMap

@Deprecated
protected CopyOnWriteMap(java.util.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(java.util.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

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

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.

newHashMap

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.

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.

newLinkedMap

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.

copy

protected abstract <N extends java.util.Map<? extends K,? extends V>> java.util.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()

Specified by:

clear in interface java.util.Map<K,V>

remove

public final V remove(java.lang.Object key)

Specified by:

remove in interface java.util.Map<K,V>

remove

public boolean remove(java.lang.Object key,
                      java.lang.Object value)

Specified by:

remove in interface java.util.concurrent.ConcurrentMap<K,V>

replace

public boolean replace(K key,
                       V oldValue,
                       V newValue)

Specified by:

replace in interface java.util.concurrent.ConcurrentMap<K,V>

replace

public V replace(K key,
                 V value)

Specified by:

replace in interface java.util.concurrent.ConcurrentMap<K,V>

put

public final V put(K key,
                   V value)

Specified by:

put in interface java.util.Map<K,V>

putIfAbsent

public V putIfAbsent(K key,
                     V value)

Specified by:

putIfAbsent in interface java.util.concurrent.ConcurrentMap<K,V>

putAll

public final void putAll(java.util.Map<? extends K,? extends V> t)

Specified by:

putAll in interface java.util.Map<K,V>

copy

protected M copy()

set

protected void set(M map)

entrySet

public final java.util.Set<java.util.Map.Entry<K,V>> entrySet()

Specified by:

entrySet in interface java.util.Map<K,V>

keySet

public final java.util.Set<K> keySet()

Specified by:

keySet in interface java.util.Map<K,V>

values

public final java.util.Collection<V> values()

Specified by:

values in interface java.util.Map<K,V>

containsKey

public final boolean containsKey(java.lang.Object key)

Specified by:

containsKey in interface java.util.Map<K,V>

containsValue

public final boolean containsValue(java.lang.Object value)

Specified by:

containsValue in interface java.util.Map<K,V>

get

public final V get(java.lang.Object key)

Specified by:

get in interface java.util.Map<K,V>

isEmpty

public final boolean isEmpty()

Specified by:

isEmpty in interface java.util.Map<K,V>

size

public final int size()

Specified by:

size in interface java.util.Map<K,V>

equals

public final boolean equals(java.lang.Object o)

Specified by:

equals in interface java.util.Map<K,V>

Overrides:

equals in class java.lang.Object

hashCode

public final int hashCode()

Specified by:

hashCode in interface java.util.Map<K,V>

Overrides:

hashCode in class java.lang.Object

getDelegate

protected final M getDelegate()

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object