Package org.apache.commons.collections4

Class MultiSetUtils

java.lang.Object

org.apache.commons.collections4.MultiSetUtils

public class MultiSetUtils
extends Object

Provides utility methods and decorators for MultiSet instances.

Since:

4.1

Field Summary

Fields

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

Method Summary

Modifier and Type	Method	Description
static <E> MultiSet<E>	emptyMultiSet()	Gets 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

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

Field Details

EMPTY_MULTISET

public static final MultiSet EMPTY_MULTISET

An empty unmodifiable multiset.

Method Details

emptyMultiSet

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

Gets an empty MultiSet.

Type Parameters:

E - the element type

Returns:

an empty MultiSet

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:

NullPointerException - if the MultiSet or Predicate is null

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:

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:

NullPointerException - if the MultiSet is null