public class

CopyOnWriteArraySet

extends AbstractSet<E>
implements Serializable
java.lang.Object
   ↳ java.util.AbstractCollection<E>
     ↳ java.util.AbstractSet<E>
       ↳ java.util.concurrent.CopyOnWriteArraySet<E>

Class Overview

A Set that uses CopyOnWriteArrayList for all of its operations. Thus, it shares the same basic properties:

  • It is best suited for applications in which set sizes generally stay small, read-only operations vastly outnumber mutative operations, and you need to prevent interference among threads during traversal.
  • Mutative operations(add, set, remove, etc) are expensive since they usually entail copying the entire underlying array.
  • Iterators do not support the mutative remove operation
  • Traversal via iterators is very fast and cannot ever encounter interference from other threads. Iterators rely on unchanging snapshots of the array at the time the iterators were constructed.

Sample Usage. Probably the main application of copy-on-write sets are classes that maintain sets of Handler objects that must be multicasted to upon an update command. This is a classic case where you do not want to be holding a lock while sending a message, and where traversals normally vastly overwhelm additions. 

 class Handler { void handle(); ... }

 class X {
    private final CopyOnWriteArraySet<Handler> handlers = new CopyOnWriteArraySet<Handler>();
    public void addHandler(Handler h) { handlers.add(h); }

    private long internalState;
    private synchronized void changeState() { internalState = ...; }

    public void update() {
       changeState();
       Iterator it = handlers.iterator();
       while (it.hasNext())
          it.next().handle();
    }
 }

See Also

Summary

Public Constructors
CopyOnWriteArraySet()
Creates an empty set.
CopyOnWriteArraySet(Collection<? extends E> c)
Creates a set containing all of the elements of the specified Collection.
Public Methods
boolean add(E o)
Attempts to add object to the contents of this Collection (optional).
boolean addAll(Collection<? extends E> c)
Attempts to add all of the objects contained in collection to the contents of this Collection (optional).
void clear()
Removes all elements from this Collection, leaving it empty (optional).
boolean contains(Object o)
Tests whether this Collection contains the specified object.
boolean containsAll(Collection<?> c)
Tests whether this Collection contains all objects contained in the specified Collection.
boolean isEmpty()
Returns if this Collection contains no elements.
Iterator<E> iterator()
Returns an instance of Iterator that may be used to access the objects contained by this Collection.
boolean remove(Object o)
Removes one instance of the specified object from this Collection if one is contained (optional).
boolean removeAll(Collection<?> c)
Removes all occurrences in this collection which are contained in the specified collection.
boolean retainAll(Collection<?> c)
Removes all objects from this Collection that are not also found in the Collection passed (optional).
int size()
Returns a count of how many objects this Collection contains.
<T> T[] toArray(T[] a)
Returns an array containing all elements contained in this Collection.
Object[] toArray()
Returns a new array containing all elements contained in this Collection.
[Expand]
Inherited Methods
From class java.util.AbstractSet
From class java.util.AbstractCollection
From class java.lang.Object
From interface java.lang.Iterable
From interface java.util.Collection
From interface java.util.Set

Public Constructors

public CopyOnWriteArraySet ()

Creates an empty set.

public CopyOnWriteArraySet (Collection<? extends E> c)

Creates a set containing all of the elements of the specified Collection.

Parameters
c the collection

Public Methods

public boolean add (E o)

Attempts to add object to the contents of this Collection (optional). After this method finishes successfully it is guaranteed that the object is contained in the collection. If the collection was modified it returns true, false if no changes were made. An implementation of Collection may narrow the set of accepted objects, but it has to specify this in the documentation. If the object to be added does not meet this restriction, then an IllegalArgumentException is thrown. If a collection does not yet contain an object that is to be added and adding the object fails, this method must throw an appropriate unchecked Exception. Returning false is not permitted in this case because it would violate the postcondition that the element will be part of the collection after this method finishes.

Parameters
o the object to add.
Returns
  • true if this Collection is modified, false otherwise.

public boolean addAll (Collection<? extends E> c)

