⇒ Index (Frames) |  ⇒ Index (No Frames) |  ⇒ Package |  ⇒ Package Tree |  ⇒ Full Tree 
org.apache.commons.collections

Class SetUtils

java.lang.Object
|
+--org.apache.commons.collections.SetUtils


public class SetUtils
extends java.lang.Object

Provides utility methods and decorators for Set and SortedSet instances.
Since:
Commons Collections 2.1
Authors:
Paul Jack
Stephen Colebourne
Neil O'Toole
Matthew Hawthorne

Field Summary

static Set

EMPTY_SET

An empty unmodifiable set.

static SortedSet

EMPTY_SORTED_SET

An empty unmodifiable sorted set.

Constructor Summary

SetUtils()

SetUtils should not normally be instantiated.

Method Summary

static int

hashCodeForSet(final Collection set)

Generates a hash code using the algorithm specified in java.util.Set#hashCode().

static boolean

isEqualSet(final Collection set1, final Collection set2)

Tests two sets for equality as per the equals() contract in java.util.Set#equals(java.lang.Object).

static Set

orderedSet(Set set)

Returns a set that maintains the order of elements that are added backed by the given set.

static Set

predicatedSet(Set set, Predicate predicate)

Returns a predicated set backed by the given set.

static SortedSet

predicatedSortedSet(SortedSet set, Predicate predicate)

Returns a predicated sorted set backed by the given sorted set.

static Set

synchronizedSet(Set set)

Returns a synchronized set backed by the given set.

static SortedSet

synchronizedSortedSet(SortedSet set)

Returns a synchronized sorted set backed by the given sorted set.

static Set

transformedSet(Set set, Transformer transformer)

Returns a transformed set backed by the given set.

static SortedSet

transformedSortedSet(SortedSet set, Transformer transformer)

Returns a transformed sorted set backed by the given set.

static Set

typedSet(Set set, Class type)

Returns a typed set backed by the given set.

static SortedSet

typedSortedSet(SortedSet set, Class type)

Returns a typed sorted set backed by the given set.

static Set

unmodifiableSet(Set set)

Returns an unmodifiable set backed by the given set.

static SortedSet

unmodifiableSortedSet(SortedSet set)

Returns an unmodifiable sorted set backed by the given sorted set.

Field Details

EMPTY_SET

public static final Set EMPTY_SET

An empty unmodifiable set. This uses the Collections implementation and is provided for completeness.


EMPTY_SORTED_SET

public static final SortedSet EMPTY_SORTED_SET

An empty unmodifiable sorted set. This is not provided in the JDK.

Constructor Details

SetUtils

public SetUtils()

SetUtils should not normally be instantiated.

Method Details

hashCodeForSet

public static int hashCodeForSet(final Collection set)

Generates a hash code using the algorithm specified in java.util.Set.hashCode().

This method is useful for implementing Set when you cannot extend AbstractSet. The method takes Collection instances to enable other collection types to use the Set implementation algorithm.

Parameters:
set - the set to calculate the hash code for, may be null
Returns:
the hash code
See Also:
java.util.Set.hashCode()

isEqualSet

public static boolean isEqualSet(final Collection set1, final Collection set2)

Tests two sets for equality as per the equals() contract in java.util.Set.equals(java.lang.Object).

This method is useful for implementing Set when you cannot extend AbstractSet. The method takes Collection instances to enable other collection types to use the Set implementation algorithm.

The relevant text (slightly paraphrased as this is a static method) is:

Two sets are considered equal if they have the same size, and every member of the first set is contained in the second. This ensures that the equals method works properly across different implementations of the Set interface.

This implementation first checks if the two sets are the same object: if so it returns true. Then, it checks if the two sets are identical in size; if not, it returns false. If so, it returns a.containsAll((Collection) b).

Parameters:
set1 - the first set, may be null
set2 - the second set, may be null
Returns:
whether the sets are equal by value comparison
See Also:
java.util.Set

orderedSet

public static Set orderedSet(Set set)

Returns a set that maintains the order of elements that are added backed by the given set.

If an element is added twice, the order is determined by the first add. The order is observed through the iterator or toArray.

Parameters:
set - the set to order, must not be null
Returns:
an ordered set backed by the given set
Throws:
- if the Set is null

predicatedSet

