java.util.concurrent.CopyOnWriteArraySet<E>
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();
}
}
Summary
Public Constructors
Public Methods
add,
addAll,
clear,
contains,
containsAll,
isEmpty,
iterator,
remove,
removeAll,
retainAll,
size,
toArray,
toArray,
toString
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
add,
addAll,
clear,
contains,
containsAll,
equals,
hashCode,
isEmpty,
iterator,
remove,
removeAll,
retainAll,
size,
toArray,
toArray
Methods inherited
from interface
java.util.Set
add,
addAll,
clear,
contains,
containsAll,
equals,
hashCode,
isEmpty,
iterator,
remove,
removeAll,
retainAll,
size,
toArray,
toArray
Details
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.
Public Methods
public
boolean
add(E o)
If the specified element is not contained within this collection, and
addition of this element succeeds, then true will be returned. If the
specified element is already contained within this collection, or
duplication is not permitted, false will be returned. Different
implementations may add specific limitations on this method to filter
permitted elements. For example, in some implementation, null element may
be denied, and NullPointerException will be thrown out. These limitations
should be explicitly documented by specific collection implementation.
Add operation is not supported in this implementation, and
UnsupportedOperationException will always be thrown out.
Parameters
o
| the element to be added. |
Returns
- true if the collection is changed successfully after invoking
this method. Otherwise, false.
public
boolean
addAll(Collection<? extends E> c)
Adds the objects in the specified Collection to this Collection.
Parameters
c
| the Collection of objects |
Returns
- true if this Collection is modified, false otherwise
public
void
clear()
Removes all the elements in this collection. This collection will be
cleared up after this operation. The operation iterates over the
collection, removes every element using Iterator.remove method.
UnsupportedOperationException will be thrown out if the iterator returned
by this collection does not implement the remove method and the collection
is not zero length.
public
boolean
contains(Object o)
Searches this Collection for the specified object.
Parameters
o
| the object to search for |
Returns
- true if
object
is an element of this Collection,
false otherwise
public
boolean
containsAll(Collection<?> c)
Searches this Collection for all objects in the specified Collection.
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 true if the collection has no element, otherwise false.
Returns
- true if the collection has no element.
public
Iterator<E>
iterator()
Returns an Iterator on the elements of this Collection. A subclass must
implement the abstract methods iterator() and size().
Returns
- an Iterator on the elements of this Collection
public
boolean
remove(Object o)
Removes the first occurrence of the specified object from this
Collection. This operation traverses over the collection, looking
for the specified object. Once the object is found, the object will
be removed from the collection using the iterator's remove method.
This collection will throw an UnsupportedOperationException if the
iterator returned does not implement remove method, and the specified
object is in this collection.
Returns
- true if this Collection is modified, false otherwise
public
boolean
removeAll(Collection<?> c)
Removes all occurrences in this Collection of each object in the
specified Collection.
Parameters
c
| the Collection of objects to remove |
Returns
- true if this Collection is modified, false otherwise
public
boolean
retainAll(Collection<?> c)
Removes all objects from this Collection that are not contained in the
specified Collection. This operation traverses over the collection
itself, to verify whether any element is contained in the specified
collection. The object will be removed from the collection itself using
the iterator's remove method if it is not contained in the specified
collection.
This collection will throw an UnsupportedOperationException if the
iterator returned does not implement remove method, and the collection
itself does contain elements which do not exist in the specified collection.
Parameters
c
| the Collection of objects to retain |
Returns
- true if this Collection is modified, false otherwise
public
int
size()
Returns the number of elements in this Collection.
Returns
- the number of 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.
Returns
- an array of the elements from this Collection
public
Object[]
toArray()
Returns a new array containing all elements contained in this Collection.
All the elements in the array will not be referenced by the collection.
The elements in the returned array will be sorted to the same order as
those returned by the iterator of this collection itself if the collection
guarantees the order.
Returns
- an array of the elements from this Collection