Attempts to add all of the objects contained in collection to the contents of this Collection (optional). This implementation iterates over the given Collection and calls add for each element. If any of these calls return true, then true is returned as result of this method call, false otherwise. If this Collection does not support adding elements, an UnsupportedOperationException is thrown.

If the passed Collection is changed during the process of adding elements to this Collection, the behavior depends on the behavior of the passed Collection.

Parameters
c the collection of objects.
Returns
  • true if this Collection is modified, false otherwise.

public void clear ()

Removes all elements from this Collection, leaving it empty (optional). This implementation iterates over this Collection and calls the remove method on each element. If the iterator does not support removal of elements, an UnsupportedOperationException is thrown.

Concrete implementations usually can clear a Collection more efficiently and should therefore overwrite this method.

public boolean contains (Object o)

Tests whether this Collection contains the specified object. This implementation iterates over this Collection and tests, whether any element is equal to the given object. If object != null then object.equals(e) is called for each element e returned by the iterator until the element is found. If object == null then each element e returned by the iterator is compared with the test e == null.

Parameters
o the object to search for.
Returns
  • true if object is an element of this Collection, false otherwise.

public boolean containsAll (Collection<?> c)

Tests whether this Collection contains all objects contained in the specified Collection. This implementation iterates over the specified Collection. If one element returned by the iterator is not contained in this Collection, then false is returned; true otherwise.

Parameters
c the collection of objects.
Returns
  • true if all objects in the specified Collection are elements of this Collection, false otherwise.

public boolean isEmpty ()

Returns if this Collection contains no elements. This implementation tests, whether size returns 0.

Returns
  • true if this Collection has no elements, false otherwise.

public Iterator<E> iterator ()

Returns an instance of Iterator that may be used to access the objects contained by this Collection. The order in which the elements are returned by the Iterator is not defined unless the instance of the Collection has a defined order. In that case, the elements are returned in that order.

In this class this method is declared abstract and has to be implemented by concrete Collection implementations.

Returns
  • an iterator for accessing the Collection contents.

public boolean remove (Object o)

Removes one instance of the specified object from this Collection if one is contained (optional). This implementation iterates over this Collection and tests for each element e returned by the iterator, whether e is equal to the given object. If object != null then this test is performed using object.equals(e), otherwise using object == null. If an element equal to the given object is found, then the remove method is called on the iterator and true is returned, false otherwise. If the iterator does not support removing elements, an UnsupportedOperationException is thrown.

Parameters
o the object to remove.
Returns
  • true if this Collection is modified, false otherwise.

public boolean removeAll (Collection<?> c)

Removes all occurrences in this collection which are contained in the specified collection.

Parameters
c the collection of objects to remove.
Returns
  • true if this collection was modified, false otherwise.

public boolean retainAll (Collection<?> c)

Removes all objects from this Collection that are not also found in the Collection passed (optional). After this method returns this Collection will only contain elements that also can be found in the Collection passed to this method.

This implementation iterates over this Collection and tests for each element e returned by the iterator, whether it is contained in the specified Collection. If this test is negative, then the remove method is called on the iterator. If the iterator does not support removing elements, an UnsupportedOperationException is thrown.

Parameters
c the collection of objects to retain.
Returns
  • true if this Collection is modified, false otherwise.

public int size ()

Returns a count of how many objects this Collection contains.

In this class this method is declared abstract and has to be implemented by concrete Collection implementations.

Returns
  • how many objects this Collection contains, or Integer.MAX_VALUE if there are more than Integer.MAX_VALUE elements in this Collection.

public T[] toArray (T[] a)

Returns an array containing all elements contained in this Collection. If the specified array is large enough to hold the elements, the specified array is used, otherwise an array of the same type is created. If the specified array is used and is larger than this Collection, the array element following the Collection elements is set to null. If the implementation has ordered elements it will return the element array in the same order as an iterator would return them. toArray(new Object[0]) behaves exactly the same way as toArray() does.

Parameters
a the array.
Returns
  • an array of the elements from this Collection.

public Object[] toArray ()

Returns a new array containing all elements contained in this Collection. If the implementation has ordered elements it will return the element array in the same order as an iterator would return them. The array returned does not reflect any changes of the Collection. A new array is created even if the underlying data structure is already an array.

Returns
  • an array of the elements from this Collection.