Package org.apache.commons.collections4

# Class BagUtils

java.lang.Object
org.apache.commons.collections4.BagUtils

public class BagUtils extends Object
Provides utility methods and decorators for `Bag` and `SortedBag` instances.

Since:
  2.1

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final Bag`
  `EMPTY_BAG`
  An empty unmodifiable bag.
  `static final Bag`
  `EMPTY_SORTED_BAG`
  An empty unmodifiable sorted bag.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <E> Bag<E>`
  `collectionBag(Bag<E> bag)`
  Returns a bag that complies to the Collection contract, backed by the given bag.
  `static <E> Bag<E>`
  `emptyBag()`
  Gets an empty `Bag`.
  `static <E> SortedBag<E>`
  `emptySortedBag()`
  Gets an empty `SortedBag`.
  `static <E> Bag<E>`
  `predicatedBag(Bag<E> bag, Predicate<? super E> predicate)`
  Returns a predicated (validating) bag backed by the given bag.
  `static <E> SortedBag<E>`
  `predicatedSortedBag(SortedBag<E> bag, Predicate<? super E> predicate)`
  Returns a predicated (validating) sorted bag backed by the given sorted bag.
  `static <E> Bag<E>`
  `synchronizedBag(Bag<E> bag)`
  Returns a synchronized (thread-safe) bag backed by the given bag.
  `static <E> SortedBag<E>`
  `synchronizedSortedBag(SortedBag<E> bag)`
  Returns a synchronized (thread-safe) sorted bag backed by the given sorted bag.
  `static <E> Bag<E>`
  `transformingBag(Bag<E> bag, Transformer<? super E,? extends E> transformer)`
  Returns a transformed bag backed by the given bag.
  `static <E> SortedBag<E>`
  `transformingSortedBag(SortedBag<E> bag, Transformer<? super E,? extends E> transformer)`
  Returns a transformed sorted bag backed by the given bag.
  `static <E> Bag<E>`
  `unmodifiableBag(Bag<? extends E> bag)`
  Returns an unmodifiable view of the given bag.
  `static <E> SortedBag<E>`
  `unmodifiableSortedBag(SortedBag<E> bag)`
  Returns an unmodifiable view of the given sorted bag.

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### EMPTY_BAG

    public static final Bag EMPTY_BAG
    An empty unmodifiable bag.

  - ### EMPTY_SORTED_BAG

    public static final Bag EMPTY_SORTED_BAG
    An empty unmodifiable sorted bag.

