java.util
Class Collections

java.lang.Object
  java.util.Collections

public class Collections
extends Object

Utility class consisting of static methods that operate on, or return Collections. Contains methods to sort, search, reverse, fill and shuffle Collections, methods to facilitate interoperability with legacy APIs that are unaware of collections, a method to return a list which consists of multiple copies of one element, and methods which "wrap" collections to give them extra properties, such as thread-safety and unmodifiability.

All methods which take a collection throw a NullPointerException if that collection is null. Algorithms which can change a collection may, but are not required, to throw the UnsupportedOperationException that the underlying collection would throw during an attempt at modification. For example, Collections.singleton("").addAll(Collections.EMPTY_SET) does not throw a exception, even though addAll is an unsupported operation on a singleton; the reason for this is that addAll did not attempt to modify the set.

Since:

1.2

See Also:

Collection, Set, List, Map, Arrays

Method Summary

static Enumeration	enumeration(Collection c) Returns an Enumeration over a collection.
static Collection	synchronizedCollection(Collection c) Returns a synchronized (thread-safe) collection wrapper backed by the given collection.
static List	synchronizedList(List l) Returns a synchronized (thread-safe) list wrapper backed by the given list.
static Map	synchronizedMap(Map m) Returns a synchronized (thread-safe) map wrapper backed by the given map.
static Set	synchronizedSet(Set s) Returns a synchronized (thread-safe) set wrapper backed by the given set.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

enumeration

public static Enumeration enumeration(Collection c)

Returns an Enumeration over a collection. This allows interoperability with legacy APIs that require an Enumeration as input.

Parameters:

c - the Collection to iterate over

Returns:

an Enumeration backed by an Iterator over c

synchronizedCollection

public static Collection synchronizedCollection(Collection c)

Returns a synchronized (thread-safe) collection wrapper backed by the given collection. Notice that element access through the iterators is thread-safe, but if the collection can be structurally modified (adding or removing elements) then you should synchronize around the iteration to avoid non-deterministic behavior:

 Collection c = Collections.synchronizedCollection(new Collection(...));
 ...
 synchronized (c)
   {
     Iterator i = c.iterator();
     while (i.hasNext())
       foo(i.next());
   }
 

Since the collection might be a List or a Set, and those have incompatible equals and hashCode requirements, this relies on Object's implementation rather than passing those calls on to the wrapped collection. The returned Collection implements Serializable, but can only be serialized if the collection it wraps is likewise Serializable.

Parameters:

c - the collection to wrap

Returns:

a synchronized view of the collection

See Also:

Serializable

synchronizedList

public static List synchronizedList(List l)

Returns a synchronized (thread-safe) list wrapper backed by the given list. Notice that element access through the iterators is thread-safe, but if the list can be structurally modified (adding or removing elements) then you should synchronize around the iteration to avoid non-deterministic behavior:

 List l = Collections.synchronizedList(new List(...));
 ...
 synchronized (l)
   {
     Iterator i = l.iterator();
     while (i.hasNext())
       foo(i.next());
   }
 

The returned List implements Serializable, but can only be serialized if the list it wraps is likewise Serializable. In addition, if the wrapped list implements RandomAccess, this does too.

Parameters:

l - the list to wrap

Returns:

a synchronized view of the list

See Also:

Serializable, RandomAccess

synchronizedMap

public static Map synchronizedMap(Map m)

Returns a synchronized (thread-safe) map wrapper backed by the given map. Notice that element access through the collection views and their iterators are thread-safe, but if the map can be structurally modified (adding or removing elements) then you should synchronize around the iteration to avoid non-deterministic behavior:

 Map m = Collections.synchronizedMap(new Map(...));
 ...
 Set s = m.keySet(); // safe outside a synchronized block
 synchronized (m) // synch on m, not s
   {
     Iterator i = s.iterator();
     while (i.hasNext())
       foo(i.next());
   }
 

The returned Map implements Serializable, but can only be serialized if the map it wraps is likewise Serializable.

Parameters:

m - the map to wrap

Returns:

a synchronized view of the map

See Also:

Serializable

synchronizedSet

public static Set synchronizedSet(Set s)

Returns a synchronized (thread-safe) set wrapper backed by the given set. Notice that element access through the iterator is thread-safe, but if the set can be structurally modified (adding or removing elements) then you should synchronize around the iteration to avoid non-deterministic behavior:

 Set s = Collections.synchronizedSet(new Set(...));
 ...
 synchronized (s)
   {
     Iterator i = s.iterator();
     while (i.hasNext())
       foo(i.next());
   }
 

The returned Set implements Serializable, but can only be serialized if the set it wraps is likewise Serializable.

Parameters:

s - the set to wrap

Returns:

a synchronized view of the set

See Also:

Serializable