Apache
/
commons-collections
mirror of https://github.com/apache/commons-collections.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Javadoc improvements, especially exception descriptions 

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/collections/trunk@130822 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Stephen Colebourne 2002-10-13 00:38:36 +00:00
parent 332b8ff8d8
commit 4e2452d242
6 changed files with 513 additions and 497 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

217
src/java/org/apache/commons/collections/BagUtils.java
View File

@ -1,7 +1,7 @@
/* /*
* $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/BagUtils.java,v 1.6 2002/10/12 22:15:18 scolebourne Exp $ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/BagUtils.java,v 1.7 2002/10/13 00:38:36 scolebourne Exp $
* $Revision: 1.6 $ * $Revision: 1.7 $
* $Date: 2002/10/12 22:15:18 $ * $Date: 2002/10/13 00:38:36 $
* *
* ==================================================================== * ====================================================================
* *
@ -60,22 +60,19 @@
*/ */
package org.apache.commons.collections; package org.apache.commons.collections;
import java.util.Comparator; import java.util.Comparator;
import java.util.Set; import java.util.Set;
/** /**
* Provides utility methods and decorators for {@link Bag} * Provides utility methods and decorators for {@link Bag}
* and {@link SortedBag} instances.<P> * and {@link SortedBag} instances.<P>
* *
* @author Paul Jack * @author Paul Jack
* @version $Id: BagUtils.java,v 1.6 2002/10/12 22:15:18 scolebourne Exp $ * @author Stephen Colebourne
* @since 2.1 * @version $Id: BagUtils.java,v 1.7 2002/10/13 00:38:36 scolebourne Exp $
* @since 2.1
*/ */
public class BagUtils { public class BagUtils {
/** /**
* Prevents instantiation. * Prevents instantiation.
*/ */
@ -83,8 +80,9 @@ public class BagUtils {
} }
static class PredicatedBag extends CollectionUtils.PredicatedCollection static class PredicatedBag
implements Bag { extends CollectionUtils.PredicatedCollection
implements Bag {
public PredicatedBag(Bag b, Predicate p) { public PredicatedBag(Bag b, Predicate p) {
super(b, p); super(b, p);
@ -114,8 +112,8 @@ public class BagUtils {
static class UnmodifiableBag static class UnmodifiableBag
extends CollectionUtils.UnmodifiableCollection extends CollectionUtils.UnmodifiableCollection
implements Bag { implements Bag {
public UnmodifiableBag(Bag bag) { public UnmodifiableBag(Bag bag) {
super(bag); super(bag);
@ -144,8 +142,8 @@ public class BagUtils {
static class SynchronizedBag static class SynchronizedBag
extends CollectionUtils.SynchronizedCollection extends CollectionUtils.SynchronizedCollection
implements Bag { implements Bag {
public SynchronizedBag(Bag bag) { public SynchronizedBag(Bag bag) {
super(bag); super(bag);
@ -174,8 +172,9 @@ public class BagUtils {
} }
static class PredicatedSortedBag extends PredicatedBag static class PredicatedSortedBag
implements SortedBag { extends PredicatedBag
implements SortedBag {
public PredicatedSortedBag(SortedBag sb, Predicate p) { public PredicatedSortedBag(SortedBag sb, Predicate p) {
super(sb, p); super(sb, p);
@ -199,8 +198,9 @@ public class BagUtils {
} }
static class SynchronizedSortedBag extends SynchronizedBag static class SynchronizedSortedBag
implements SortedBag { extends SynchronizedBag
implements SortedBag {
public SynchronizedSortedBag(SortedBag bag) { public SynchronizedSortedBag(SortedBag bag) {
super(bag); super(bag);
@ -225,8 +225,9 @@ public class BagUtils {
} }
static class UnmodifiableSortedBag extends UnmodifiableBag static class UnmodifiableSortedBag
implements SortedBag { extends UnmodifiableBag
implements SortedBag {
public UnmodifiableSortedBag(SortedBag bag) { public UnmodifiableSortedBag(SortedBag bag) {
super(bag); super(bag);
@ -252,121 +253,121 @@ public class BagUtils {
/** /**
* Returns a predicated bag backed by the given bag. Only 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. * 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 * It is important not to use the original bag after invoking this
* method, as it is a backdoor for adding unvalidated objects. * method, as it is a backdoor for adding unvalidated objects.
* *
* @param b the bag to predicate * @param bag the bag to predicate, must not be null
* @param p the predicate for the bag * @param predicate the predicate for the bag, must not be null
* @return a predicated bag backed by the given bag * @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) { public static Bag predicatedBag(Bag bag, Predicate predicate) {
return new PredicatedBag(b, p); return new PredicatedBag(bag, predicate);
} }
/** /**
* Returns an unmodifiable view of the given bag. Any modification * Returns an unmodifiable view of the given bag. Any modification
* attempts to the returned bag will raise an * attempts to the returned bag will raise an
* {@link UnsupportedOperationException}. * {@link UnsupportedOperationException}.
* *
* @param b the bag whose unmodifiable view is to be returned * @param bag the bag whose unmodifiable view is to be returned, must not be null
* @return an unmodifiable view of that bag * @return an unmodifiable view of that bag
* @throws IllegalArgumentException if the Bag is null
*/ */
public static Bag unmodifiableBag(Bag b) { public static Bag unmodifiableBag(Bag bag) {
return new UnmodifiableBag(b); return new UnmodifiableBag(bag);
} }
/** /**
* Returns a synchronized (thread-safe) bag backed by the given bag. * Returns a synchronized (thread-safe) bag backed by the given bag.
* In order to guarantee serial access, it is critical that all * In order to guarantee serial access, it is critical that all
* access to the backing bag is accomplished through the returned bag. * access to the backing bag is accomplished through the returned bag.
* <P> * <p>
* It is imperative that the user manually synchronize on the returned * It is imperative that the user manually synchronize on the returned
* bag when iterating over it: * bag when iterating over it:
* *
* <Pre> * <pre>
* Bag bag = BagUtils.synchronizedBag(new HashBag()); * Bag bag = BagUtils.synchronizedBag(new HashBag());
* ... * ...
* synchronized(bag) { * synchronized(bag) {
* Iterator i = bag.iterator(); // Must be in synchronized block * Iterator i = bag.iterator(); // Must be in synchronized block
* while (i.hasNext()) * while (i.hasNext())
* foo(i.next()); * foo(i.next());
* } * }
* } * }
* </Pre> * </pre>
* *
* Failure to follow this advice may result in non-deterministic * Failure to follow this advice may result in non-deterministic
* behavior. * behavior.
* *
* @param b the bag to synchronize * @param bag the bag to synchronize, must not be null
* @return a synchronized bag backed by that bag * @return a synchronized bag backed by that bag
* @throws IllegalArgumentException if the Bag is null
*/ */
public static Bag synchronizedBag(Bag b) { public static Bag synchronizedBag(Bag bag) {
return new SynchronizedBag(b); return new SynchronizedBag(bag);
} }
/** /**
* Returns a predicated sorted bag backed by the given sorted bag. * Returns a predicated sorted bag backed by the given sorted bag.
* Only objects that pass the test in the given predicate can be * Only objects that pass the test in the given predicate can be
* added to the bag. * added to the bag.
* It is important not to use the original bag after invoking this * It is important not to use the original bag after invoking this
* method, as it is a backdoor for adding unvalidated objects. * method, as it is a backdoor for adding unvalidated objects.
* *
* @param b the sorted bag to predicate * @param bag the sorted bag to predicate, must not be null
* @param p the predicate for the bag * @param predicate the predicate for the bag, must not be null
* @return a predicated bag backed by the given bag * @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) { public static SortedBag predicatedSortedBag(SortedBag bag, Predicate predicate) {
return new PredicatedSortedBag(b, p); return new PredicatedSortedBag(bag, predicate);
} }
/** /**
* Returns an unmodifiable view of the given sorted bag. Any modification * Returns an unmodifiable view of the given sorted bag. Any modification
* attempts to the returned bag will raise an * attempts to the returned bag will raise an
* {@link UnsupportedOperationException}. * {@link UnsupportedOperationException}.
* *
* @param b the bag whose unmodifiable view is to be returned * @param bag the bag whose unmodifiable view is to be returned, must not be null
* @return an unmodifiable view of that bag * @return an unmodifiable view of that bag
* @throws IllegalArgumentException if the SortedBag is null
*/ */
public static SortedBag unmodifiableSortedBag(SortedBag b) { public static SortedBag unmodifiableSortedBag(SortedBag bag) {
return new UnmodifiableSortedBag(b); return new UnmodifiableSortedBag(bag);
} }
/** /**
* Returns a synchronized (thread-safe) sorted bag backed by the given * Returns a synchronized (thread-safe) sorted bag backed by the given
* sorted bag. * sorted bag.
* In order to guarantee serial access, it is critical that all * In order to guarantee serial access, it is critical that all
* access to the backing bag is accomplished through the returned bag. * access to the backing bag is accomplished through the returned bag.
* <P> * <p>
* It is imperative that the user manually synchronize on the returned * It is imperative that the user manually synchronize on the returned
* bag when iterating over it: * bag when iterating over it:
* *
* <Pre> * <pre>
* SortedBag bag = BagUtils.synchronizedSortedBag(new TreeBag()); * SortedBag bag = BagUtils.synchronizedSortedBag(new TreeBag());
* ... * ...
* synchronized(bag) { * synchronized(bag) {
* Iterator i = bag.iterator(); // Must be in synchronized block * Iterator i = bag.iterator(); // Must be in synchronized block
* while (i.hasNext()) * while (i.hasNext())
* foo(i.next()); * foo(i.next());
* } * }
* } * }
* </Pre> * </pre>
* *
* Failure to follow this advice may result in non-deterministic * Failure to follow this advice may result in non-deterministic
* behavior. * behavior.
* *
* @param b the bag to synchronize * @param bag the bag to synchronize, must not be null
* @return a synchronized bag backed by that bag * @return a synchronized bag backed by that bag
* @throws IllegalArgumentException if the SortedBag is null
*/ */
public static SortedBag synchronizedSortedBag(SortedBag b) { public static SortedBag synchronizedSortedBag(SortedBag bag) {
return new SynchronizedSortedBag(b); return new SynchronizedSortedBag(bag);
} }
} }

131
src/java/org/apache/commons/collections/BufferUtils.java
View File

@ -1,7 +1,7 @@
/* /*
* $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/BufferUtils.java,v 1.8 2002/10/12 22:15:18 scolebourne Exp $ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/BufferUtils.java,v 1.9 2002/10/13 00:38:36 scolebourne Exp $
* $Revision: 1.8 $ * $Revision: 1.9 $
* $Date: 2002/10/12 22:15:18 $ * $Date: 2002/10/13 00:38:36 $
* *
* ==================================================================== * ====================================================================
* *
@ -60,61 +60,62 @@
*/ */
package org.apache.commons.collections; package org.apache.commons.collections;
import java.util.Collection; 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 * @author Paul Jack
* @version $Id: BufferUtils.java,v 1.8 2002/10/12 22:15:18 scolebourne Exp $ * @author Stephen Colebourne
* @since 2.1 * @version $Id: BufferUtils.java,v 1.9 2002/10/13 00:38:36 scolebourne Exp $
* @since 2.1
*/ */
public class BufferUtils { public class BufferUtils {
/**
* Restrictive constructor
*/
private BufferUtils() { private BufferUtils() {
} }
/** /**
* Returns a synchronized buffer backed by the given buffer. * Returns a synchronized buffer backed by the given buffer.
* Much like the synchronized collections returned by * Much like the synchronized collections returned by
* {@link java.util.Collections}, you must manually synchronize on * {@link java.util.Collections}, you must manually synchronize on
* the returned buffer's iterator to avoid non-deterministic behavior: * the returned buffer's iterator to avoid non-deterministic behavior:
* *
* <Pre> * <pre>
* Buffer b = BufferUtils.synchronizedBuffer(myBuffer); * Buffer b = BufferUtils.synchronizedBuffer(myBuffer);
* synchronized (b) { * synchronized (b) {
* Iterator i = b.iterator(); * Iterator i = b.iterator();
* while (i.hasNext()) { * while (i.hasNext()) {
* process (i.next()); * process (i.next());
* } * }
* } * }
* </Pre> * </pre>
* *
* @param b the buffer to synchronize * @param buffer the buffer to synchronize, must not be null
* @return a synchronized buffer backed by that buffer * @return a synchronized buffer backed by that buffer
* @throws IllegalArgumentException if the Buffer is null
*/ */
public static Buffer synchronizedBuffer(final Buffer b) { public static Buffer synchronizedBuffer(final Buffer buffer) {
return new SynchronizedBuffer(b); return new SynchronizedBuffer(buffer);
} }
/** /**
* Returns a synchronized buffer backed by the given buffer that will * Returns a synchronized buffer backed by the given buffer that will
* block on {@link Buffer#get()} and {@link Buffer#remove()} operations. * block on {@link Buffer#get()} and {@link Buffer#remove()} operations.
* If the buffer is empty, then the {@link Buffer#get()} and * If the buffer is empty, then the {@link Buffer#get()} and
* {@link Buffer#remove()} operations will block until new elements * {@link Buffer#remove()} operations will block until new elements
* are added to the buffer, rather than immediately throwing a * are added to the buffer, rather than immediately throwing a
* <Code>BufferUnderflowException</Code>. * <code>BufferUnderflowException</code>.
* *
* @param buf the buffer to synchronize * @param buffer the buffer to synchronize, must not be null
* @return a blocking buffer backed by that buffer * @return a blocking buffer backed by that buffer
* @throws IllegalArgumentException if the Buffer is null
*/ */
public static Buffer blockingBuffer(Buffer buf) { public static Buffer blockingBuffer(Buffer buffer) {
return new SynchronizedBuffer(buf) { return new SynchronizedBuffer(buffer) {
public synchronized boolean add(Object o) { public synchronized boolean add(Object o) {
boolean r = collection.add(o); boolean r = collection.add(o);
@ -152,38 +153,38 @@ public class BufferUtils {
}; };
} }
/** /**
* 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 * @param buffer the buffer to make unmodifiable, must not be null
* @return an unmodifiable buffer backed by that buffer * @return an unmodifiable buffer backed by that buffer
* @throws IllegalArgumentException if the Buffer is null
*/ */
public static Buffer unmodifiableBuffer(Buffer b) { public static Buffer unmodifiableBuffer(Buffer buffer) {
return new UnmodifiableBuffer(b); return new UnmodifiableBuffer(buffer);
} }
/** /**
* Returns a predicated buffer backed by the given buffer. Elements are * Returns a predicated buffer backed by the given buffer. Elements are
* evaluated with the given predicate before being added to the buffer. * evaluated with the given predicate before being added to the buffer.
* If the predicate evaluation returns false, then an * If the predicate evaluation returns false, then an
* IllegalArgumentException is raised and the element is not added to * IllegalArgumentException is raised and the element is not added to
* the buffer. * the buffer.
* *
* @param buf the buffer to predicate * @param buffer the buffer to predicate, must not be null
* @param p the predicate used to evaluate new elements * @param predicate the predicate used to evaluate new elements, must not be null
* @return a predicated buffer * @return a predicated buffer
* @throws IllegalArgumentException if the Buffer or Predicate is null
*/ */
public static Buffer predicatedBuffer(Buffer buf, final Predicate p) { public static Buffer predicatedBuffer(Buffer buffer, final Predicate predicate) {
return new PredicatedBuffer(buf, p); return new PredicatedBuffer(buffer, predicate);
} }
private static class SynchronizedBuffer static class SynchronizedBuffer
extends CollectionUtils.SynchronizedCollection extends CollectionUtils.SynchronizedCollection
implements Buffer { implements Buffer {
public SynchronizedBuffer(Buffer b) { public SynchronizedBuffer(Buffer b) {
super(b); super(b);
@ -199,9 +200,9 @@ public class BufferUtils {
} }
private static class UnmodifiableBuffer static class UnmodifiableBuffer
extends CollectionUtils.UnmodifiableCollection extends CollectionUtils.UnmodifiableCollection
implements Buffer { implements Buffer {
public UnmodifiableBuffer(Buffer b) { public UnmodifiableBuffer(Buffer b) {
super(b); super(b);
@ -218,9 +219,9 @@ public class BufferUtils {
} }
private static class PredicatedBuffer static class PredicatedBuffer
extends CollectionUtils.PredicatedCollection extends CollectionUtils.PredicatedCollection
implements Buffer { implements Buffer {
public PredicatedBuffer(Buffer b, Predicate p) { public PredicatedBuffer(Buffer b, Predicate p) {
super(b, p); super(b, p);

84
src/java/org/apache/commons/collections/CollectionUtils.java
View File

@ -1,7 +1,7 @@
/* /*
* $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/CollectionUtils.java,v 1.17 2002/10/12 21:59:45 scolebourne Exp $ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/CollectionUtils.java,v 1.18 2002/10/13 00:38:36 scolebourne Exp $
* $Revision: 1.17 $ * $Revision: 1.18 $
* $Date: 2002/10/12 21:59:45 $ * $Date: 2002/10/13 00:38:36 $
* *
* ==================================================================== * ====================================================================
* *
@ -75,7 +75,6 @@ import java.util.Set;
import org.apache.commons.collections.iterators.ArrayIterator; import org.apache.commons.collections.iterators.ArrayIterator;
import org.apache.commons.collections.iterators.EnumerationIterator; import org.apache.commons.collections.iterators.EnumerationIterator;
/** /**
* A set of {@link Collection} related utility methods. * A set of {@link Collection} related utility methods.
* *
@ -84,7 +83,7 @@ import org.apache.commons.collections.iterators.EnumerationIterator;
* @author Paul Jack * @author Paul Jack
* @author Stephen Colebourne * @author Stephen Colebourne
* @author Steve Downey * @author Steve Downey
* @version $Revision: 1.17 $ $Date: 2002/10/12 21:59:45 $ * @version $Revision: 1.18 $ $Date: 2002/10/13 00:38:36 $
*/ */
public class CollectionUtils { public class CollectionUtils {
@ -727,33 +726,37 @@ public class CollectionUtils {
} }
/** /**
* Base class for collection decorators. I decided to do it this way * Base class for collection decorators. I decided to do it this way
* because it seemed to result in the most reuse. * because it seemed to result in the most reuse.
* *
* Inner class tree looks like: * Inner class tree looks like:
* <pre>
* CollectionWrapper * CollectionWrapper
* PredicatedCollection * PredicatedCollection
* PredicatedSet * PredicatedSet
* PredicatedList * PredicatedList
* PredicatedBag * PredicatedBag
* BoundedCollection * PredicatedBuffer
* BoundedSet * UnmodifiableCollection
* BoundedList * UnmodifiableBag
* BoundedBag * UnmodifiableBuffer
* LazyCollection * LazyCollection
* LazyList * LazyList
* LazyBag * LazyBag
* SynchronizedCollection * SynchronizedCollection
* SynchronizedBuffer * SynchronizedBuffer
* SynchronizedBag * 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) { public CollectionWrapper(Collection collection) {
if (collection == null) { if (collection == null) {
throw new IllegalArgumentException("Collection must not be null."); throw new IllegalArgumentException("Collection must not be null");
} }
this.collection = collection; this.collection = collection;
} }
@ -826,14 +829,15 @@ public class CollectionUtils {
} }
static class PredicatedCollection extends CollectionWrapper { static class PredicatedCollection
extends CollectionWrapper {
final protected Predicate predicate; protected final Predicate predicate;
public PredicatedCollection(Collection c, Predicate p) { public PredicatedCollection(Collection c, Predicate p) {
super(c); super(c);
if (p == null) { if (p == null) {
throw new IllegalArgumentException("Predicate must not be null."); throw new IllegalArgumentException("Predicate must not be null");
} }
this.predicate = p; this.predicate = p;
for (Iterator iter = c.iterator(); iter.hasNext(); ) { for (Iterator iter = c.iterator(); iter.hasNext(); ) {
@ -846,7 +850,6 @@ public class CollectionUtils {
return collection.add(o); return collection.add(o);
} }
public boolean addAll(Collection c2) { public boolean addAll(Collection c2) {
for (Iterator iter = c2.iterator(); iter.hasNext(); ) { for (Iterator iter = c2.iterator(); iter.hasNext(); ) {
validate(iter.next()); validate(iter.next());
@ -854,18 +857,17 @@ public class CollectionUtils {
return collection.addAll(c2); return collection.addAll(c2);
} }
protected void validate(Object o) { protected void validate(Object o) {
if (!predicate.evaluate(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) { public UnmodifiableCollection(Collection c) {
super(c); super(c);
@ -904,11 +906,11 @@ public class CollectionUtils {
static class SynchronizedCollection { static class SynchronizedCollection {
final protected Collection collection; protected final Collection collection;
public SynchronizedCollection(Collection collection) { public SynchronizedCollection(Collection collection) {
if (collection == null) { if (collection == null) {
throw new IllegalArgumentException("Collection must not be null."); throw new IllegalArgumentException("Collection must not be null");
} }
this.collection = collection; this.collection = collection;
} }
@ -980,11 +982,15 @@ public class CollectionUtils {
} }
static class UnmodifiableIterator implements Iterator { static class UnmodifiableIterator
implements Iterator {
final protected Iterator iterator; protected final Iterator iterator;
public UnmodifiableIterator(Iterator iterator) { public UnmodifiableIterator(Iterator iterator) {
if (iterator == null) {
throw new IllegalArgumentException("Iterator must not be null");
}
this.iterator = iterator; this.iterator = iterator;
} }
@ -1003,19 +1009,19 @@ public class CollectionUtils {
/** /**
* Returns a predicated collection backed by the given collection. * Returns a predicated collection backed by the given collection.
* Only objects that pass the test in the given predicate can be * Only objects that pass the test in the given predicate can be
* added to the collection. * added to the collection.
* It is important not to use the original collection after invoking this * It is important not to use the original collection after invoking this
* method, as it is a backdoor for adding unvalidated objects. * method, as it is a backdoor for adding unvalidated objects.
* *
* @param b the collection to predicate * @param collection the collection to predicate, must not be null
* @param p the predicate for the collection * @param predicate the predicate for the collection, must not be null
* @return a predicated collection backed by the given collection * @return a predicated collection backed by the given collection
* @throws IllegalArgumentException if the Collection is null
*/ */
public static Collection predicatedCollection(Collection c, Predicate p) { public static Collection predicatedCollection(Collection collection, Predicate predicate) {
return new PredicatedCollection(c, p); return new PredicatedCollection(collection, predicate);
} }
} }

211
src/java/org/apache/commons/collections/ListUtils.java
View File

@ -1,7 +1,7 @@
/* /*
* $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/ListUtils.java,v 1.10 2002/08/18 20:11:37 pjack Exp $ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/ListUtils.java,v 1.11 2002/10/13 00:38:36 scolebourne Exp $
* $Revision: 1.10 $ * $Revision: 1.11 $
* $Date: 2002/08/18 20:11:37 $ * $Date: 2002/10/13 00:38:36 $
* *
* ==================================================================== * ====================================================================
* *
@ -65,7 +65,6 @@ import java.util.Collection;
import java.util.Iterator; import java.util.Iterator;
import java.util.List; import java.util.List;
import java.util.ListIterator; import java.util.ListIterator;
/** /**
* Contains static utility methods and decorators for {@link List} * Contains static utility methods and decorators for {@link List}
* instances. * instances.
@ -74,9 +73,9 @@ import java.util.ListIterator;
* @author <a href="mailto:fede@apache.org">Federico Barbieri</a> * @author <a href="mailto:fede@apache.org">Federico Barbieri</a>
* @author <a href="mailto:donaldp@apache.org">Peter Donald</a> * @author <a href="mailto:donaldp@apache.org">Peter Donald</a>
* @author Paul Jack * @author Paul Jack
* @author Stephen Colebourne
*/ */
public class ListUtils public class ListUtils {
{
/** /**
* Please don't ever instantiate a <Code>ListUtils</Code>. * Please don't ever instantiate a <Code>ListUtils</Code>.
@ -85,95 +84,86 @@ public class ListUtils
} }
/** /**
* Returns a new list containing all elements that are contained in * Returns a new list containing all elements that are contained in
* both given lists. * both given lists.
* *
* @param list1 the first list * @param list1 the first list
* @param list2 the second list * @param list2 the second list
* @return the intersection of those two lists * @return the intersection of those two lists
* @throws NullPointerException if either list is null * @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 ArrayList result = new ArrayList();
final Iterator iterator = list2.iterator(); final Iterator iterator = list2.iterator();
while( iterator.hasNext() ) while (iterator.hasNext()) {
{
final Object o = iterator.next(); final Object o = iterator.next();
if ( list1.contains( o ) ) if (list1.contains(o)) {
{ result.add(o);
result.add( o );
} }
} }
return result; return result;
} }
/** /**
* Subtracts all elements in the second list from the first list, * Subtracts all elements in the second list from the first list,
* placing the results in a new list. * placing the results in a new list.
* This differs from {@link List#removeAll(Collection)} in that * This differs from {@link List#removeAll(Collection)} in that
* cardinality is respected; if <Code>list1</Code> contains two * cardinality is respected; if <Code>list1</Code> contains two
* occurrences of <Code>null</Code> and <Code>list2</Code> only * occurrences of <Code>null</Code> and <Code>list2</Code> only
* contains one occurrence, then the returned list will still contain * contains one occurrence, then the returned list will still contain
* one occurrence. * one occurrence.
* *
* @param list1 the list to subtract from * @param list1 the list to subtract from
* @param list2 the lsit to subtract * @param list2 the lsit to subtract
* @return a new list containing the results * @return a new list containing the results
* @throws NullPointerException if either list is null * @throws NullPointerException if either list is null
*/ */
public static List subtract( final List list1, final List list2 ) public static List subtract(final List list1, final List list2) {
{ final ArrayList result = new ArrayList(list1);
final ArrayList result = new ArrayList( list1 );
final Iterator iterator = list2.iterator(); final Iterator iterator = list2.iterator();
while( iterator.hasNext() ) while (iterator.hasNext()) {
{ result.remove(iterator.next());
result.remove( iterator.next() );
} }
return result; return result;
} }
/** /**
* Returns the sum of the given lists. This is their intersection * Returns the sum of the given lists. This is their intersection
* subtracted from their union. * subtracted from their union.
* *
* @param list1 the first list * @param list1 the first list
* @param list2 the second list * @param list2 the second list
* @return a new list containing the sum of those lists * @return a new list containing the sum of those lists
* @throws NullPointerException if either list is null * @throws NullPointerException if either list is null
*/ */
public static List sum( final List list1, final List list2 ) public static List sum(final List list1, final List list2) {
{ return subtract(union(list1, list2), intersection(list1, list2));
return subtract( union( list1, list2 ),
intersection( list1, list2 ) );
} }
/** /**
* Returns a new list containing the second list appended to the * Returns a new list containing the second list appended to the
* first list. The {@link List#addAll(Collection)} operation is * first list. The {@link List#addAll(Collection)} operation is
* used to append the two given lists into a new list. * used to append the two given lists into a new list.
* *
* @param list1 the first list * @param list1 the first list
* @param list2 the second list * @param list2 the second list
* @return a new list containing the union of those lists * @return a new list containing the union of those lists
* @throws NullPointerException if either list is null * @throws NullPointerException if either list is null
*/ */
public static List union( final List list1, final List list2 ) public static List union(final List list1, final List list2) {
{ final ArrayList result = new ArrayList(list1);
final ArrayList result = new ArrayList( list1 ); result.addAll(list2);
result.addAll( list2 );
return result; return result;
} }
static class ListIteratorWrapper implements ListIterator { static class ListIteratorWrapper
implements ListIterator {
final protected ListIterator iterator; final protected ListIterator iterator;
@ -220,8 +210,9 @@ public class ListUtils
} }
static class PredicatedList extends CollectionUtils.PredicatedCollection static class PredicatedList
implements List { extends CollectionUtils.PredicatedCollection
implements List {
public PredicatedList(List list, Predicate p) { public PredicatedList(List list, Predicate p) {
super(list, p); super(list, p);
@ -290,8 +281,9 @@ public class ListUtils
} }
static class FixedSizeList extends CollectionUtils.UnmodifiableCollection static class FixedSizeList
implements List { extends CollectionUtils.UnmodifiableCollection
implements List {
public FixedSizeList(List list) { public FixedSizeList(List list) {
super(list); super(list);
@ -357,15 +349,16 @@ public class ListUtils
} }
static class LazyList extends CollectionUtils.CollectionWrapper static class LazyList
implements List { extends CollectionUtils.CollectionWrapper
implements List {
final protected Factory factory; protected final Factory factory;
public LazyList(List list, Factory factory) { public LazyList(List list, Factory factory) {
super(list); super(list);
if (factory == null) { if (factory == null) {
throw new IllegalArgumentException("factory may not be null"); throw new IllegalArgumentException("Factory must not be null");
} }
this.factory = factory; this.factory = factory;
} }
@ -452,65 +445,65 @@ public class ListUtils
/** /**
* Returns a predicated list backed by the given list. Only 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. * 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 * It is important not to use the original list after invoking this
* method, as it is a backdoor for adding unvalidated objects. * method, as it is a backdoor for adding unvalidated objects.
* *
* @param list the list to predicate * @param list the list to predicate, must not be null
* @param p the predicate for the list * @param predicate the predicate for the list, must not be null
* @return a predicated list backed by the given list * @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) { public static List predicatedList(List list, Predicate predicate) {
return new PredicatedList(list, p); return new PredicatedList(list, predicate);
} }
/** /**
* Returns a "lazy" list whose elements will be created on demand.<P> * Returns a "lazy" list whose elements will be created on demand.<P>
* <P> * <p>
* When the index passed to the returned list's {@link List#get(int) get} * 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 * 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. * to create a new object and that object will be inserted at that index.
* <P> * <p>
* For instance: * For instance:
* *
* <Pre> * <pre>
* Factory factory = new Factory() { * Factory factory = new Factory() {
* public Object create() { * public Object create() {
* return new Date(); * return new Date();
* } * }
* } * }
* List lazy = ListUtils.lazyList(new ArrayList(), factory); * List lazy = ListUtils.lazyList(new ArrayList(), factory);
* Object obj = lazy.get(3); * Object obj = lazy.get(3);
* </Pre> * </pre>
* *
* After the above code is executed, <Code>obj</Code> will contain * After the above code is executed, <code>obj</code> will contain
* a new <Code>Date</Code> instance. Furthermore, that <Code>Date</Code> * a new <code>Date</code> instance. Furthermore, that <code>Date</code>
* instance is the fourth element in the list. The first, second, * instance is the fourth element in the list. The first, second,
* and third element are all set to <Code>null</Code>.<P> * and third element are all set to <code>null</code>.
* *
* @param list the list to make lazy * @param list the list to make lazy, must not be null
* @param factory the factory for creating new objects * @param factory the factory for creating new objects, must not be null
* @return a lazy list backed by the given list * @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) { public static List lazyList(List list, Factory factory) {
return new LazyList(list, factory); return new LazyList(list, factory);
} }
/** /**
* Returns a fixed-sized list backed by the given list. * Returns a fixed-sized list backed by the given list.
* Elements may not be added or removed from the returned list, but * Elements may not be added or removed from the returned list, but
* existing elements can be changed (for instance, via the * existing elements can be changed (for instance, via the
* {@link List#set(int,Object)} method). * {@link List#set(int,Object)} method).
* *
* @param list the list whose size to fix * @param list the list whose size to fix, must not be null
* @return a fixed-size list backed by that list * @return a fixed-size list backed by that list
* @throws IllegalArgumentException if the List is null
*/ */
public static List fixedSizeList(List list) { public static List fixedSizeList(List list) {
return new FixedSizeList(list); return new FixedSizeList(list);
} }
} }

284
src/java/org/apache/commons/collections/MapUtils.java
View File

@ -1,7 +1,7 @@
/* /*
* $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/MapUtils.java,v 1.12 2002/08/19 21:56:18 pjack Exp $ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/MapUtils.java,v 1.13 2002/10/13 00:38:36 scolebourne Exp $
* $Revision: 1.12 $ * $Revision: 1.13 $
* $Date: 2002/08/19 21:56:18 $ * $Date: 2002/10/13 00:38:36 $
* *
* ==================================================================== * ====================================================================
* *
@ -64,29 +64,30 @@ import java.io.*;
import java.text.*; import java.text.*;
import java.text.NumberFormat; import java.text.NumberFormat;
import java.util.*; import java.util.*;
/**
/** A helper class for using {@link Map Map} instances.<P> * A helper class for using {@link Map Map} instances.<P>
* *
* It contains various typesafe methods * It contains various typesafe methods
* as well as other useful features like deep copying.<P> * as well as other useful features like deep copying.<P>
* *
* It also provides the following decorators: * It also provides the following decorators:
* *
* <UL> * <UL>
* <LI>{@link #fixedSizeMap(Map)} * <LI>{@link #fixedSizeMap(Map)}
* <LI>{@link #fixedSizeSortedMap(SortedMap)} * <LI>{@link #fixedSizeSortedMap(SortedMap)}
* <LI>{@link #lazyMap(Map,Factory)} * <LI>{@link #lazyMap(Map,Factory)}
* <LI>{@link #lazySortedMap(SortedMap,Factory)} * <LI>{@link #lazySortedMap(SortedMap,Factory)}
* <LI>{@link #predicatedMap(Map,Predicate,Predicate)} * <LI>{@link #predicatedMap(Map,Predicate,Predicate)}
* <LI>{@link #predicatedSortedMap(SortedMap,Predicate,Predicate)} * <LI>{@link #predicatedSortedMap(SortedMap,Predicate,Predicate)}
* </UL> * </UL>
* *
* @since 1.0 * @since 1.0
* @author <a href="mailto:jstrachan@apache.org">James Strachan</a> * @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
* @author <a href="mailto:nissim@nksystems.com">Nissim Karpenstein</a> * @author <a href="mailto:nissim@nksystems.com">Nissim Karpenstein</a>
* @author <a href="mailto:knielsen@apache.org">Kasper Nielsen</a> * @author <a href="mailto:knielsen@apache.org">Kasper Nielsen</a>
* @author Paul Jack * @author Paul Jack
*/ * @author Stephen Colebourne
*/
public class MapUtils { public class MapUtils {
private static int debugIndent = 0; private static int debugIndent = 0;
@ -727,22 +728,22 @@ public class MapUtils {
} }
static class PredicatedMap extends ProxyMap { static class PredicatedMap
extends ProxyMap {
final protected Predicate keyPredicate;
final protected Predicate valuePredicate;
protected final Predicate keyPredicate;
protected final Predicate valuePredicate;
public PredicatedMap(Map map, Predicate keyPred, Predicate valuePred) { public PredicatedMap(Map map, Predicate keyPred, Predicate valuePred) {
super(map); super(map);
if (map == null) { if (map == null) {
throw new IllegalArgumentException("map may not be null."); throw new IllegalArgumentException("Map must not be null");
} }
if (keyPred == null) { if (keyPred == null) {
throw new IllegalArgumentException("keyPred may not be null."); throw new IllegalArgumentException("Key Predicate must not be null");
} }
if (valuePred == 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.keyPredicate = keyPred;
this.valuePredicate = valuePred; this.valuePredicate = valuePred;
@ -778,20 +779,20 @@ public class MapUtils {
private void validate(Object key, Object value) { private void validate(Object key, Object value) {
if (!keyPredicate.evaluate(key)) { if (!keyPredicate.evaluate(key)) {
throw new IllegalArgumentException("Invalid key."); throw new IllegalArgumentException("Cannot add key - Predicate rejected it");
} }
if (!valuePredicate.evaluate(value)) { if (!valuePredicate.evaluate(value)) {
throw new IllegalArgumentException("Invalid value."); throw new IllegalArgumentException("Cannot add value - Predicate rejected it");
} }
} }
} }
static class PredicatedMapEntrySet static class PredicatedMapEntrySet
extends CollectionUtils.CollectionWrapper extends CollectionUtils.CollectionWrapper
implements Set { implements Set {
final private Predicate predicate; private final Predicate predicate;
public PredicatedMapEntrySet(Set set, Predicate p) { public PredicatedMapEntrySet(Set set, Predicate p) {
super(set); super(set);
@ -818,13 +819,20 @@ public class MapUtils {
} }
static class PredicatedMapEntry implements Map.Entry { static class PredicatedMapEntry
implements Map.Entry {
final private Map.Entry entry; private final Map.Entry entry;
final private Predicate predicate; private final Predicate predicate;
public PredicatedMapEntry(Map.Entry entry, Predicate p) { 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.entry = entry;
this.predicate = p; this.predicate = p;
} }
@ -851,26 +859,27 @@ public class MapUtils {
public Object setValue(Object o) { public Object setValue(Object o) {
if (!predicate.evaluate(o)) { if (!predicate.evaluate(o)) {
throw new IllegalArgumentException("Invalid value."); throw new IllegalArgumentException("Cannot set value - Predicate rejected it");
} }
return entry.setValue(o); return entry.setValue(o);
} }
} }
static class FixedSizeMap extends ProxyMap { static class FixedSizeMap
extends ProxyMap {
public FixedSizeMap(Map map) { public FixedSizeMap(Map map) {
super(map); super(map);
if (map == null) { 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) { public Object put(Object key, Object value) {
if (!map.containsKey(key)) { 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); return map.put(key, value);
} }
@ -879,7 +888,7 @@ public class MapUtils {
public void putAll(Map m) { public void putAll(Map m) {
for (Iterator iter = m.keySet().iterator(); iter.hasNext(); ) { for (Iterator iter = m.keySet().iterator(); iter.hasNext(); ) {
if (!map.containsKey(iter.next())) { 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); map.putAll(m);
@ -888,18 +897,18 @@ public class MapUtils {
} }
static class LazyMap extends ProxyMap { static class LazyMap
extends ProxyMap {
final protected Factory factory;
protected final Factory factory;
public LazyMap(Map map, Factory factory) { public LazyMap(Map map, Factory factory) {
super(map); super(map);
if (map == null) { if (map == null) {
throw new IllegalArgumentException("map may not be null."); throw new IllegalArgumentException("Map must not be null");
} }
if (factory == null) { if (factory == null) {
throw new IllegalArgumentException("factory may not be null."); throw new IllegalArgumentException("Factory must not be null");
} }
this.factory = factory; this.factory = factory;
} }
@ -918,8 +927,9 @@ public class MapUtils {
static class PredicatedSortedMap extends PredicatedMap static class PredicatedSortedMap
implements SortedMap { extends PredicatedMap
implements SortedMap {
public PredicatedSortedMap(SortedMap map, Predicate k, Predicate v) { public PredicatedSortedMap(SortedMap map, Predicate k, Predicate v) {
super(map, k, v); super(map, k, v);
@ -962,7 +972,9 @@ public class MapUtils {
} }
static class FixedSizeSortedMap extends FixedSizeMap implements SortedMap { static class FixedSizeSortedMap
extends FixedSizeMap
implements SortedMap {
public FixedSizeSortedMap(SortedMap m) { public FixedSizeSortedMap(SortedMap m) {
super(m); super(m);
@ -1002,7 +1014,9 @@ public class MapUtils {
} }
static class LazySortedMap extends LazyMap implements SortedMap { static class LazySortedMap
extends LazyMap
implements SortedMap {
public LazySortedMap(SortedMap m, Factory factory) { public LazySortedMap(SortedMap m, Factory factory) {
super(m, factory); super(m, factory);
@ -1043,127 +1057,129 @@ public class MapUtils {
/** /**
* Returns a predicated map backed by the given map. Only keys and * Returns a predicated map backed by the given map. Only keys and
* values that pass the given predicates can be added to the map. * values that pass the given predicates can be added to the map.
* It is important not to use the original map after invoking this * It is important not to use the original map after invoking this
* method, as it is a backdoor for adding unvalidated objects. * method, as it is a backdoor for adding unvalidated objects.
* *
* @param map the map to predicate * @param map the map to predicate, must not be null
* @param keyPred the predicate for keys * @param keyPred the predicate for keys, must not be null
* @param valuePred the predicate for values * @param valuePred the predicate for values, must not be null
* @return a predicated map backed by the given map * @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) { public static Map predicatedMap(Map map, Predicate keyPred, Predicate valuePred) {
return new PredicatedMap(map, keyPred, valuePred); return new PredicatedMap(map, keyPred, valuePred);
} }
/** /**
* Returns a fixed-sized map backed by the given map. * Returns a fixed-sized map backed by the given map.
* Elements may not be added or removed from the returned map, but * Elements may not be added or removed from the returned map, but
* existing elements can be changed (for instance, via the * existing elements can be changed (for instance, via the
* {@link Map#put(Object,Object)} method). * {@link Map#put(Object,Object)} method).
* *
* @param map the map whose size to fix * @param map the map whose size to fix, must not be null
* @return a fixed-size map backed by that map * @return a fixed-size map backed by that map
* @throws IllegalArgumentException if the Map is null
*/ */
public static Map fixedSizeMap(Map map) { public static Map fixedSizeMap(Map map) {
return new FixedSizeMap(map); return new FixedSizeMap(map);
} }
/** /**
* Returns a "lazy" map whose values will be created on demand.<P> * Returns a "lazy" map whose values will be created on demand.<P>
* <P> * <p>
* When the key passed to the returned map's {@link Map#get(Object)} * 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 * 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 * to create a new object and that object will become the value
* associated with that key. * associated with that key.
* <P> * <p>
* For instance: * For instance:
* *
* <Pre> * <pre>
* Factory factory = new Factory() { * Factory factory = new Factory() {
* public Object create() { * public Object create() {
* return new Date(); * return new Date();
* } * }
* } * }
* Map lazy = MapUtils.lazyMap(new HashMap(), factory); * Map lazy = MapUtils.lazyMap(new HashMap(), factory);
* Object obj = lazy.get("test"); * Object obj = lazy.get("test");
* </Pre> * </pre>
* *
* After the above code is executed, <Code>obj</Code> will contain * After the above code is executed, <code>obj</code> will contain
* a new <Code>Date</Code> instance. Furthermore, that <Code>Date</Code> * a new <code>Date</code> instance. Furthermore, that <code>Date</code>
* instance is the value for the <Code>test</Code> key.<P> * instance is the value for the <code>test</code> key.
* *
* @param map the map to make lazy * @param map the map to make lazy, must not be null
* @param factory the factory for creating new objects * @param factory the factory for creating new objects, must not be null
* @return a lazy map backed by the given map * @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) { public static Map lazyMap(Map map, Factory factory) {
return new LazyMap(map, factory); return new LazyMap(map, factory);
} }
/** /**
* Returns a predicated sorted map backed by the given map. Only keys and * 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. * values that pass the given predicates can be added to the map.
* It is important not to use the original map after invoking this * It is important not to use the original map after invoking this
* method, as it is a backdoor for adding unvalidated objects. * method, as it is a backdoor for adding unvalidated objects.
* *
* @param map the map to predicate * @param map the map to predicate, must not be null
* @param keyPred the predicate for keys * @param keyPred the predicate for keys, must not be null
* @param valuePred the predicate for values * @param valuePred the predicate for values, must not be null
* @return a predicated map backed by the given map * @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) { public static SortedMap predicatedSortedMap(SortedMap map, Predicate keyPred, Predicate valuePred) {
return new PredicatedSortedMap(map, keyPred, valuePred); return new PredicatedSortedMap(map, keyPred, valuePred);
} }
/** /**
* Returns a fixed-sized sorted map backed by the given sorted 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 * Elements may not be added or removed from the returned map, but
* existing elements can be changed (for instance, via the * existing elements can be changed (for instance, via the
* {@link Map#put(Object,Object)} method). * {@link Map#put(Object,Object)} method).
* *
* @param map the map whose size to fix * @param map the map whose size to fix, must not be null
* @return a fixed-size map backed by that map * @return a fixed-size map backed by that map
* @throws IllegalArgumentException if the SortedMap is null
*/ */
public static SortedMap fixedSizeSortedMap(SortedMap map) { public static SortedMap fixedSizeSortedMap(SortedMap map) {
return new FixedSizeSortedMap(map); return new FixedSizeSortedMap(map);
} }
/** /**
* Returns a "lazy" sorted map whose values will be created on demand. * Returns a "lazy" sorted map whose values will be created on demand.
* <P> * <p>
* When the key passed to the returned map's {@link Map#get(Object)} * 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 * 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 * to create a new object and that object will become the value
* associated with that key. * associated with that key.
* <P> * <p>
* For instance: * For instance:
* *
* <Pre> * <pre>
* Factory factory = new Factory() { * Factory factory = new Factory() {
* public Object create() { * public Object create() {
* return new Date(); * return new Date();
* } * }
* } * }
* SortedMap lazy = MapUtils.lazySortedMap(new TreeMap(), factory); * SortedMap lazy = MapUtils.lazySortedMap(new TreeMap(), factory);
* Object obj = lazy.get("test"); * Object obj = lazy.get("test");
* </Pre> * </pre>
* *
* After the above code is executed, <Code>obj</Code> will contain * After the above code is executed, <code>obj</code> will contain
* a new <Code>Date</Code> instance. Furthermore, that <Code>Date</Code> * a new <code>Date</code> instance. Furthermore, that <code>Date</code>
* instance is the value for the <Code>test</Code> key.<P> * instance is the value for the <code>test</code> key.
* *
* @param map the map to make lazy * @param map the map to make lazy, must not be null
* @param factory the factory for creating new objects * @param factory the factory for creating new objects, must not be null
* @return a lazy map backed by the given map * @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) { public static SortedMap lazySortedMap(SortedMap map, Factory factory) {
return new LazySortedMap(map, factory); return new LazySortedMap(map, factory);
} }
} }

83
src/java/org/apache/commons/collections/SetUtils.java
View File

@ -1,7 +1,7 @@
/* /*
* $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/SetUtils.java,v 1.6 2002/10/12 22:15:19 scolebourne Exp $ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/SetUtils.java,v 1.7 2002/10/13 00:38:36 scolebourne Exp $
* $Revision: 1.6 $ * $Revision: 1.7 $
* $Date: 2002/10/12 22:15:19 $ * $Date: 2002/10/13 00:38:36 $
* *
* ==================================================================== * ====================================================================
* *
@ -60,45 +60,44 @@
*/ */
package org.apache.commons.collections; package org.apache.commons.collections;
import java.util.Comparator; import java.util.Comparator;
import java.util.Set; import java.util.Set;
import java.util.SortedSet; import java.util.SortedSet;
/** /**
* Provides static utility methods and decorators for {@link Set} * Provides static utility methods and decorators for {@link Set}
* and {@link SortedSet} instances. * and {@link SortedSet} instances.
* *
* @author Paul Jack * @author Paul Jack
* @version $Id: SetUtils.java,v 1.6 2002/10/12 22:15:19 scolebourne Exp $ * @author Stephen Colebourne
* @since 2.1 * @version $Id: SetUtils.java,v 1.7 2002/10/13 00:38:36 scolebourne Exp $
* @since 2.1
*/ */
public class SetUtils { public class SetUtils {
/** /**
* Prevents instantiation. * Prevents instantiation.
*/ */
private SetUtils() { private SetUtils() {
} }
static class PredicatedSet extends CollectionUtils.PredicatedCollection static class PredicatedSet
implements Set { extends CollectionUtils.PredicatedCollection
implements Set {
public PredicatedSet(Set set, Predicate p) { public PredicatedSet(Set set, Predicate predicate) {
super(set, p); super(set, predicate);
} }
} }
static class PredicatedSortedSet extends PredicatedSet static class PredicatedSortedSet
implements SortedSet { extends PredicatedSet
implements SortedSet {
public PredicatedSortedSet(SortedSet s, Predicate p) { public PredicatedSortedSet(SortedSet set, Predicate predicate) {
super(s, p); super(set, predicate);
} }
public SortedSet subSet(Object o1, Object o2) { public SortedSet subSet(Object o1, Object o2) {
@ -135,34 +134,34 @@ public class SetUtils {
} }
/** /**
* Returns a predicated set backed by the given set. Only 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. * 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 * It is important not to use the original set after invoking this
* method, as it is a backdoor for adding unvalidated objects. * method, as it is a backdoor for adding unvalidated objects.
* *
* @param set the set to predicate * @param set the set to predicate, must not be null
* @param p the predicate for the set * @param predicate the predicate for the set, must not be null
* @return a predicated set backed by the given set * @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) { public static Set predicatedSet(Set set, Predicate predicate) {
return new PredicatedSet(set, p); return new PredicatedSet(set, predicate);
} }
/** /**
* Returns a predicated sorted set backed by the given sorted set. * Returns a predicated sorted set backed by the given sorted set.
* Only objects that pass the test in the given predicate can be added * Only objects that pass the test in the given predicate can be added
* to the sorted set. * to the sorted set.
* It is important not to use the original sorted set after invoking this * It is important not to use the original sorted set after invoking this
* method, as it is a backdoor for adding unvalidated objects. * method, as it is a backdoor for adding unvalidated objects.
* *
* @param set the sorted set to predicate * @param set the sorted set to predicate, must not be null
* @param p the predicate for the sorted set * @param predicate the predicate for the sorted set, must not be null
* @return a predicated sorted set backed by the given sorted set * @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) { public static SortedSet predicatedSortedSet(SortedSet set, Predicate predicate) {
return new PredicatedSortedSet(set, p); return new PredicatedSortedSet(set, predicate);
} }
} }