From 968607b9c5f94ab3b36c7ec4fa37f6512d0a0d2f Mon Sep 17 00:00:00 2001 From: Stephen Colebourne Date: Sun, 15 Dec 2002 13:05:03 +0000 Subject: [PATCH] Add empty unmodifiable implementations for all collections Add synchronized/unmodifiable implementations for all collections git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/collections/trunk@130892 13f79535-47bb-0310-9956-ffa450edef68 --- .../commons/collections/BufferUtils.java | 18 +-- .../commons/collections/CollectionUtils.java | 58 +++++++++- .../apache/commons/collections/ListUtils.java | 55 ++++++++- .../apache/commons/collections/MapUtils.java | 99 ++++++++++++++++- .../apache/commons/collections/SetUtils.java | 104 +++++++++++++++++- 5 files changed, 308 insertions(+), 26 deletions(-) diff --git a/src/java/org/apache/commons/collections/BufferUtils.java b/src/java/org/apache/commons/collections/BufferUtils.java index e8148669a..6ea3561cf 100644 --- a/src/java/org/apache/commons/collections/BufferUtils.java +++ b/src/java/org/apache/commons/collections/BufferUtils.java @@ -1,7 +1,7 @@ /* - * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/BufferUtils.java,v 1.9 2002/10/13 00:38:36 scolebourne Exp $ - * $Revision: 1.9 $ - * $Date: 2002/10/13 00:38:36 $ + * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/BufferUtils.java,v 1.10 2002/12/15 13:05:03 scolebourne Exp $ + * $Revision: 1.10 $ + * $Date: 2002/12/15 13:05:03 $ * * ==================================================================== * @@ -66,18 +66,22 @@ import java.util.Collection; * * @author Paul Jack * @author Stephen Colebourne - * @version $Id: BufferUtils.java,v 1.9 2002/10/13 00:38:36 scolebourne Exp $ + * @version $Id: BufferUtils.java,v 1.10 2002/12/15 13:05:03 scolebourne Exp $ * @since 2.1 */ public class BufferUtils { /** - * Restrictive constructor + * An empty unmodifiable buffer. */ - private BufferUtils() { + public static final Buffer EMPTY_BUFFER = BufferUtils.unmodifiableBuffer(new ArrayStack()); + + /** + * BufferUtils should not normally be instantiated. + */ + public BufferUtils() { } - /** * Returns a synchronized buffer backed by the given buffer. * Much like the synchronized collections returned by diff --git a/src/java/org/apache/commons/collections/CollectionUtils.java b/src/java/org/apache/commons/collections/CollectionUtils.java index 924d78ac8..a3ba5ccdc 100644 --- a/src/java/org/apache/commons/collections/CollectionUtils.java +++ b/src/java/org/apache/commons/collections/CollectionUtils.java @@ -1,7 +1,7 @@ /* - * $Id: CollectionUtils.java,v 1.23 2002/12/11 19:05:14 scolebourne Exp $ - * $Revision: 1.23 $ - * $Date: 2002/12/11 19:05:14 $ + * $Id: CollectionUtils.java,v 1.24 2002/12/15 13:05:03 scolebourne Exp $ + * $Revision: 1.24 $ + * $Date: 2002/12/15 13:05:03 $ * * ==================================================================== * @@ -62,6 +62,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; @@ -84,10 +85,18 @@ import org.apache.commons.collections.iterators.EnumerationIterator; * @author Steve Downey * @author Herve Quiroz * @author BluePhelix@web.de (Peter) - * @version $Revision: 1.23 $ $Date: 2002/12/11 19:05:14 $ + * @author Stephen Colebourne + * @version $Revision: 1.24 $ $Date: 2002/12/15 13:05:03 $ */ public class CollectionUtils { + /** + * An empty unmodifiable collection. + * The JDK provides empty Set and List implementations which could be used for + * this purpose. However they could be cast to Set or List which might be + * undesirable. This implementation only implements Collection. + */ + public static final Collection EMPTY_COLLECTION = Collections.unmodifiableCollection(new ArrayList()); /** * The empty iterator (immutable). * @deprecated use IteratorUtils.EMPTY_ITERATOR @@ -95,7 +104,7 @@ public class CollectionUtils { public static final Iterator EMPTY_ITERATOR = IteratorUtils.EMPTY_ITERATOR; /** - * Please don't ever instantiate a CollectionUtils. + * CollectionUtils should not normally be instantiated. */ public CollectionUtils() { } @@ -1121,6 +1130,45 @@ public class CollectionUtils { } + /** + * Returns a synchronized collection backed by the given collection. + *

+ * You must manually synchronize on the returned buffer's iterator to + * avoid non-deterministic behavior: + * + * 

+     * Collection c = CollectionUtils.synchronizedCollection(myCollection);
+     * synchronized (c) {
+     *     Iterator i = c.iterator();
+     *     while (i.hasNext()) {
+     *         process (i.next());
+     *     }
+     * }
+     *
+ * + * This method uses the implementation in {@link java.util.Collections Collections}. + * + * @param collection the collection to synchronize, must not be null + * @return a synchronized collection backed by the given collection + * @throws IllegalArgumentException if the collection is null + */ + public static Collection synchronizedCollection(Collection collection) { + return Collections.synchronizedCollection(collection); + } + + /** + * Returns an unmodifiable collection backed by the given collection. + *

+ * This method uses the implementation in {@link java.util.Collections Collections}. + * + * @param collection the collection to make unmodifiable, must not be null + * @return an unmodifiable collection backed by the given collection + * @throws IllegalArgumentException if the collection is null + */ + public static Collection unmodifiableCollection(Collection collection) { + return Collections.unmodifiableCollection(collection); + } + /** * Returns a predicated collection backed by the given collection. * Only objects that pass the test in the given predicate can be diff --git a/src/java/org/apache/commons/collections/ListUtils.java b/src/java/org/apache/commons/collections/ListUtils.java index 2ccea102d..36229eeb9 100644 --- a/src/java/org/apache/commons/collections/ListUtils.java +++ b/src/java/org/apache/commons/collections/ListUtils.java @@ -1,7 +1,7 @@ /* - * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/ListUtils.java,v 1.11 2002/10/13 00:38:36 scolebourne Exp $ - * $Revision: 1.11 $ - * $Date: 2002/10/13 00:38:36 $ + * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/ListUtils.java,v 1.12 2002/12/15 13:05:03 scolebourne Exp $ + * $Revision: 1.12 $ + * $Date: 2002/12/15 13:05:03 $ * * ==================================================================== * @@ -62,6 +62,7 @@ package org.apache.commons.collections; import java.util.ArrayList; import java.util.Collection; +import java.util.Collections; import java.util.Iterator; import java.util.List; import java.util.ListIterator; @@ -78,7 +79,14 @@ import java.util.ListIterator; public class ListUtils { /** - * Please don't ever instantiate a ListUtils. + * An empty unmodifiable list. + * This uses the {@link #java.util.Collections Collections} implementation + * and is provided for completeness. + */ + public static final List EMPTY_LIST = Collections.EMPTY_LIST; + + /** + * ListUtils should not normally be instantiated. */ public ListUtils() { } @@ -444,6 +452,45 @@ public class ListUtils { } + /** + * Returns a synchronized list backed by the given list. + *

+ * You must manually synchronize on the returned buffer's iterator to + * avoid non-deterministic behavior: + * + * 

+     * List list = ListUtils.synchronizedList(myList);
+     * synchronized (list) {
+     *     Iterator i = list.iterator();
+     *     while (i.hasNext()) {
+     *         process (i.next());
+     *     }
+     * }
+     *
+ * + * This method uses the implementation in {@link java.util.Collections Collections}. + * + * @param list the list to synchronize, must not be null + * @return a synchronized list backed by the given list + * @throws IllegalArgumentException if the list is null + */ + public static List synchronizedList(List list) { + return Collections.synchronizedList(list); + } + + /** + * Returns an unmodifiable list backed by the given list. + *

+ * This method uses the implementation in {@link java.util.Collections Collections}. + * + * @param list the list to make unmodifiable, must not be null + * @return an unmodifiable list backed by the given list + * @throws IllegalArgumentException if the list is null + */ + public static List unmodifiableList(List list) { + return Collections.unmodifiableList(list); + } + /** * Returns a predicated list backed by the given list. Only objects * that pass the test in the given predicate can be added to the list. diff --git a/src/java/org/apache/commons/collections/MapUtils.java b/src/java/org/apache/commons/collections/MapUtils.java index f948f46e1..10ee0e69b 100644 --- a/src/java/org/apache/commons/collections/MapUtils.java +++ b/src/java/org/apache/commons/collections/MapUtils.java @@ -1,7 +1,7 @@ /* - * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/MapUtils.java,v 1.14 2002/10/13 22:31:35 scolebourne Exp $ - * $Revision: 1.14 $ - * $Date: 2002/10/13 22:31:35 $ + * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/MapUtils.java,v 1.15 2002/12/15 13:05:03 scolebourne Exp $ + * $Revision: 1.15 $ + * $Date: 2002/12/15 13:05:03 $ * * ==================================================================== * @@ -89,11 +89,22 @@ import java.util.*; * @author Stephen Colebourne */ public class MapUtils { + + /** + * An empty unmodifiable map. + * This was not provided in JDK1.2. + */ + public static final Map EMPTY_MAP = Collections.unmodifiableMap(new HashMap(1)); + /** + * An empty unmodifiable sorted map. + * This is not provided in the JDK. + */ + public static final SortedMap EMPTY_SORTED_MAP = Collections.unmodifiableSortedMap(new TreeMap()); private static int debugIndent = 0; /** - * Please don't instantiate a MapUtils. + * MapUtils should not normally be instantiated. */ public MapUtils() { } @@ -1060,6 +1071,46 @@ public class MapUtils { } + /** + * Returns a synchronized map backed by the given map. + *

+ * You must manually synchronize on the returned buffer's iterator to + * avoid non-deterministic behavior: + * + * 

+     * Map m = MapUtils.synchronizedMap(myMap);
+     * Set s = m.keySet();  // outside synchronized block
+     * synchronized (m) {  // synchronized on MAP!
+     *     Iterator i = s.iterator();
+     *     while (i.hasNext()) {
+     *         process (i.next());
+     *     }
+     * }
+     *
+ * + * This method uses the implementation in {@link java.util.Collections Collections}. + * + * @param map the map to synchronize, must not be null + * @return a synchronized map backed by the given map + * @throws IllegalArgumentException if the map is null + */ + public static Map synchronizedMap(Map map) { + return Collections.synchronizedMap(map); + } + + /** + * Returns an unmodifiable map backed by the given map. + *

+ * This method uses the implementation in {@link java.util.Collections Collections}. + * + * @param map the map to make unmodifiable, must not be null + * @return an unmodifiable map backed by the given map + * @throws IllegalArgumentException if the map is null + */ + public static Map unmodifiableMap(Map map) { + return Collections.unmodifiableMap(map); + } + /** * Returns a predicated map backed by the given map. Only keys and * values that pass the given predicates can be added to the map. @@ -1123,6 +1174,46 @@ public class MapUtils { return new LazyMap(map, factory); } + /** + * Returns a synchronized sorted map backed by the given sorted map. + *

+ * You must manually synchronize on the returned buffer's iterator to + * avoid non-deterministic behavior: + * + * 

+     * Map m = MapUtils.synchronizedSortedMap(myMap);
+     * Set s = m.keySet();  // outside synchronized block
+     * synchronized (m) {  // synchronized on MAP!
+     *     Iterator i = s.iterator();
+     *     while (i.hasNext()) {
+     *         process (i.next());
+     *     }
+     * }
+     *
+ * + * This method uses the implementation in {@link java.util.Collections Collections}. + * + * @param map the map to synchronize, must not be null + * @return a synchronized map backed by the given map + * @throws IllegalArgumentException if the map is null + */ + public static Map synchronizedSortedMap(SortedMap map) { + return Collections.synchronizedSortedMap(map); + } + + /** + * Returns an unmodifiable sorted map backed by the given sorted map. + *

+ * This method uses the implementation in {@link java.util.Collections Collections}. + * + * @param map the sorted map to make unmodifiable, must not be null + * @return an unmodifiable map backed by the given map + * @throws IllegalArgumentException if the map is null + */ + public static Map unmodifiableSortedMap(SortedMap map) { + return Collections.unmodifiableSortedMap(map); + } + /** * Returns a predicated sorted map backed by the given map. Only keys and * values that pass the given predicates can be added to the map. diff --git a/src/java/org/apache/commons/collections/SetUtils.java b/src/java/org/apache/commons/collections/SetUtils.java index 0534ea28c..06cd83045 100644 --- a/src/java/org/apache/commons/collections/SetUtils.java +++ b/src/java/org/apache/commons/collections/SetUtils.java @@ -1,7 +1,7 @@ /* - * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/SetUtils.java,v 1.7 2002/10/13 00:38:36 scolebourne Exp $ - * $Revision: 1.7 $ - * $Date: 2002/10/13 00:38:36 $ + * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/SetUtils.java,v 1.8 2002/12/15 13:05:03 scolebourne Exp $ + * $Revision: 1.8 $ + * $Date: 2002/12/15 13:05:03 $ * * ==================================================================== * @@ -60,24 +60,38 @@ */ package org.apache.commons.collections; +import java.util.Collections; import java.util.Comparator; import java.util.Set; import java.util.SortedSet; +import java.util.TreeSet; /** * Provides static utility methods and decorators for {@link Set} * and {@link SortedSet} instances. * * @author Paul Jack * @author Stephen Colebourne - * @version $Id: SetUtils.java,v 1.7 2002/10/13 00:38:36 scolebourne Exp $ + * @version $Id: SetUtils.java,v 1.8 2002/12/15 13:05:03 scolebourne Exp $ * @since 2.1 */ public class SetUtils { /** - * Prevents instantiation. + * An empty unmodifiable set. + * This uses the {@link #java.util.Collections Collections} implementation + * and is provided for completeness. */ - private SetUtils() { + public static final Set EMPTY_SET = Collections.EMPTY_SET; + /** + * An empty unmodifiable sorted set. + * This is not provided in the JDK. + */ + public static final SortedSet EMPTY_SORTED_SET = Collections.unmodifiableSortedSet(new TreeSet()); + + /** + * SetUtils should not normally be instantiated. + */ + public SetUtils() { } @@ -133,6 +147,45 @@ public class SetUtils { } + /** + * Returns a synchronized set backed by the given set. + *

+ * You must manually synchronize on the returned buffer's iterator to + * avoid non-deterministic behavior: + * + * 

+     * Set s = SetUtils.synchronizedSet(mySet);
+     * synchronized (s) {
+     *     Iterator i = s.iterator();
+     *     while (i.hasNext()) {
+     *         process (i.next());
+     *     }
+     * }
+     *
+ * + * This method uses the implementation in {@link java.util.Collections Collections}. + * + * @param set the set to synchronize, must not be null + * @return a synchronized set backed by the given set + * @throws IllegalArgumentException if the set is null + */ + public static Set synchronizedSet(Set set) { + return Collections.synchronizedSet(set); + } + + /** + * Returns an unmodifiable set backed by the given set. + *

+ * This method uses the implementation in {@link java.util.Collections Collections}. + * + * @param set the set to make unmodifiable, must not be null + * @return an unmodifiable set backed by the given set + * @throws IllegalArgumentException if the set is null + */ + public static Set unmodifiableSet(Set set) { + return Collections.unmodifiableSet(set); + } + /** * Returns a predicated set backed by the given set. Only objects * that pass the test in the given predicate can be added to the set. @@ -148,6 +201,45 @@ public class SetUtils { return new PredicatedSet(set, predicate); } + /** + * Returns a synchronized sorted set backed by the given sorted set. + *

+ * You must manually synchronize on the returned buffer's iterator to + * avoid non-deterministic behavior: + * + * 

+     * Set s = SetUtils.synchronizedSet(mySet);
+     * synchronized (s) {
+     *     Iterator i = s.iterator();
+     *     while (i.hasNext()) {
+     *         process (i.next());
+     *     }
+     * }
+     *
+ * + * This method uses the implementation in {@link java.util.Collections Collections}. + * + * @param set the sorted set to synchronize, must not be null + * @return a synchronized set backed by the given set + * @throws IllegalArgumentException if the set is null + */ + public static SortedSet synchronizedSortedSet(SortedSet set) { + return Collections.synchronizedSortedSet(set); + } + + /** + * Returns an unmodifiable sorted set backed by the given sorted set. + *

+ * This method uses the implementation in {@link java.util.Collections Collections}. + * + * @param set the sorted set to make unmodifiable, must not be null + * @return an unmodifiable set backed by the given set + * @throws IllegalArgumentException if the set is null + */ + public static SortedSet unmodifiableSortedSet(SortedSet set) { + return Collections.unmodifiableSortedSet(set); + } + /** * Returns a predicated sorted set backed by the given sorted set. * Only objects that pass the test in the given predicate can be added