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:
2.1
Version:
$Id: BagUtils.java,v 1.7.2.1 2004/05/22 12:14:01 scolebourne Exp $
Author:
Paul Jack, Stephen Colebourne

Method Summary
static Bag predicatedBag(Bag bag, Predicate predicate)
          Returns a predicated bag backed by the given bag.
static SortedBag predicatedSortedBag(SortedBag bag, Predicate predicate)
          Returns a predicated 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 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
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

predicatedBag

public static Bag predicatedBag(Bag bag,
                                Predicate predicate)
Returns a predicated bag backed by the given bag. Only objects that pass the test in the given predicate can be added to the bag. It is important not to use the original bag after invoking this method, as it is a backdoor for adding unvalidated 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

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

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

predicatedSortedBag

public static SortedBag predicatedSortedBag(SortedBag bag,
                                            Predicate predicate)
Returns a predicated sorted bag backed by the given sorted bag. Only objects that pass the test in the given predicate can be added to the bag. It is important not to use the original bag after invoking this method, as it is a backdoor for adding unvalidated 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

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

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


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