Author: bayard Date: Tue Sep 15 05:54:12 2009 New Revision: 815020 URL: http://svn.apache.org/viewvc?rev=815020&view=rev Log: Merging from -r468106:814127 of collections_jdk5_branch - namely where this code was generified; mostly in r738956.
Also see the following revisions: ------------------------------------------------------------------------ r555925 | skestle | 2007-07-13 03:39:24 -0700 (Fri, 13 Jul 2007) | 2 lines Added Edwin Tellman's patch for COLLECTIONS-243. It all seems pretty reasonable, and it should all be checked again as the project is worked through ------------------------------------------------------------------------ r471166 | scolebourne | 2006-11-04 03:33:22 -0800 (Sat, 04 Nov 2006) | 1 line Removed Typed* containers such as TypedList and TypedMap as generics now provides type safety ------------------------------------------------------------------------ Modified: commons/proper/collections/trunk/src/java/org/apache/commons/collections/BagUtils.java Modified: commons/proper/collections/trunk/src/java/org/apache/commons/collections/BagUtils.java URL: http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/java/org/apache/commons/collections/BagUtils.java?rev=815020&r1=815019&r2=815020&view=diff ============================================================================== --- commons/proper/collections/trunk/src/java/org/apache/commons/collections/BagUtils.java (original) +++ commons/proper/collections/trunk/src/java/org/apache/commons/collections/BagUtils.java Tue Sep 15 05:54:12 2009 @@ -24,17 +24,16 @@ import org.apache.commons.collections.bag.TransformedBag; import org.apache.commons.collections.bag.TransformedSortedBag; import org.apache.commons.collections.bag.TreeBag; -import org.apache.commons.collections.bag.TypedBag; -import org.apache.commons.collections.bag.TypedSortedBag; import org.apache.commons.collections.bag.UnmodifiableBag; import org.apache.commons.collections.bag.UnmodifiableSortedBag; /** - * Provides utility methods and decorators for - * {...@link Bag} and {...@link SortedBag} instances. + * Provides utility methods and decorators for {...@link Bag} and {...@link SortedBag} + * instances. * * @since Commons Collections 2.1 - * @version $Revision$ $Date$ + * @version $Revision$ $Date: 2007-07-13 05:39:24 -0500 (Fri, 13 Jul + * 2007) $ * * @author Paul Jack * @author Stephen Colebourne @@ -46,29 +45,29 @@ /** * An empty unmodifiable bag. */ - public static final Bag EMPTY_BAG = UnmodifiableBag.decorate(new HashBag()); + public static final Bag<Object> EMPTY_BAG = UnmodifiableBag.decorate(new HashBag<Object>()); /** * An empty unmodifiable sorted bag. */ - public static final Bag EMPTY_SORTED_BAG = UnmodifiableSortedBag.decorate(new TreeBag()); + public static final Bag<Object> EMPTY_SORTED_BAG = UnmodifiableSortedBag.decorate(new TreeBag<Object>()); /** - * Instantiation of BagUtils is not intended or required. - * However, some tools require an instance to operate. + * Instantiation of BagUtils is not intended or required. However, some + * tools require an instance to operate. */ public BagUtils() { } //----------------------------------------------------------------------- /** - * 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. + * 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. * <p> - * It is imperative that the user manually synchronize on the returned - * bag when iterating over it: - * + * It is imperative that the user manually synchronize on the returned bag + * when iterating over it: + * * <pre> * Bag bag = BagUtils.synchronizedBag(new HashBag()); * ... @@ -79,90 +78,76 @@ * } * } * </pre> - * - * Failure to follow this advice may result in non-deterministic - * behavior. - * - * @param bag the bag to synchronize, must not be null + * + * Failure to follow this advice may result in non-deterministic behavior. + * + * @param bag the bag to synchronize, must not be null * @return a synchronized bag backed by that bag - * @throws IllegalArgumentException if the Bag is null + * @throws IllegalArgumentException if the Bag is null */ - public static Bag synchronizedBag(Bag bag) { + public static <E> Bag<E> synchronizedBag(Bag<E> bag) { return SynchronizedBag.decorate(bag); } /** - * Returns an unmodifiable view of the given bag. Any modification - * attempts to the returned bag will raise an - * {...@link UnsupportedOperationException}. - * - * @param bag the bag whose unmodifiable view is to be returned, must not be null + * Returns an unmodifiable view of the given bag. Any modification attempts + * to the returned bag will raise an {...@link UnsupportedOperationException}. + * + * @param bag the bag whose unmodifiable view is to be returned, must not be + * null * @return an unmodifiable view of that bag - * @throws IllegalArgumentException if the Bag is null + * @throws IllegalArgumentException if the Bag is null */ - public static Bag unmodifiableBag(Bag bag) { + public static <E> Bag<E> unmodifiableBag(Bag<E> bag) { return UnmodifiableBag.decorate(bag); } - + /** * Returns a predicated (validating) bag backed by the given bag. * <p> - * 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. - * - * @param bag the bag to predicate, must not be null - * @param predicate the predicate for the bag, must not be null + * 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. + * + * @param bag the bag to predicate, must not be null + * @param predicate the predicate for the bag, must not be null * @return a predicated bag backed by the given bag - * @throws IllegalArgumentException if the Bag or Predicate is null + * @throws IllegalArgumentException if the Bag or Predicate is null */ - public static Bag predicatedBag(Bag bag, Predicate predicate) { + public static <E> Bag<E> predicatedBag(Bag<E> bag, Predicate<? super E> predicate) { return PredicatedBag.decorate(bag, predicate); } - - /** - * Returns a typed bag backed by the given bag. - * <p> - * Only objects of the specified type can be added to the bag. - * - * @param bag the bag to limit to a specific type, must not be null - * @param type the type of objects which may be added to the bag - * @return a typed bag backed by the specified bag - */ - public static Bag typedBag(Bag bag, Class type) { - return TypedBag.decorate(bag, type); - } - + /** * Returns a transformed bag backed by the given bag. * <p> - * 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. + * 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. * <p> * Existing entries in the specified bag will not be transformed. * If you want that behaviour, see {...@link TransformedBag#decorateTransform}. - * - * @param bag the bag to predicate, must not be null - * @param transformer the transformer for the bag, must not be null + * + * @param bag the bag to predicate, must not be null + * @param transformer the transformer for the bag, must not be null * @return a transformed bag backed by the given bag - * @throws IllegalArgumentException if the Bag or Transformer is null + * @throws IllegalArgumentException if the Bag or Transformer is null */ - public static Bag transformedBag(Bag bag, Transformer transformer) { + public static <E> Bag<E> transformedBag(Bag<E> bag, Transformer<? super E, ? extends E> transformer) { return TransformedBag.decorate(bag, transformer); } - + //----------------------------------------------------------------------- /** - * Returns a synchronized (thread-safe) sorted bag backed by the given - * sorted bag. - * In order to guarantee serial access, it is critical that all + * 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. * <p> - * It is imperative that the user manually synchronize on the returned - * bag when iterating over it: - * + * It is imperative that the user manually synchronize on the returned bag + * when iterating over it: + * * <pre> * SortedBag bag = BagUtils.synchronizedSortedBag(new TreeBag()); * ... @@ -173,78 +158,87 @@ * } * } * </pre> - * - * Failure to follow this advice may result in non-deterministic - * behavior. - * - * @param bag the bag to synchronize, must not be null + * + * Failure to follow this advice may result in non-deterministic behavior. + * + * @param bag the bag to synchronize, must not be null * @return a synchronized bag backed by that bag - * @throws IllegalArgumentException if the SortedBag is null + * @throws IllegalArgumentException if the SortedBag is null */ - public static SortedBag synchronizedSortedBag(SortedBag bag) { + public static <E> SortedBag<E> synchronizedSortedBag(SortedBag<E> bag) { return SynchronizedSortedBag.decorate(bag); } - + /** - * Returns an unmodifiable view of the given sorted bag. Any modification - * attempts to the returned bag will raise an + * Returns an unmodifiable view of the given sorted bag. Any modification + * attempts to the returned bag will raise an * {...@link UnsupportedOperationException}. - * - * @param bag the bag whose unmodifiable view is to be returned, must not be null + * + * @param bag the bag whose unmodifiable view is to be returned, must not be + * null * @return an unmodifiable view of that bag - * @throws IllegalArgumentException if the SortedBag is null + * @throws IllegalArgumentException if the SortedBag is null */ - public static SortedBag unmodifiableSortedBag(SortedBag bag) { + public static <E> SortedBag<E> unmodifiableSortedBag(SortedBag<E> bag) { return UnmodifiableSortedBag.decorate(bag); } - + /** - * Returns a predicated (validating) sorted bag backed by the given sorted bag. + * Returns a predicated (validating) sorted bag backed by the given sorted + * bag. * <p> - * 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. - * - * @param bag the sorted bag to predicate, must not be null - * @param predicate the predicate for the bag, must not be null + * 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. + * + * @param bag the sorted bag to predicate, must not be null + * @param predicate the predicate for the bag, must not be null * @return a predicated bag backed by the given bag - * @throws IllegalArgumentException if the SortedBag or Predicate is null + * @throws IllegalArgumentException if the SortedBag or Predicate is null */ - public static SortedBag predicatedSortedBag(SortedBag bag, Predicate predicate) { + public static <E> SortedBag<E> predicatedSortedBag(SortedBag<E> bag, + Predicate<? super E> predicate) { return PredicatedSortedBag.decorate(bag, predicate); } - - /** - * Returns a typed sorted bag backed by the given bag. - * <p> - * Only objects of the specified type can be added to the bag. - * - * @param bag the bag to limit to a specific type, must not be null - * @param type the type of objects which may be added to the bag - * @return a typed bag backed by the specified bag - */ - public static SortedBag typedSortedBag(SortedBag bag, Class type) { - return TypedSortedBag.decorate(bag, type); - } - + /** * Returns a transformed sorted bag backed by the given bag. * <p> - * 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. + * 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. * <p> * Existing entries in the specified bag will not be transformed. * If you want that behaviour, see {...@link TransformedSortedBag#decorateTransform}. - * - * @param bag the bag to predicate, must not be null - * @param transformer the transformer for the bag, must not be null + * + * @param bag the bag to predicate, must not be null + * @param transformer the transformer for the bag, must not be null * @return a transformed bag backed by the given bag - * @throws IllegalArgumentException if the Bag or Transformer is null + * @throws IllegalArgumentException if the Bag or Transformer is null */ - public static SortedBag transformedSortedBag(SortedBag bag, Transformer transformer) { + public static <E> SortedBag<E> transformedSortedBag(SortedBag<E> bag, Transformer<? super E, ? extends E> transformer) { return TransformedSortedBag.decorate(bag, transformer); } - + + /** + * Get an empty <code>Bag</code>. + * @param <E> + * @return Bag<E> + */ + @SuppressWarnings("unchecked") + public static <E> Bag<E> emptyBag() { + return (Bag<E>) EMPTY_BAG; + } + + /** + * Get an empty <code>SortedBag</code>. + * @param <E> + * @return SortedBag<E> + */ + @SuppressWarnings("unchecked") + public static <E> SortedBag<E> emptySortedBag() { + return (SortedBag<E>) EMPTY_SORTED_BAG; + } }