# 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