scolebourne 2002/10/12 17:38:36 Modified: collections/src/java/org/apache/commons/collections MapUtils.java BufferUtils.java ListUtils.java CollectionUtils.java BagUtils.java SetUtils.java Log: Javadoc improvements, especially exception descriptions Revision Changes Path 1.13 +160 -144 jakarta-commons/collections/src/java/org/apache/commons/collections/MapUtils.java Index: MapUtils.java =================================================================== RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/MapUtils.java,v retrieving revision 1.12 retrieving revision 1.13 diff -u -r1.12 -r1.13 --- MapUtils.java 19 Aug 2002 21:56:18 -0000 1.12 +++ MapUtils.java 13 Oct 2002 00:38:36 -0000 1.13 @@ -64,29 +64,30 @@ import java.text.*; import java.text.NumberFormat; import java.util.*; - -/** A helper class for using {@link Map Map} instances.<P> - * - * It contains various typesafe methods - * as well as other useful features like deep copying.<P> - * - * It also provides the following decorators: - * - * <UL> - * <LI>{@link #fixedSizeMap(Map)} - * <LI>{@link #fixedSizeSortedMap(SortedMap)} - * <LI>{@link #lazyMap(Map,Factory)} - * <LI>{@link #lazySortedMap(SortedMap,Factory)} - * <LI>{@link #predicatedMap(Map,Predicate,Predicate)} - * <LI>{@link #predicatedSortedMap(SortedMap,Predicate,Predicate)} - * </UL> - * - * @since 1.0 - * @author <a href="mailto:[EMAIL PROTECTED]">James Strachan</a> - * @author <a href="mailto:[EMAIL PROTECTED]">Nissim Karpenstein</a> - * @author <a href="mailto:[EMAIL PROTECTED]">Kasper Nielsen</a> - * @author Paul Jack - */ +/** + * A helper class for using {@link Map Map} instances.<P> + * + * It contains various typesafe methods + * as well as other useful features like deep copying.<P> + * + * It also provides the following decorators: + * + * <UL> + * <LI>{@link #fixedSizeMap(Map)} + * <LI>{@link #fixedSizeSortedMap(SortedMap)} + * <LI>{@link #lazyMap(Map,Factory)} + * <LI>{@link #lazySortedMap(SortedMap,Factory)} + * <LI>{@link #predicatedMap(Map,Predicate,Predicate)} + * <LI>{@link #predicatedSortedMap(SortedMap,Predicate,Predicate)} + * </UL> + * + * @since 1.0 + * @author <a href="mailto:[EMAIL PROTECTED]">James Strachan</a> + * @author <a href="mailto:[EMAIL PROTECTED]">Nissim Karpenstein</a> + * @author <a href="mailto:[EMAIL PROTECTED]">Kasper Nielsen</a> + * @author Paul Jack + * @author Stephen Colebourne + */ public class MapUtils { private static int debugIndent = 0; @@ -727,22 +728,22 @@ } - static class PredicatedMap extends ProxyMap { - - final protected Predicate keyPredicate; - final protected Predicate valuePredicate; + static class PredicatedMap + extends ProxyMap { + protected final Predicate keyPredicate; + protected final Predicate valuePredicate; public PredicatedMap(Map map, Predicate keyPred, Predicate valuePred) { super(map); if (map == null) { - throw new IllegalArgumentException("map may not be null."); + throw new IllegalArgumentException("Map must not be null"); } if (keyPred == null) { - throw new IllegalArgumentException("keyPred may not be null."); + throw new IllegalArgumentException("Key Predicate must not be null"); } if (valuePred == null) { - throw new IllegalArgumentException("valuePred may not be null."); + throw new IllegalArgumentException("Value Predicate must not be null"); } this.keyPredicate = keyPred; this.valuePredicate = valuePred; @@ -778,20 +779,20 @@ private void validate(Object key, Object value) { if (!keyPredicate.evaluate(key)) { - throw new IllegalArgumentException("Invalid key."); + throw new IllegalArgumentException("Cannot add key - Predicate rejected it"); } if (!valuePredicate.evaluate(value)) { - throw new IllegalArgumentException("Invalid value."); + throw new IllegalArgumentException("Cannot add value - Predicate rejected it"); } } } static class PredicatedMapEntrySet - extends CollectionUtils.CollectionWrapper - implements Set { + extends CollectionUtils.CollectionWrapper + implements Set { - final private Predicate predicate; + private final Predicate predicate; public PredicatedMapEntrySet(Set set, Predicate p) { super(set); @@ -818,13 +819,20 @@ } - static class PredicatedMapEntry implements Map.Entry { + static class PredicatedMapEntry + implements Map.Entry { - final private Map.Entry entry; - final private Predicate predicate; + private final Map.Entry entry; + private final Predicate predicate; public PredicatedMapEntry(Map.Entry entry, Predicate p) { + if (entry == null) { + throw new IllegalArgumentException("Map.Entry must not be null"); + } + if (p == null) { + throw new IllegalArgumentException("Predicate must not be null"); + } this.entry = entry; this.predicate = p; } @@ -851,26 +859,27 @@ public Object setValue(Object o) { if (!predicate.evaluate(o)) { - throw new IllegalArgumentException("Invalid value."); + throw new IllegalArgumentException("Cannot set value - Predicate rejected it"); } return entry.setValue(o); } } - static class FixedSizeMap extends ProxyMap { + static class FixedSizeMap + extends ProxyMap { public FixedSizeMap(Map map) { super(map); if (map == null) { - throw new IllegalArgumentException("map may not be null."); + throw new IllegalArgumentException("Map must not be null"); } } public Object put(Object key, Object value) { if (!map.containsKey(key)) { - throw new IllegalArgumentException("Can't add new keys."); + throw new IllegalArgumentException("Cannot put new key/value pair - List is fixed size"); } return map.put(key, value); } @@ -879,7 +888,7 @@ public void putAll(Map m) { for (Iterator iter = m.keySet().iterator(); iter.hasNext(); ) { if (!map.containsKey(iter.next())) { - throw new IllegalArgumentException("Can't add new keys."); + throw new IllegalArgumentException("Cannot put new key/value pair - List is fixed size"); } } map.putAll(m); @@ -888,18 +897,18 @@ } - static class LazyMap extends ProxyMap { - - final protected Factory factory; + static class LazyMap + extends ProxyMap { + protected final Factory factory; public LazyMap(Map map, Factory factory) { super(map); if (map == null) { - throw new IllegalArgumentException("map may not be null."); + throw new IllegalArgumentException("Map must not be null"); } if (factory == null) { - throw new IllegalArgumentException("factory may not be null."); + throw new IllegalArgumentException("Factory must not be null"); } this.factory = factory; } @@ -918,8 +927,9 @@ - static class PredicatedSortedMap extends PredicatedMap - implements SortedMap { + static class PredicatedSortedMap + extends PredicatedMap + implements SortedMap { public PredicatedSortedMap(SortedMap map, Predicate k, Predicate v) { super(map, k, v); @@ -962,7 +972,9 @@ } - static class FixedSizeSortedMap extends FixedSizeMap implements SortedMap { + static class FixedSizeSortedMap + extends FixedSizeMap + implements SortedMap { public FixedSizeSortedMap(SortedMap m) { super(m); @@ -1002,7 +1014,9 @@ } - static class LazySortedMap extends LazyMap implements SortedMap { + static class LazySortedMap + extends LazyMap + implements SortedMap { public LazySortedMap(SortedMap m, Factory factory) { super(m, factory); @@ -1043,127 +1057,129 @@ /** - * Returns a predicated map backed by the given map. Only keys and - * values that pass the given predicates can be added to the map. - * It is important not to use the original map after invoking this - * method, as it is a backdoor for adding unvalidated objects. - * - * @param map the map to predicate - * @param keyPred the predicate for keys - * @param valuePred the predicate for values - * @return a predicated map backed by the given 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. + * It is important not to use the original map after invoking this + * method, as it is a backdoor for adding unvalidated objects. + * + * @param map the map to predicate, must not be null + * @param keyPred the predicate for keys, must not be null + * @param valuePred the predicate for values, must not be null + * @return a predicated map backed by the given map + * @throws IllegalArgumentException if the Map or Predicates are null */ public static Map predicatedMap(Map map, Predicate keyPred, Predicate valuePred) { return new PredicatedMap(map, keyPred, valuePred); } - /** - * Returns a fixed-sized map backed by the given map. - * Elements may not be added or removed from the returned map, but - * existing elements can be changed (for instance, via the - * {@link Map#put(Object,Object)} method). - * - * @param map the map whose size to fix - * @return a fixed-size map backed by that map + * Returns a fixed-sized map backed by the given map. + * Elements may not be added or removed from the returned map, but + * existing elements can be changed (for instance, via the + * {@link Map#put(Object,Object)} method). + * + * @param map the map whose size to fix, must not be null + * @return a fixed-size map backed by that map + * @throws IllegalArgumentException if the Map is null */ public static Map fixedSizeMap(Map map) { return new FixedSizeMap(map); } - /** - * Returns a "lazy" map whose values will be created on demand.<P> - * <P> - * When the key passed to the returned map's {@link Map#get(Object)} - * method is not present in the map, then the factory will be used - * to create a new object and that object will become the value - * associated with that key. - * <P> - * For instance: - * - * <Pre> - * Factory factory = new Factory() { - * public Object create() { - * return new Date(); - * } - * } - * Map lazy = MapUtils.lazyMap(new HashMap(), factory); - * Object obj = lazy.get("test"); - * </Pre> - * - * After the above code is executed, <Code>obj</Code> will contain - * a new <Code>Date</Code> instance. Furthermore, that <Code>Date</Code> - * instance is the value for the <Code>test</Code> key.<P> - * - * @param map the map to make lazy - * @param factory the factory for creating new objects - * @return a lazy map backed by the given map + * Returns a "lazy" map whose values will be created on demand.<P> + * <p> + * When the key passed to the returned map's {@link Map#get(Object)} + * method is not present in the map, then the factory will be used + * to create a new object and that object will become the value + * associated with that key. + * <p> + * For instance: + * + * <pre> + * Factory factory = new Factory() { + * public Object create() { + * return new Date(); + * } + * } + * Map lazy = MapUtils.lazyMap(new HashMap(), factory); + * Object obj = lazy.get("test"); + * </pre> + * + * After the above code is executed, <code>obj</code> will contain + * a new <code>Date</code> instance. Furthermore, that <code>Date</code> + * instance is the value for the <code>test</code> key. + * + * @param map the map to make lazy, must not be null + * @param factory the factory for creating new objects, must not be null + * @return a lazy map backed by the given map + * @throws IllegalArgumentException if the Map or Factory is null */ public static Map lazyMap(Map map, Factory factory) { return new LazyMap(map, factory); } - /** - * 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. - * It is important not to use the original map after invoking this - * method, as it is a backdoor for adding unvalidated objects. - * - * @param map the map to predicate - * @param keyPred the predicate for keys - * @param valuePred the predicate for values - * @return a predicated map backed by the given 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. + * It is important not to use the original map after invoking this + * method, as it is a backdoor for adding unvalidated objects. + * + * @param map the map to predicate, must not be null + * @param keyPred the predicate for keys, must not be null + * @param valuePred the predicate for values, must not be null + * @return a predicated map backed by the given map + * @throws IllegalArgumentException if the SortedMap or Predicates are null */ public static SortedMap predicatedSortedMap(SortedMap map, Predicate keyPred, Predicate valuePred) { return new PredicatedSortedMap(map, keyPred, valuePred); } - /** - * Returns a fixed-sized sorted map backed by the given sorted map. - * Elements may not be added or removed from the returned map, but - * existing elements can be changed (for instance, via the - * {@link Map#put(Object,Object)} method). - * - * @param map the map whose size to fix - * @return a fixed-size map backed by that map + * Returns a fixed-sized sorted map backed by the given sorted map. + * Elements may not be added or removed from the returned map, but + * existing elements can be changed (for instance, via the + * {@link Map#put(Object,Object)} method). + * + * @param map the map whose size to fix, must not be null + * @return a fixed-size map backed by that map + * @throws IllegalArgumentException if the SortedMap is null */ public static SortedMap fixedSizeSortedMap(SortedMap map) { return new FixedSizeSortedMap(map); } - /** - * Returns a "lazy" sorted map whose values will be created on demand. - * <P> - * When the key passed to the returned map's {@link Map#get(Object)} - * method is not present in the map, then the factory will be used - * to create a new object and that object will become the value - * associated with that key. - * <P> - * For instance: - * - * <Pre> - * Factory factory = new Factory() { - * public Object create() { - * return new Date(); - * } - * } - * SortedMap lazy = MapUtils.lazySortedMap(new TreeMap(), factory); - * Object obj = lazy.get("test"); - * </Pre> - * - * After the above code is executed, <Code>obj</Code> will contain - * a new <Code>Date</Code> instance. Furthermore, that <Code>Date</Code> - * instance is the value for the <Code>test</Code> key.<P> - * - * @param map the map to make lazy - * @param factory the factory for creating new objects - * @return a lazy map backed by the given map + * Returns a "lazy" sorted map whose values will be created on demand. + * <p> + * When the key passed to the returned map's {@link Map#get(Object)} + * method is not present in the map, then the factory will be used + * to create a new object and that object will become the value + * associated with that key. + * <p> + * For instance: + * + * <pre> + * Factory factory = new Factory() { + * public Object create() { + * return new Date(); + * } + * } + * SortedMap lazy = MapUtils.lazySortedMap(new TreeMap(), factory); + * Object obj = lazy.get("test"); + * </pre> + * + * After the above code is executed, <code>obj</code> will contain + * a new <code>Date</code> instance. Furthermore, that <code>Date</code> + * instance is the value for the <code>test</code> key. + * + * @param map the map to make lazy, must not be null + * @param factory the factory for creating new objects, must not be null + * @return a lazy map backed by the given map + * @throws IllegalArgumentException if the SortedMap or Factory is null */ public static SortedMap lazySortedMap(SortedMap map, Factory factory) { return new LazySortedMap(map, factory); } + } 1.9 +66 -65 jakarta-commons/collections/src/java/org/apache/commons/collections/BufferUtils.java Index: BufferUtils.java =================================================================== RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/BufferUtils.java,v retrieving revision 1.8 retrieving revision 1.9 diff -u -r1.8 -r1.9 --- BufferUtils.java 12 Oct 2002 22:15:18 -0000 1.8 +++ BufferUtils.java 13 Oct 2002 00:38:36 -0000 1.9 @@ -60,61 +60,62 @@ */ package org.apache.commons.collections; - import java.util.Collection; - - /** - * Contains static utility methods for operating on {@link Buffer} objects. + * Contains static utility methods for operating on {@link Buffer} objects. * - * @author Paul Jack - * @version $Id$ - * @since 2.1 + * @author Paul Jack + * @author Stephen Colebourne + * @version $Id$ + * @since 2.1 */ public class BufferUtils { - + /** + * Restrictive constructor + */ private BufferUtils() { } /** - * Returns a synchronized buffer backed by the given buffer. - * Much like the synchronized collections returned by - * {@link java.util.Collections}, you must manually synchronize on - * the returned buffer's iterator to avoid non-deterministic behavior: + * Returns a synchronized buffer backed by the given buffer. + * Much like the synchronized collections returned by + * {@link java.util.Collections}, you must manually synchronize on + * the returned buffer's iterator to avoid non-deterministic behavior: * - * <Pre> - * Buffer b = BufferUtils.synchronizedBuffer(myBuffer); - * synchronized (b) { - * Iterator i = b.iterator(); - * while (i.hasNext()) { - * process (i.next()); - * } - * } - * </Pre> + * <pre> + * Buffer b = BufferUtils.synchronizedBuffer(myBuffer); + * synchronized (b) { + * Iterator i = b.iterator(); + * while (i.hasNext()) { + * process (i.next()); + * } + * } + * </pre> * - * @param b the buffer to synchronize - * @return a synchronized buffer backed by that buffer + * @param buffer the buffer to synchronize, must not be null + * @return a synchronized buffer backed by that buffer + * @throws IllegalArgumentException if the Buffer is null */ - public static Buffer synchronizedBuffer(final Buffer b) { - return new SynchronizedBuffer(b); + public static Buffer synchronizedBuffer(final Buffer buffer) { + return new SynchronizedBuffer(buffer); } - /** - * Returns a synchronized buffer backed by the given buffer that will - * block on {@link Buffer#get()} and {@link Buffer#remove()} operations. - * If the buffer is empty, then the {@link Buffer#get()} and - * {@link Buffer#remove()} operations will block until new elements - * are added to the buffer, rather than immediately throwing a - * <Code>BufferUnderflowException</Code>. + * Returns a synchronized buffer backed by the given buffer that will + * block on {@link Buffer#get()} and {@link Buffer#remove()} operations. + * If the buffer is empty, then the {@link Buffer#get()} and + * {@link Buffer#remove()} operations will block until new elements + * are added to the buffer, rather than immediately throwing a + * <code>BufferUnderflowException</code>. * - * @param buf the buffer to synchronize - * @return a blocking buffer backed by that buffer + * @param buffer the buffer to synchronize, must not be null + * @return a blocking buffer backed by that buffer + * @throws IllegalArgumentException if the Buffer is null */ - public static Buffer blockingBuffer(Buffer buf) { - return new SynchronizedBuffer(buf) { + public static Buffer blockingBuffer(Buffer buffer) { + return new SynchronizedBuffer(buffer) { public synchronized boolean add(Object o) { boolean r = collection.add(o); @@ -152,38 +153,38 @@ }; } - /** - * Returns an unmodifiable buffer backed by the given buffer. + * Returns an unmodifiable buffer backed by the given buffer. * - * @param b the buffer to make unmodifiable - * @return an unmodifiable buffer backed by that buffer + * @param buffer the buffer to make unmodifiable, must not be null + * @return an unmodifiable buffer backed by that buffer + * @throws IllegalArgumentException if the Buffer is null */ - public static Buffer unmodifiableBuffer(Buffer b) { - return new UnmodifiableBuffer(b); + public static Buffer unmodifiableBuffer(Buffer buffer) { + return new UnmodifiableBuffer(buffer); } - /** - * Returns a predicated buffer backed by the given buffer. Elements are - * evaluated with the given predicate before being added to the buffer. - * If the predicate evaluation returns false, then an - * IllegalArgumentException is raised and the element is not added to - * the buffer. + * Returns a predicated buffer backed by the given buffer. Elements are + * evaluated with the given predicate before being added to the buffer. + * If the predicate evaluation returns false, then an + * IllegalArgumentException is raised and the element is not added to + * the buffer. * - * @param buf the buffer to predicate - * @param p the predicate used to evaluate new elements - * @return a predicated buffer + * @param buffer the buffer to predicate, must not be null + * @param predicate the predicate used to evaluate new elements, must not be null + * @return a predicated buffer + * @throws IllegalArgumentException if the Buffer or Predicate is null */ - public static Buffer predicatedBuffer(Buffer buf, final Predicate p) { - return new PredicatedBuffer(buf, p); + public static Buffer predicatedBuffer(Buffer buffer, final Predicate predicate) { + return new PredicatedBuffer(buffer, predicate); } - private static class SynchronizedBuffer - extends CollectionUtils.SynchronizedCollection - implements Buffer { + static class SynchronizedBuffer + extends CollectionUtils.SynchronizedCollection + implements Buffer { public SynchronizedBuffer(Buffer b) { super(b); @@ -199,9 +200,9 @@ } - private static class UnmodifiableBuffer - extends CollectionUtils.UnmodifiableCollection - implements Buffer { + static class UnmodifiableBuffer + extends CollectionUtils.UnmodifiableCollection + implements Buffer { public UnmodifiableBuffer(Buffer b) { super(b); @@ -218,9 +219,9 @@ } - private static class PredicatedBuffer - extends CollectionUtils.PredicatedCollection - implements Buffer { + static class PredicatedBuffer + extends CollectionUtils.PredicatedCollection + implements Buffer { public PredicatedBuffer(Buffer b, Predicate p) { super(b, p); 1.11 +102 -109 jakarta-commons/collections/src/java/org/apache/commons/collections/ListUtils.java Index: ListUtils.java =================================================================== RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/ListUtils.java,v retrieving revision 1.10 retrieving revision 1.11 diff -u -r1.10 -r1.11 --- ListUtils.java 18 Aug 2002 20:11:37 -0000 1.10 +++ ListUtils.java 13 Oct 2002 00:38:36 -0000 1.11 @@ -65,7 +65,6 @@ import java.util.Iterator; import java.util.List; import java.util.ListIterator; - /** * Contains static utility methods and decorators for {@link List} * instances. @@ -74,9 +73,9 @@ * @author <a href="mailto:[EMAIL PROTECTED]">Federico Barbieri</a> * @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a> * @author Paul Jack + * @author Stephen Colebourne */ -public class ListUtils -{ +public class ListUtils { /** * Please don't ever instantiate a <Code>ListUtils</Code>. @@ -85,95 +84,86 @@ } /** - * Returns a new list containing all elements that are contained in - * both given lists. + * Returns a new list containing all elements that are contained in + * both given lists. * - * @param list1 the first list - * @param list2 the second list - * @return the intersection of those two lists - * @throws NullPointerException if either list is null + * @param list1 the first list + * @param list2 the second list + * @return the intersection of those two lists + * @throws NullPointerException if either list is null */ - public static List intersection( final List list1, final List list2 ) - { + public static List intersection(final List list1, final List list2) { final ArrayList result = new ArrayList(); final Iterator iterator = list2.iterator(); - while( iterator.hasNext() ) - { + while (iterator.hasNext()) { final Object o = iterator.next(); - if ( list1.contains( o ) ) - { - result.add( o ); + if (list1.contains(o)) { + result.add(o); } } return result; } - /** - * Subtracts all elements in the second list from the first list, - * placing the results in a new list. - * This differs from {@link List#removeAll(Collection)} in that - * cardinality is respected; if <Code>list1</Code> contains two - * occurrences of <Code>null</Code> and <Code>list2</Code> only - * contains one occurrence, then the returned list will still contain - * one occurrence. + * Subtracts all elements in the second list from the first list, + * placing the results in a new list. + * This differs from {@link List#removeAll(Collection)} in that + * cardinality is respected; if <Code>list1</Code> contains two + * occurrences of <Code>null</Code> and <Code>list2</Code> only + * contains one occurrence, then the returned list will still contain + * one occurrence. * - * @param list1 the list to subtract from - * @param list2 the lsit to subtract - * @return a new list containing the results - * @throws NullPointerException if either list is null + * @param list1 the list to subtract from + * @param list2 the lsit to subtract + * @return a new list containing the results + * @throws NullPointerException if either list is null */ - public static List subtract( final List list1, final List list2 ) - { - final ArrayList result = new ArrayList( list1 ); + public static List subtract(final List list1, final List list2) { + final ArrayList result = new ArrayList(list1); final Iterator iterator = list2.iterator(); - while( iterator.hasNext() ) - { - result.remove( iterator.next() ); + while (iterator.hasNext()) { + result.remove(iterator.next()); } return result; } /** - * Returns the sum of the given lists. This is their intersection - * subtracted from their union. + * Returns the sum of the given lists. This is their intersection + * subtracted from their union. * - * @param list1 the first list - * @param list2 the second list - * @return a new list containing the sum of those lists - * @throws NullPointerException if either list is null + * @param list1 the first list + * @param list2 the second list + * @return a new list containing the sum of those lists + * @throws NullPointerException if either list is null */ - public static List sum( final List list1, final List list2 ) - { - return subtract( union( list1, list2 ), - intersection( list1, list2 ) ); + public static List sum(final List list1, final List list2) { + return subtract(union(list1, list2), intersection(list1, list2)); } - /** - * Returns a new list containing the second list appended to the - * first list. The {@link List#addAll(Collection)} operation is - * used to append the two given lists into a new list. + * Returns a new list containing the second list appended to the + * first list. The {@link List#addAll(Collection)} operation is + * used to append the two given lists into a new list. * - * @param list1 the first list - * @param list2 the second list - * @return a new list containing the union of those lists - * @throws NullPointerException if either list is null + * @param list1 the first list + * @param list2 the second list + * @return a new list containing the union of those lists + * @throws NullPointerException if either list is null */ - public static List union( final List list1, final List list2 ) - { - final ArrayList result = new ArrayList( list1 ); - result.addAll( list2 ); + public static List union(final List list1, final List list2) { + final ArrayList result = new ArrayList(list1); + result.addAll(list2); return result; } - static class ListIteratorWrapper implements ListIterator { + static class ListIteratorWrapper + implements ListIterator { final protected ListIterator iterator; @@ -220,8 +210,9 @@ } - static class PredicatedList extends CollectionUtils.PredicatedCollection - implements List { + static class PredicatedList + extends CollectionUtils.PredicatedCollection + implements List { public PredicatedList(List list, Predicate p) { super(list, p); @@ -290,8 +281,9 @@ } - static class FixedSizeList extends CollectionUtils.UnmodifiableCollection - implements List { + static class FixedSizeList + extends CollectionUtils.UnmodifiableCollection + implements List { public FixedSizeList(List list) { super(list); @@ -357,15 +349,16 @@ } - static class LazyList extends CollectionUtils.CollectionWrapper - implements List { + static class LazyList + extends CollectionUtils.CollectionWrapper + implements List { - final protected Factory factory; + protected final Factory factory; public LazyList(List list, Factory factory) { super(list); if (factory == null) { - throw new IllegalArgumentException("factory may not be null"); + throw new IllegalArgumentException("Factory must not be null"); } this.factory = factory; } @@ -452,65 +445,65 @@ /** - * 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. - * It is important not to use the original list after invoking this - * method, as it is a backdoor for adding unvalidated objects. + * 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. + * It is important not to use the original list after invoking this + * method, as it is a backdoor for adding unvalidated objects. * - * @param list the list to predicate - * @param p the predicate for the list - * @return a predicated list backed by the given list + * @param list the list to predicate, must not be null + * @param predicate the predicate for the list, must not be null + * @return a predicated list backed by the given list + * @throws IllegalArgumentException if the List or Predicate is null */ - public static List predicatedList(List list, Predicate p) { - return new PredicatedList(list, p); + public static List predicatedList(List list, Predicate predicate) { + return new PredicatedList(list, predicate); } - /** - * Returns a "lazy" list whose elements will be created on demand.<P> - * <P> - * When the index passed to the returned list's {@link List#get(int) get} - * method is greater than the list's size, then the factory will be used - * to create a new object and that object will be inserted at that index. - * <P> - * For instance: + * Returns a "lazy" list whose elements will be created on demand.<P> + * <p> + * When the index passed to the returned list's {@link List#get(int) get} + * method is greater than the list's size, then the factory will be used + * to create a new object and that object will be inserted at that index. + * <p> + * For instance: * - * <Pre> - * Factory factory = new Factory() { - * public Object create() { - * return new Date(); - * } - * } - * List lazy = ListUtils.lazyList(new ArrayList(), factory); - * Object obj = lazy.get(3); - * </Pre> + * <pre> + * Factory factory = new Factory() { + * public Object create() { + * return new Date(); + * } + * } + * List lazy = ListUtils.lazyList(new ArrayList(), factory); + * Object obj = lazy.get(3); + * </pre> * - * After the above code is executed, <Code>obj</Code> will contain - * a new <Code>Date</Code> instance. Furthermore, that <Code>Date</Code> - * instance is the fourth element in the list. The first, second, - * and third element are all set to <Code>null</Code>.<P> + * After the above code is executed, <code>obj</code> will contain + * a new <code>Date</code> instance. Furthermore, that <code>Date</code> + * instance is the fourth element in the list. The first, second, + * and third element are all set to <code>null</code>. * - * @param list the list to make lazy - * @param factory the factory for creating new objects - * @return a lazy list backed by the given list + * @param list the list to make lazy, must not be null + * @param factory the factory for creating new objects, must not be null + * @return a lazy list backed by the given list + * @throws IllegalArgumentException if the List or Factory is null */ public static List lazyList(List list, Factory factory) { return new LazyList(list, factory); } - /** - * Returns a fixed-sized list backed by the given list. - * Elements may not be added or removed from the returned list, but - * existing elements can be changed (for instance, via the - * {@link List#set(int,Object)} method). + * Returns a fixed-sized list backed by the given list. + * Elements may not be added or removed from the returned list, but + * existing elements can be changed (for instance, via the + * {@link List#set(int,Object)} method). * - * @param list the list whose size to fix - * @return a fixed-size list backed by that list + * @param list the list whose size to fix, must not be null + * @return a fixed-size list backed by that list + * @throws IllegalArgumentException if the List is null */ public static List fixedSizeList(List list) { return new FixedSizeList(list); } - } 1.18 +45 -39 jakarta-commons/collections/src/java/org/apache/commons/collections/CollectionUtils.java Index: CollectionUtils.java =================================================================== RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/CollectionUtils.java,v retrieving revision 1.17 retrieving revision 1.18 diff -u -r1.17 -r1.18 --- CollectionUtils.java 12 Oct 2002 21:59:45 -0000 1.17 +++ CollectionUtils.java 13 Oct 2002 00:38:36 -0000 1.18 @@ -75,7 +75,6 @@ import org.apache.commons.collections.iterators.ArrayIterator; import org.apache.commons.collections.iterators.EnumerationIterator; - /** * A set of {@link Collection} related utility methods. * @@ -727,33 +726,37 @@ } /** - * Base class for collection decorators. I decided to do it this way - * because it seemed to result in the most reuse. - * - * Inner class tree looks like: + * Base class for collection decorators. I decided to do it this way + * because it seemed to result in the most reuse. + * + * Inner class tree looks like: + * <pre> * CollectionWrapper * PredicatedCollection * PredicatedSet * PredicatedList * PredicatedBag - * BoundedCollection - * BoundedSet - * BoundedList - * BoundedBag + * PredicatedBuffer + * UnmodifiableCollection + * UnmodifiableBag + * UnmodifiableBuffer * LazyCollection * LazyList * LazyBag * SynchronizedCollection * SynchronizedBuffer * SynchronizedBag + * SynchronizedBuffer + * </pre> */ - static class CollectionWrapper implements Collection { + static class CollectionWrapper + implements Collection { - final protected Collection collection; + protected final Collection collection; public CollectionWrapper(Collection collection) { if (collection == null) { - throw new IllegalArgumentException("Collection must not be null."); + throw new IllegalArgumentException("Collection must not be null"); } this.collection = collection; } @@ -826,14 +829,15 @@ } - static class PredicatedCollection extends CollectionWrapper { + static class PredicatedCollection + extends CollectionWrapper { - final protected Predicate predicate; + protected final Predicate predicate; public PredicatedCollection(Collection c, Predicate p) { super(c); if (p == null) { - throw new IllegalArgumentException("Predicate must not be null."); + throw new IllegalArgumentException("Predicate must not be null"); } this.predicate = p; for (Iterator iter = c.iterator(); iter.hasNext(); ) { @@ -846,7 +850,6 @@ return collection.add(o); } - public boolean addAll(Collection c2) { for (Iterator iter = c2.iterator(); iter.hasNext(); ) { validate(iter.next()); @@ -854,18 +857,17 @@ return collection.addAll(c2); } - protected void validate(Object o) { if (!predicate.evaluate(o)) { - throw new IllegalArgumentException("Object failed predicate."); + throw new IllegalArgumentException("Cannot add Object - Predicate rejected it"); } } } - static class UnmodifiableCollection extends CollectionWrapper { - + static class UnmodifiableCollection + extends CollectionWrapper { public UnmodifiableCollection(Collection c) { super(c); @@ -904,11 +906,11 @@ static class SynchronizedCollection { - final protected Collection collection; + protected final Collection collection; public SynchronizedCollection(Collection collection) { if (collection == null) { - throw new IllegalArgumentException("Collection must not be null."); + throw new IllegalArgumentException("Collection must not be null"); } this.collection = collection; } @@ -980,11 +982,15 @@ } - static class UnmodifiableIterator implements Iterator { + static class UnmodifiableIterator + implements Iterator { - final protected Iterator iterator; + protected final Iterator iterator; public UnmodifiableIterator(Iterator iterator) { + if (iterator == null) { + throw new IllegalArgumentException("Iterator must not be null"); + } this.iterator = iterator; } @@ -1003,19 +1009,19 @@ /** - * Returns a predicated collection backed by the given collection. - * Only objects that pass the test in the given predicate can be - * added to the collection. - * It is important not to use the original collection after invoking this - * method, as it is a backdoor for adding unvalidated objects. + * Returns a predicated collection backed by the given collection. + * Only objects that pass the test in the given predicate can be + * added to the collection. + * It is important not to use the original collection after invoking this + * method, as it is a backdoor for adding unvalidated objects. * - * @param b the collection to predicate - * @param p the predicate for the collection - * @return a predicated collection backed by the given collection + * @param collection the collection to predicate, must not be null + * @param predicate the predicate for the collection, must not be null + * @return a predicated collection backed by the given collection + * @throws IllegalArgumentException if the Collection is null */ - public static Collection predicatedCollection(Collection c, Predicate p) { - return new PredicatedCollection(c, p); + public static Collection predicatedCollection(Collection collection, Predicate predicate) { + return new PredicatedCollection(collection, predicate); } - } 1.7 +109 -108 jakarta-commons/collections/src/java/org/apache/commons/collections/BagUtils.java Index: BagUtils.java =================================================================== RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/BagUtils.java,v retrieving revision 1.6 retrieving revision 1.7 diff -u -r1.6 -r1.7 --- BagUtils.java 12 Oct 2002 22:15:18 -0000 1.6 +++ BagUtils.java 13 Oct 2002 00:38:36 -0000 1.7 @@ -60,22 +60,19 @@ */ package org.apache.commons.collections; - import java.util.Comparator; import java.util.Set; - - /** - * Provides utility methods and decorators for {@link Bag} - * and {@link SortedBag} instances.<P> + * Provides utility methods and decorators for {@link Bag} + * and {@link SortedBag} instances.<P> * - * @author Paul Jack - * @version $Id$ - * @since 2.1 + * @author Paul Jack + * @author Stephen Colebourne + * @version $Id$ + * @since 2.1 */ public class BagUtils { - /** * Prevents instantiation. */ @@ -83,8 +80,9 @@ } - static class PredicatedBag extends CollectionUtils.PredicatedCollection - implements Bag { + static class PredicatedBag + extends CollectionUtils.PredicatedCollection + implements Bag { public PredicatedBag(Bag b, Predicate p) { super(b, p); @@ -114,8 +112,8 @@ static class UnmodifiableBag - extends CollectionUtils.UnmodifiableCollection - implements Bag { + extends CollectionUtils.UnmodifiableCollection + implements Bag { public UnmodifiableBag(Bag bag) { super(bag); @@ -144,8 +142,8 @@ static class SynchronizedBag - extends CollectionUtils.SynchronizedCollection - implements Bag { + extends CollectionUtils.SynchronizedCollection + implements Bag { public SynchronizedBag(Bag bag) { super(bag); @@ -174,8 +172,9 @@ } - static class PredicatedSortedBag extends PredicatedBag - implements SortedBag { + static class PredicatedSortedBag + extends PredicatedBag + implements SortedBag { public PredicatedSortedBag(SortedBag sb, Predicate p) { super(sb, p); @@ -199,8 +198,9 @@ } - static class SynchronizedSortedBag extends SynchronizedBag - implements SortedBag { + static class SynchronizedSortedBag + extends SynchronizedBag + implements SortedBag { public SynchronizedSortedBag(SortedBag bag) { super(bag); @@ -225,8 +225,9 @@ } - static class UnmodifiableSortedBag extends UnmodifiableBag - implements SortedBag { + static class UnmodifiableSortedBag + extends UnmodifiableBag + implements SortedBag { public UnmodifiableSortedBag(SortedBag bag) { super(bag); @@ -252,121 +253,121 @@ /** - * 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. + * 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. * - * @param b the bag to predicate - * @param p the predicate for the bag - * @return a predicated bag backed by the given bag + * @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 */ - public static Bag predicatedBag(Bag b, Predicate p) { - return new PredicatedBag(b, p); + public static Bag predicatedBag(Bag bag, Predicate predicate) { + return new PredicatedBag(bag, predicate); } - /** - * Returns an unmodifiable view of the given bag. Any modification - * attempts to the returned bag will raise an - * {@link UnsupportedOperationException}. + * Returns an unmodifiable view of the given bag. Any modification + * attempts to the returned bag will raise an + * {@link UnsupportedOperationException}. * - * @param b the bag whose unmodifiable view is to be returned - * @return an unmodifiable view of that bag + * @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 */ - public static Bag unmodifiableBag(Bag b) { - return new UnmodifiableBag(b); + public static Bag unmodifiableBag(Bag bag) { + return new UnmodifiableBag(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: + * 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: * - * <Pre> - * Bag bag = BagUtils.synchronizedBag(new HashBag()); - * ... - * synchronized(bag) { - * Iterator i = bag.iterator(); // Must be in synchronized block - * while (i.hasNext()) - * foo(i.next()); - * } - * } - * </Pre> + * <pre> + * Bag bag = BagUtils.synchronizedBag(new HashBag()); + * ... + * synchronized(bag) { + * Iterator i = bag.iterator(); // Must be in synchronized block + * while (i.hasNext()) + * foo(i.next()); + * } + * } + * </pre> * - * Failure to follow this advice may result in non-deterministic - * behavior. + * Failure to follow this advice may result in non-deterministic + * behavior. * - * @param b the bag to synchronize - * @return a synchronized bag backed by that bag + * @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 */ - public static Bag synchronizedBag(Bag b) { - return new SynchronizedBag(b); + public static Bag synchronizedBag(Bag bag) { + return new SynchronizedBag(bag); } - /** - * 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. + * 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. * - * @param b the sorted bag to predicate - * @param p the predicate for the bag - * @return a predicated bag backed by the given bag + * @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 */ - public static SortedBag predicatedSortedBag(SortedBag b, Predicate p) { - return new PredicatedSortedBag(b, p); + public static SortedBag predicatedSortedBag(SortedBag bag, Predicate predicate) { + return new PredicatedSortedBag(bag, predicate); } - /** - * Returns an unmodifiable view of the given sorted bag. Any modification - * attempts to the returned bag will raise an - * {@link UnsupportedOperationException}. + * Returns an unmodifiable view of the given sorted bag. Any modification + * attempts to the returned bag will raise an + * {@link UnsupportedOperationException}. * - * @param b the bag whose unmodifiable view is to be returned - * @return an unmodifiable view of that bag + * @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 */ - public static SortedBag unmodifiableSortedBag(SortedBag b) { - return new UnmodifiableSortedBag(b); + public static SortedBag unmodifiableSortedBag(SortedBag bag) { + return new UnmodifiableSortedBag(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. - * <P> - * It is imperative that the user manually synchronize on the returned - * bag when iterating over it: + * 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: * - * <Pre> - * SortedBag bag = BagUtils.synchronizedSortedBag(new TreeBag()); - * ... - * synchronized(bag) { - * Iterator i = bag.iterator(); // Must be in synchronized block - * while (i.hasNext()) - * foo(i.next()); - * } - * } - * </Pre> + * <pre> + * SortedBag bag = BagUtils.synchronizedSortedBag(new TreeBag()); + * ... + * synchronized(bag) { + * Iterator i = bag.iterator(); // Must be in synchronized block + * while (i.hasNext()) + * foo(i.next()); + * } + * } + * </pre> * - * Failure to follow this advice may result in non-deterministic - * behavior. + * Failure to follow this advice may result in non-deterministic + * behavior. * - * @param b the bag to synchronize - * @return a synchronized bag backed by that bag + * @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 */ - public static SortedBag synchronizedSortedBag(SortedBag b) { - return new SynchronizedSortedBag(b); + public static SortedBag synchronizedSortedBag(SortedBag bag) { + return new SynchronizedSortedBag(bag); } - } 1.7 +41 -42 jakarta-commons/collections/src/java/org/apache/commons/collections/SetUtils.java Index: SetUtils.java =================================================================== RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/SetUtils.java,v retrieving revision 1.6 retrieving revision 1.7 diff -u -r1.6 -r1.7 --- SetUtils.java 12 Oct 2002 22:15:19 -0000 1.6 +++ SetUtils.java 13 Oct 2002 00:38:36 -0000 1.7 @@ -60,45 +60,44 @@ */ package org.apache.commons.collections; - import java.util.Comparator; import java.util.Set; import java.util.SortedSet; - - /** - * Provides static utility methods and decorators for {@link Set} - * and {@link SortedSet} instances. + * Provides static utility methods and decorators for {@link Set} + * and {@link SortedSet} instances. * - * @author Paul Jack - * @version $Id$ - * @since 2.1 + * @author Paul Jack + * @author Stephen Colebourne + * @version $Id$ + * @since 2.1 */ public class SetUtils { - /** - * Prevents instantiation. + * Prevents instantiation. */ private SetUtils() { } - static class PredicatedSet extends CollectionUtils.PredicatedCollection - implements Set { + static class PredicatedSet + extends CollectionUtils.PredicatedCollection + implements Set { - public PredicatedSet(Set set, Predicate p) { - super(set, p); + public PredicatedSet(Set set, Predicate predicate) { + super(set, predicate); } } - static class PredicatedSortedSet extends PredicatedSet - implements SortedSet { + static class PredicatedSortedSet + extends PredicatedSet + implements SortedSet { - public PredicatedSortedSet(SortedSet s, Predicate p) { - super(s, p); + public PredicatedSortedSet(SortedSet set, Predicate predicate) { + super(set, predicate); } public SortedSet subSet(Object o1, Object o2) { @@ -135,34 +134,34 @@ } /** - * 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. - * It is important not to use the original set after invoking this - * method, as it is a backdoor for adding unvalidated objects. + * 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. + * It is important not to use the original set after invoking this + * method, as it is a backdoor for adding unvalidated objects. * - * @param set the set to predicate - * @param p the predicate for the set - * @return a predicated set backed by the given set + * @param set the set to predicate, must not be null + * @param predicate the predicate for the set, must not be null + * @return a predicated set backed by the given set + * @throws IllegalArgumentException if the Set or Predicate is null */ - public static Set predicatedSet(Set set, Predicate p) { - return new PredicatedSet(set, p); + public static Set predicatedSet(Set set, Predicate predicate) { + return new PredicatedSet(set, predicate); } - - /** - * Returns a predicated sorted set backed by the given sorted set. - * Only objects that pass the test in the given predicate can be added - * to the sorted set. - * It is important not to use the original sorted set after invoking this - * method, as it is a backdoor for adding unvalidated objects. + * Returns a predicated sorted set backed by the given sorted set. + * Only objects that pass the test in the given predicate can be added + * to the sorted set. + * It is important not to use the original sorted set after invoking this + * method, as it is a backdoor for adding unvalidated objects. * - * @param set the sorted set to predicate - * @param p the predicate for the sorted set - * @return a predicated sorted set backed by the given sorted set + * @param set the sorted set to predicate, must not be null + * @param predicate the predicate for the sorted set, must not be null + * @return a predicated sorted set backed by the given sorted set + * @throws IllegalArgumentException if the Set or Predicate is null */ - public static SortedSet predicatedSortedSet(SortedSet set, Predicate p) { - return new PredicatedSortedSet(set, p); + public static SortedSet predicatedSortedSet(SortedSet set, Predicate predicate) { + return new PredicatedSortedSet(set, predicate); } }
-- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>