org.apache.commons.collections4
Class BagUtils

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

public class BagUtils
extends Object

Provides utility methods and decorators for Bag and SortedBag instances.

Since:
2.1
Version:
$Id: BagUtils.java 1493938 2013-06-17 21:06:00Z tn $

Field Summary
static Bag<Object> EMPTY_BAG
          An empty unmodifiable bag.
static Bag<Object> EMPTY_SORTED_BAG
          An empty unmodifiable sorted bag.
 
Method Summary
static
<E> Bag<E>
compliantBag(Bag<E> bag)
          Returns a bag that complies to the Collection contract, backed by the given bag.
static
<E> Bag<E>
emptyBag()
          Get an empty Bag.
static
<E> SortedBag<E>
emptySortedBag()
          Get 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<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 Detail

EMPTY_BAG

public static final Bag<Object> EMPTY_BAG
An empty unmodifiable bag.


EMPTY_SORTED_BAG

public static final Bag<Object> EMPTY_SORTED_BAG
An empty unmodifiable sorted bag.

Method Detail

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:
IllegalArgumentException - if the Bag is null

unmodifiableBag

public static <E> Bag<E> unmodifiableBag(Bag<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:
IllegalArgumentException - if the Bag is null

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:
IllegalArgumentException - if the Bag or Predicate 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 behaviour, 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:
IllegalArgumentException - if the Bag or Transformer is null

compliantBag

public static <E> Bag<E> compliantBag(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:
IllegalArgumentException - if bag is null
Since:
4.0

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:
IllegalArgumentException - if the SortedBag 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:
IllegalArgumentException - if the SortedBag 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:
IllegalArgumentException - if the SortedBag or Predicate 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 behaviour, 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:
IllegalArgumentException - if the Bag or Transformer is null

emptyBag

public static <E> Bag<E> emptyBag()
Get an empty Bag.

Type Parameters:
E - the element type
Returns:
an empty Bag

emptySortedBag

public static <E> SortedBag<E> emptySortedBag()
Get an empty SortedBag.

Type Parameters:
E - the element type
Returns:
an empty sorted Bag


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