org.apache.commons.collections4

Class MultiSetUtils

java.lang.Object

org.apache.commons.collections4.MultiSetUtils

public class MultiSetUtils
extends java.lang.Object

Provides utility methods and decorators for MultiSet instances.

Since:

4.1

Field Summary

Fields

Modifier and Type	Field and Description
static MultiSet	EMPTY_MULTISET An empty unmodifiable multiset.

Method Summary

Modifier and Type	Method and Description
static <E> MultiSet<E>	emptyMultiSet() Get an empty MultiSet.
static <E> MultiSet<E>	predicatedMultiSet(MultiSet<E> multiset, Predicate<? super E> predicate) Returns a predicated (validating) multiset backed by the given multiset.
static <E> MultiSet<E>	synchronizedMultiSet(MultiSet<E> multiset) Returns a synchronized (thread-safe) multiset backed by the given multiset.
static <E> MultiSet<E>	unmodifiableMultiSet(MultiSet<? extends E> multiset) Returns an unmodifiable view of the given multiset.

Methods inherited from class java.lang.Object

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

Field Detail

EMPTY_MULTISET

public static final MultiSet EMPTY_MULTISET

An empty unmodifiable multiset.

Method Detail

synchronizedMultiSet

public static <E> MultiSet<E> synchronizedMultiSet(MultiSet<E> multiset)

Returns a synchronized (thread-safe) multiset backed by the given multiset. In order to guarantee serial access, it is critical that all access to the backing multiset is accomplished through the returned multiset.

It is imperative that the user manually synchronize on the returned multiset when iterating over it:

 MultiSet multiset = MultiSetUtils.synchronizedMultiSet(new HashMultiSet());
 ...
 synchronized(multiset) {
     Iterator i = multiset.iterator(); // Must be in synchronized block
     while (i.hasNext())
         foo(i.next());
     }
 }
 

Failure to follow this advice may result in non-deterministic behavior.

Type Parameters:

E - the element type

Parameters:

multiset - the multiset to synchronize, must not be null

Returns:

a synchronized multiset backed by that multiset

Throws:

java.lang.NullPointerException - if the MultiSet is null

unmodifiableMultiSet

public static <E> MultiSet<E> unmodifiableMultiSet(MultiSet<? extends E> multiset)

Returns an unmodifiable view of the given multiset. Any modification attempts to the returned multiset will raise an UnsupportedOperationException.

Type Parameters:

E - the element type

Parameters:

multiset - the multiset whose unmodifiable view is to be returned, must not be null

Returns:

an unmodifiable view of that multiset

Throws:

java.lang.NullPointerException - if the MultiSet is null

predicatedMultiSet

public static <E> MultiSet<E> predicatedMultiSet(MultiSet<E> multiset,
                                                 Predicate<? super E> predicate)

Returns a predicated (validating) multiset backed by the given multiset.

Only objects that pass the test in the given predicate can be added to the multiset. Trying to add an invalid object results in an IllegalArgumentException. It is important not to use the original multiset after invoking this method, as it is a backdoor for adding invalid objects.

Type Parameters:

E - the element type

Parameters:

multiset - the multiset to predicate, must not be null

predicate - the predicate for the multiset, must not be null

Returns:

a predicated multiset backed by the given multiset

Throws:

java.lang.NullPointerException - if the MultiSet or Predicate is null

emptyMultiSet

public static <E> MultiSet<E> emptyMultiSet()

Get an empty MultiSet.

Type Parameters:

E - the element type

Returns:

an empty MultiSet