## org.apache.commons.collections
Class BagUtils

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

    public class BagUtils

extends java.lang.Object

Provides utility methods and decorators for `Bag` and `SortedBag` instances.

Since:
  Commons Collections 2.1
Version:
  $Revision: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $
Author:
  Paul Jack, Stephen Colebourne, Andrew Freeman, Matthew Hawthorne

Field Summary
`static Bag` `EMPTY_BAG` An empty unmodifiable bag.
`static Bag` `EMPTY_SORTED_BAG` An empty unmodifiable sorted bag.

Constructor Summary
`BagUtils()` Instantiation of BagUtils is not intended or required.

Method Summary
`static Bag` `predicatedBag(Bag bag, Predicate predicate)` Returns a predicated (validating) bag backed by the given bag.
`static SortedBag` `predicatedSortedBag(SortedBag bag, Predicate predicate)` Returns a predicated (validating) sorted bag backed by the given sorted bag.
`static Bag` `synchronizedBag(Bag bag)` Returns a synchronized (thread-safe) bag backed by the given bag.
`static SortedBag` `synchronizedSortedBag(SortedBag bag)` Returns a synchronized (thread-safe) sorted bag backed by the given sorted bag.
`static Bag` `transformedBag(Bag bag, Transformer transformer)` Returns a transformed bag backed by the given bag.
`static SortedBag` `transformedSortedBag(SortedBag bag, Transformer transformer)` Returns a transformed sorted bag backed by the given bag.
`static Bag` `typedBag(Bag bag, java.lang.Class type)` Returns a typed bag backed by the given bag.
`static SortedBag` `typedSortedBag(SortedBag bag, java.lang.Class type)` Returns a typed sorted bag backed by the given bag.
`static Bag` `unmodifiableBag(Bag bag)` Returns an unmodifiable view of the given bag.
`static SortedBag` `unmodifiableSortedBag(SortedBag 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 Detail

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

Constructor Detail

### BagUtils

    public BagUtils()

  Instantiation of BagUtils is not intended or required. However, some tools require an instance to operate.

Method Detail

### synchronizedBag

    public static Bag synchronizedBag(Bag 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.

  Parameters:
    `bag` - the bag to synchronize, must not be null
  Returns:
    a synchronized bag backed by that bag
  Throws:
    `java.lang.IllegalArgumentException` - if the Bag is null

### unmodifiableBag

    public static Bag unmodifiableBag(Bag bag)

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

  Parameters:
    `bag` - the bag whose unmodifiable view is to be returned, must not be null
  Returns:
    an unmodifiable view of that bag
  Throws:
    `java.lang.IllegalArgumentException` - if the Bag is null

### predicatedBag

    public static Bag predicatedBag(Bag bag,
                                    Predicate 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.

  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:
    `java.lang.IllegalArgumentException` - if the Bag or Predicate is null

### typedBag

    public static Bag typedBag(Bag bag,
                               java.lang.Class type)

  Returns a typed bag backed by the given bag.

  Only objects of the specified type can be added to the bag.

  Parameters:
    `bag` - the bag to limit to a specific type, must not be null
    `type` - the type of objects which may be added to the bag
  Returns:
    a typed bag backed by the specified bag

### transformedBag

    public static Bag transformedBag(Bag bag,
                                     Transformer 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.

  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:
    `java.lang.IllegalArgumentException` - if the Bag or Transformer is null

### synchronizedSortedBag

    public static SortedBag synchronizedSortedBag(SortedBag 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.

  Parameters:
    `bag` - the bag to synchronize, must not be null
  Returns:
    a synchronized bag backed by that bag
  Throws:
    `java.lang.IllegalArgumentException` - if the SortedBag is null

### unmodifiableSortedBag

    public static SortedBag unmodifiableSortedBag(SortedBag bag)

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

  Parameters:
    `bag` - the bag whose unmodifiable view is to be returned, must not be null
  Returns:
    an unmodifiable view of that bag
  Throws:
    `java.lang.IllegalArgumentException` - if the SortedBag is null

### predicatedSortedBag

    public static SortedBag predicatedSortedBag(SortedBag bag,
                                                Predicate 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.

  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:
    `java.lang.IllegalArgumentException` - if the SortedBag or Predicate is null

### typedSortedBag

    public static SortedBag typedSortedBag(SortedBag bag,
                                           java.lang.Class type)

  Returns a typed sorted bag backed by the given bag.

  Only objects of the specified type can be added to the bag.

  Parameters:
    `bag` - the bag to limit to a specific type, must not be null
    `type` - the type of objects which may be added to the bag
  Returns:
    a typed bag backed by the specified bag

### transformedSortedBag

    public static SortedBag transformedSortedBag(SortedBag bag,
                                                 Transformer 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.

  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:
    `java.lang.IllegalArgumentException` - if the Bag or Transformer is null

Copyright © 2001-2008 The Apache Software Foundation. All Rights Reserved.