public static Set predicatedSet(Set set, Predicate predicate)

Returns a predicated set backed by the given set. Only objects that pass the test in the given predicate can be added to the set. It is important not to use the original set after invoking this method, as it is a backdoor for adding unvalidated objects.

Parameters:
set - the set to predicate, must not be null
predicate - the predicate for the set, must not be null
Returns:
a predicated set backed by the given set
Throws:
- if the Set or Predicate is null

predicatedSortedSet

public static SortedSet predicatedSortedSet(SortedSet set, Predicate predicate)

Returns a predicated sorted set backed by the given sorted set. Only objects that pass the test in the given predicate can be added to the sorted set. It is important not to use the original sorted set after invoking this method, as it is a backdoor for adding unvalidated objects.

Parameters:
set - the sorted set to predicate, must not be null
predicate - the predicate for the sorted set, must not be null
Returns:
a predicated sorted set backed by the given sorted set
Throws:
- if the Set or Predicate is null

synchronizedSet

public static Set synchronizedSet(Set set)

Returns a synchronized set backed by the given set.

You must manually synchronize on the returned buffer's iterator to avoid non-deterministic behavior:

 Set s = SetUtils.synchronizedSet(mySet);
 synchronized (s) {
     Iterator i = s.iterator();
     while (i.hasNext()) {
         process (i.next());
     }
 }
This method uses the implementation in the decorators subpackage.

Parameters:
set - the set to synchronize, must not be null
Returns:
a synchronized set backed by the given set
Throws:
- if the set is null

synchronizedSortedSet

public static SortedSet synchronizedSortedSet(SortedSet set)

Returns a synchronized sorted set backed by the given sorted set.

You must manually synchronize on the returned buffer's iterator to avoid non-deterministic behavior:

 Set s = SetUtils.synchronizedSet(mySet);
 synchronized (s) {
     Iterator i = s.iterator();
     while (i.hasNext()) {
         process (i.next());
     }
 }
This method uses the implementation in the decorators subpackage.

Parameters:
set - the sorted set to synchronize, must not be null
Returns:
a synchronized set backed by the given set
Throws:
- if the set is null

transformedSet

public static Set transformedSet(Set set, Transformer transformer)

Returns a transformed set backed by the given set.

Each object is passed through the transformer as it is added to the Set. It is important not to use the original set after invoking this method, as it is a backdoor for adding untransformed objects.

Parameters:
set - the set to transform, must not be null
transformer - the transformer for the set, must not be null
Returns:
a transformed set backed by the given set
Throws:
- if the Set or Transformer is null

transformedSortedSet

public static SortedSet transformedSortedSet(SortedSet set, Transformer transformer)

Returns a transformed sorted set backed by the given set.

Each object is passed through the transformer as it is added to the Set. It is important not to use the original set after invoking this method, as it is a backdoor for adding untransformed objects.

Parameters:
set - the set to transform, must not be null
transformer - the transformer for the set, must not be null
Returns:
a transformed set backed by the given set
Throws:
- if the Set or Transformer is null

typedSet

public static Set typedSet(Set set, Class type)

Returns a typed set backed by the given set.

Only objects of the specified type can be added to the set.

Parameters:
set - the set to limit to a specific type, must not be null
type - the type of objects which may be added to the set
Returns:
a typed set backed by the specified set

typedSortedSet

public static SortedSet typedSortedSet(SortedSet set, Class type)

Returns a typed sorted set backed by the given set.

Only objects of the specified type can be added to the set.

Parameters:
set - the set to limit to a specific type, must not be null
type - the type of objects which may be added to the set
Returns:
a typed set backed by the specified set

unmodifiableSet

public static Set unmodifiableSet(Set set)

Returns an unmodifiable set backed by the given set.

This method uses the implementation in the decorators subpackage.

Parameters:
set - the set to make unmodifiable, must not be null
Returns:
an unmodifiable set backed by the given set
Throws:
- if the set is null

unmodifiableSortedSet

public static SortedSet unmodifiableSortedSet(SortedSet set)

Returns an unmodifiable sorted set backed by the given sorted set.

This method uses the implementation in the decorators subpackage.

Parameters:
set - the sorted set to make unmodifiable, must not be null
Returns:
an unmodifiable set backed by the given set
Throws:
- if the set is null