diff --git a/src/java/org/apache/commons/collections/CollectionUtils.java b/src/java/org/apache/commons/collections/CollectionUtils.java index da9d57586..5a840f323 100644 --- a/src/java/org/apache/commons/collections/CollectionUtils.java +++ b/src/java/org/apache/commons/collections/CollectionUtils.java @@ -38,7 +38,7 @@ import org.apache.commons.collections.collection.UnmodifiableCollection; * Provides utility methods and decorators for {@link Collection} instances. * * @since Commons Collections 1.0 - * @version $Revision: 1.62 $ $Date: 2004/07/17 21:38:33 $ + * @version $Revision: 1.63 $ $Date: 2004/12/11 06:30:38 $ * * @author Rodney Waldhoff * @author Paul Jack @@ -51,6 +51,7 @@ import org.apache.commons.collections.collection.UnmodifiableCollection; * @author Phil Steitz * @author Steven Melzer * @author Jon Schewe + * @author Neil O'Toole */ public class CollectionUtils { @@ -1048,6 +1049,22 @@ public class CollectionUtils { return UnmodifiableCollection.decorate(collection); } + /** + * Returns an unmodifiable copy of the collection. + *
+ * This method uses the implementation in the decorators subpackage.
+ *
+ * @param collection the Collection
to copy.
+ * @return an unmodifiable Collection
.
+ * @throws IllegalArgumentException if collection is null
+ */
+ public static Collection unmodifiableCollectionCopy(final Collection collection){
+ if (collection == null) throw new IllegalArgumentException("null not permitted.");
+
+ final Collection copy = new ArrayList(collection.size());
+ copy.addAll(collection);
+ return UnmodifiableCollection.decorate(copy);
+ }
/**
* Returns a predicated (validating) collection backed by the given collection.
*
@@ -1093,5 +1110,43 @@ public class CollectionUtils {
public static Collection transformedCollection(Collection collection, Transformer transformer) {
return TransformedCollection.decorate(collection, transformer);
}
-
+
+ /**
+ * Returns a collection containing all the elements in collection
+ * that are also in retain
. The cardinality of an element e
+ * in the returned collection is the same as the cardinality of e
+ * in collection
unless retain
does not contain e
, in which
+ * case the cardinality is zero. This method is useful if you do not wish to modify
+ * the collection c
and thus cannot call c.retainAll(retain);
.
+ *
+ * @param collection the collection whose contents are the target of the #retailAll operation
+ * @param retain the collection containing the elements to be retained in the returned collection
+ * @return a Collection
containing all the elements of collection
+ * that occur at least once in retain
.
+ * @throws NullPointerException if either parameter is null
+ */
+ public static Collection retainAll(final Collection collection, final Collection retain) {
+ return ListUtils.retainAll(collection, retain);
+ }
+
+ /**
+ * Removes the elements in remove
from collection
. That is, this
+ * method returns a collection containing all the elements in c
+ * that are not in remove
. The cardinality of an element e
+ * in the returned collection is the same as the cardinality of e
+ * in collection
unless remove
contains e
, in which
+ * case the cardinality is zero. This method is useful if you do not wish to modify
+ * the collection c
and thus cannot call collection.removeAll(remove);
.
+ *
+ * @param collection the collection from which items are removed (in the returned collection)
+ * @param remove the items to be removed from the returned collection
+ * @return a Collection
containing all the elements of collection
except
+ * any elements that also occur in remove
.
+ * @throws NullPointerException if either parameter is null
+ */
+ public static Collection removeAll(final Collection collection, final Collection remove) {
+ return ListUtils.retainAll(collection, remove);
+ }
+
+
}
diff --git a/src/test/org/apache/commons/collections/TestCollectionUtils.java b/src/test/org/apache/commons/collections/TestCollectionUtils.java
index 998451f77..aa99ff36c 100644
--- a/src/test/org/apache/commons/collections/TestCollectionUtils.java
+++ b/src/test/org/apache/commons/collections/TestCollectionUtils.java
@@ -17,6 +17,7 @@ package org.apache.commons.collections;
import java.util.ArrayList;
import java.util.Collection;
+import java.util.Collections;
import java.util.Enumeration;
import java.util.HashMap;
import java.util.HashSet;
@@ -49,8 +50,9 @@ import org.apache.commons.collections.collection.UnmodifiableCollection;
* @author Stephen Colebourne
* @author Phil Steitz
* @author Steven Melzer
+ * @author Neil O'Toole
*
- * @version $Revision: 1.41 $ $Date: 2004/08/03 18:20:41 $
+ * @version $Revision: 1.42 $ $Date: 2004/12/11 06:30:38 $
*/
public class TestCollectionUtils extends TestCase {
@@ -1194,5 +1196,32 @@ public class TestCollectionUtils extends TestCase {
// expected
}
}
+
+ public void testUnmodifiableCollectionCopy() {
+ Collection collection = new ArrayList();
+ collection.add("a");
+ Collection copy = CollectionUtils.unmodifiableCollectionCopy(collection);
+ assertTrue(copy instanceof Unmodifiable);
+ assertTrue(CollectionUtils.isEqualCollection(collection, copy));
+ collection.clear();
+ assertTrue(copy.isEmpty() == false);
+
+ try
+ {
+ copy.clear();
+ fail("should be unmodifiable.");
+ }
+ catch (UnsupportedOperationException uoe)
+ {} // this is what we want
+
+ try
+ {
+ copy = CollectionUtils.unmodifiableCollectionCopy(null);
+ fail("should throw IllegalArgumentException");
+ }
+ catch(IllegalArgumentException iae)
+ {}
+ }
+
}