commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From scolebou...@apache.org
Subject cvs commit: jakarta-commons/collections/src/java/org/apache/commons/collections MapUtils.java BufferUtils.java ListUtils.java CollectionUtils.java BagUtils.java SetUtils.java
Date Sun, 13 Oct 2002 00:38:36 GMT
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:jstrachan@apache.org">James Strachan</a>
  -  * @author <a href="mailto:nissim@nksystems.com">Nissim Karpenstein</a>
  -  * @author <a href="mailto:knielsen@apache.org">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:jstrachan@apache.org">James Strachan</a>
  + * @author <a href="mailto:nissim@nksystems.com">Nissim Karpenstein</a>
  + * @author <a href="mailto:knielsen@apache.org">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:fede@apache.org">Federico Barbieri</a>
    * @author  <a href="mailto:donaldp@apache.org">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:commons-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:commons-dev-help@jakarta.apache.org>


Mime
View raw message