org.apache.commons.collections
Class BagUtils

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

public class BagUtils
extends Object

Provides utility methods and decorators for Bag and SortedBag instances.

Since:

Commons Collections 2.1

Version:

$Revision: 1.1.1.1 $ $Date: 2005/05/23 04:32:35 $

Author:

Paul Jack, Stephen Colebourne, Andrew Freeman, Matt Hall, John Watkinson, 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 <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 <I,O> Bag<O>	transformedBag(Bag<I> bag, Transformer<I,O> transformer) Deprecated. TransformedCollections are not type-safe in Java 1.5.
static <I,O> SortedBag<O>	transformedSortedBag(SortedBag<I> bag, Transformer<I,O> transformer) Deprecated. This breaks the java.util.Collection interface in Java 1.5. It is recommended that it not be used.
static <E> Bag<E>	typedBag(Bag<E> bag, Class<E> type) Deprecated. Java 1.5 generics makes this method no longer useful.
static <E> SortedBag<E>	typedSortedBag(SortedBag<E> bag, Class<E> type) Deprecated. Java 1.5 generics makes this method no longer useful.
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 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 <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.

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.

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.

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

typedBag

public static <E> Bag<E> typedBag(Bag<E> bag,
                                  Class<E> type)

Deprecated. Java 1.5 generics makes this method no longer useful.

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 <I,O> Bag<O> transformedBag(Bag<I> bag,
                                          Transformer<I,O> transformer)

Deprecated. TransformedCollections are not type-safe in Java 1.5.

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:

IllegalArgumentException - if the Bag or Transformer 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.

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.

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.

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

typedSortedBag

public static <E> SortedBag<E> typedSortedBag(SortedBag<E> bag,
                                              Class<E> type)

Deprecated. Java 1.5 generics makes this method no longer useful.

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 <I,O> SortedBag<O> transformedSortedBag(SortedBag<I> bag,
                                                      Transformer<I,O> transformer)

Deprecated. This breaks the java.util.Collection interface in Java 1.5. It is recommended that it not be used.

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:

IllegalArgumentException - if the Bag or Transformer is null