- ## Method Details

  - ### collectionBag

    public static <E> Bag<E> collectionBag(Bag<E> bag)
    Returns a bag that complies to the Collection contract, backed by the given bag.
    Type Parameters:
      `E` - the element type
    Parameters:
      `bag` - the bag to decorate, must not be null
    Returns:
      a Bag that complies to the Collection contract
    Throws:
      `NullPointerException` - if bag is null
    Since:
      4.0

  - ### emptyBag

    public static <E> Bag<E> emptyBag()
    Gets an empty `Bag`.
    Type Parameters:
      `E` - the element type
    Returns:
      an empty Bag

  - ### emptySortedBag

    public static <E> SortedBag<E> emptySortedBag()
    Gets an empty `SortedBag`.
    Type Parameters:
      `E` - the element type
    Returns:
      an empty sorted Bag

  - ### predicatedBag

    public static <E> Bag<E> predicatedBag(Bag<E> bag, Predicate<? super E> predicate)
    Returns a predicated (validating) bag backed by the given bag.

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

    Type Parameters:
      `E` - the element type
    Parameters:
      `bag` - the bag to predicate, must not be null
      `predicate` - the predicate for the bag, must not be null
    Returns:
      a predicated bag backed by the given bag
    Throws:
      `NullPointerException` - if the Bag or Predicate is null

  - ### predicatedSortedBag

    public static <E> SortedBag<E> predicatedSortedBag(SortedBag<E> bag, Predicate<? super E> predicate)
    Returns a predicated (validating) sorted bag backed by the given sorted bag.

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

    Type Parameters:
      `E` - the element type
    Parameters:
      `bag` - the sorted bag to predicate, must not be null
      `predicate` - the predicate for the bag, must not be null
    Returns:
      a predicated bag backed by the given bag
    Throws:
      `NullPointerException` - if the SortedBag or Predicate is null

  - ### synchronizedBag

    public static <E> Bag<E> synchronizedBag(Bag<E> bag)
    Returns a synchronized (thread-safe) bag backed by the given bag. In order to guarantee serial access, it is critical that all access to the backing bag is accomplished through the returned bag.

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

         Bag bag = BagUtils.synchronizedBag(new HashBag());
         ...
         synchronized(bag) {
             Iterator i = bag.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:
      `bag` - the bag to synchronize, must not be null
    Returns:
      a synchronized bag backed by that bag
    Throws:
      `NullPointerException` - if the Bag is null

  - ### synchronizedSortedBag

    public static <E> SortedBag<E> synchronizedSortedBag(SortedBag<E> bag)
    Returns a synchronized (thread-safe) sorted bag backed by the given sorted bag. In order to guarantee serial access, it is critical that all access to the backing bag is accomplished through the returned bag.

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

         SortedBag bag = BagUtils.synchronizedSortedBag(new TreeBag());
         ...
         synchronized(bag) {
             Iterator i = bag.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:
      `bag` - the bag to synchronize, must not be null
    Returns:
      a synchronized bag backed by that bag
    Throws:
      `NullPointerException` - if the SortedBag is null

  - ### transformingBag

    public static <E> Bag<E> transformingBag(Bag<E> bag, Transformer<? super E,? extends E> transformer)
    Returns a transformed bag backed by the given bag.

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

    Existing entries in the specified bag will not be transformed. If you want that behavior, see `TransformedBag.transformedBag(Bag, Transformer)`.

    Type Parameters:
      `E` - the element type
    Parameters:
      `bag` - the bag to predicate, must not be null
      `transformer` - the transformer for the bag, must not be null
    Returns:
      a transformed bag backed by the given bag
    Throws:
      `NullPointerException` - if the Bag or Transformer is null

  - ### transformingSortedBag

    public static <E> SortedBag<E> transformingSortedBag(SortedBag<E> bag, Transformer<? super E,? extends E> transformer)
    Returns a transformed sorted bag backed by the given bag.

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

    Existing entries in the specified bag will not be transformed. If you want that behavior, see `TransformedSortedBag.transformedSortedBag(SortedBag, Transformer)`.

    Type Parameters:
      `E` - the element type
    Parameters:
      `bag` - the bag to predicate, must not be null
      `transformer` - the transformer for the bag, must not be null
    Returns:
      a transformed bag backed by the given bag
    Throws:
      `NullPointerException` - if the Bag or Transformer is null

  - ### unmodifiableBag

    public static <E> Bag<E> unmodifiableBag(Bag<? extends E> bag)
    Returns an unmodifiable view of the given bag. Any modification attempts to the returned bag will raise an `UnsupportedOperationException`.
    Type Parameters:
      `E` - the element type
    Parameters:
      `bag` - the bag whose unmodifiable view is to be returned, must not be null
    Returns:
      an unmodifiable view of that bag
    Throws:
      `NullPointerException` - if the Bag is null

  - ### unmodifiableSortedBag

    public static <E> SortedBag<E> unmodifiableSortedBag(SortedBag<E> bag)
    Returns an unmodifiable view of the given sorted bag. Any modification attempts to the returned bag will raise an `UnsupportedOperationException`.
    Type Parameters:
      `E` - the element type
    Parameters:
      `bag` - the bag whose unmodifiable view is to be returned, must not be null
    Returns:
      an unmodifiable view of that bag
    Throws:
      `NullPointerException` - if the SortedBag is null