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
  Version:
    $Id: MultiSetUtils.java 1714424 2015-11-15 10:06:16Z tn $

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static MultiSet` | `EMPTY_MULTISET` An empty unmodifiable multiset.

  - ### Method Summary

    Methods
    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

      `clone, equals, finalize, 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:
        `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

    - #### 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

    - #### emptyMultiSet

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

      Get an empty `MultiSet`.
      Type Parameters:
        `E` - the element type
      Returns:
        an empty MultiSet

Copyright © 2001–2015 The Apache Software Foundation. All rights reserved.