You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by jo...@apache.org on 2011/03/08 23:31:49 UTC
svn commit: r1079587 - in /commons/proper/collections:
branches/COLLECTIONS_3_2_BRANCH/src/java/org/apache/commons/collections/iterators/
branches/COLLECTIONS_3_2_BRANCH/src/test/org/apache/commons/collections/iterators/
trunk/src/java/org/apache/commo...
Author: jochen
Date: Tue Mar 8 22:31:49 2011
New Revision: 1079587
URL: http://svn.apache.org/viewvc?rev=1079587&view=rev
Log:
PR: COLLECTIONS-331
Documented the requirement to use a comparator.
Modified:
commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH/src/java/org/apache/commons/collections/iterators/CollatingIterator.java
commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH/src/test/org/apache/commons/collections/iterators/TestCollatingIterator.java
commons/proper/collections/trunk/src/java/org/apache/commons/collections/comparators/ComparableComparator.java
commons/proper/collections/trunk/src/java/org/apache/commons/collections/iterators/CollatingIterator.java
commons/proper/collections/trunk/src/test/org/apache/commons/collections/iterators/TestCollatingIterator.java
Modified: commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH/src/java/org/apache/commons/collections/iterators/CollatingIterator.java
URL: http://svn.apache.org/viewvc/commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH/src/java/org/apache/commons/collections/iterators/CollatingIterator.java?rev=1079587&r1=1079586&r2=1079587&view=diff
==============================================================================
--- commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH/src/java/org/apache/commons/collections/iterators/CollatingIterator.java (original)
+++ commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH/src/java/org/apache/commons/collections/iterators/CollatingIterator.java Tue Mar 8 22:31:49 2011
@@ -60,8 +60,10 @@ public class CollatingIterator implement
// Constructors
// ----------------------------------------------------------------------
/**
- * Constructs a new <code>CollatingIterator</code>. Natural sort order
- * will be used, and child iterators will have to be manually added
+ * Constructs a new <code>CollatingIterator</code>. A comparator must be
+ * set by calling {@link #setComparator(Comparator)} before invoking
+ * {@link #hasNext()}, or {@link #next()} for the first time. Child
+ * iterators will have to be manually added using the
* using the {@link #addIterator(Iterator)} method.
*/
public CollatingIterator() {
@@ -73,7 +75,9 @@ public class CollatingIterator implement
* specified comparator for ordering. Child iterators will have to be
* manually added using the {@link #addIterator(Iterator)} method.
*
- * @param comp the comparator to use to sort, or null to use natural sort order
+ * @param comp the comparator to use to sort; must not be null,
+ * unless you'll be invoking {@link #setComparator(Comparator)}
+ * later on.
*/
public CollatingIterator(final Comparator comp) {
this(comp,2);
@@ -85,7 +89,9 @@ public class CollatingIterator implement
* capacity. Child iterators will have to be
* manually added using the {@link #addIterator(Iterator)} method.
*
- * @param comp the comparator to use to sort, or null to use natural sort order
+ * @param comp the comparator to use to sort; must not be null,
+ * unless you'll be invoking {@link #setComparator(Comparator)}
+ * later on.
* @param initIterCapacity the initial capacity for the internal list
* of child iterators
*/
@@ -99,7 +105,9 @@ public class CollatingIterator implement
* specified comparator to provide ordered iteration over the two
* given iterators.
*
- * @param comp the comparator to use to sort, or null to use natural sort order
+ * @param comp the comparator to use to sort; must not be null,
+ * unless you'll be invoking {@link #setComparator(Comparator)}
+ * later on.
* @param a the first child ordered iterator
* @param b the second child ordered iterator
* @throws NullPointerException if either iterator is null
@@ -115,7 +123,9 @@ public class CollatingIterator implement
* specified comparator to provide ordered iteration over the array
* of iterators.
*
- * @param comp the comparator to use to sort, or null to use natural sort order
+ * @param comp the comparator to use to sort; must not be null,
+ * unless you'll be invoking {@link #setComparator(Comparator)}
+ * later on.
* @param iterators the array of iterators
* @throws NullPointerException if iterators array is or contains null
*/
@@ -131,7 +141,9 @@ public class CollatingIterator implement
* specified comparator to provide ordered iteration over the collection
* of iterators.
*
- * @param comp the comparator to use to sort, or null to use natural sort order
+ * @param comp the comparator to use to sort; must not be null,
+ * unless you'll be invoking {@link #setComparator(Comparator)}
+ * later on.
* @param iterators the collection of iterators
* @throws NullPointerException if the iterators collection is or contains null
* @throws ClassCastException if the iterators collection contains an
@@ -196,7 +208,11 @@ public class CollatingIterator implement
}
/**
- * Sets the {@link Comparator} by which collation occurs.
+ * Sets the {@link Comparator} by which collation occurs. If you
+ * would like to use the natural sort order (or, in other words,
+ * if the elements in the iterators are implementing the
+ * {@link java.lang.Comparable} interface), then use the
+ * {@link org.apache.commons.collections.comparators.ComparableComparator}.
*
* @throws IllegalStateException if iteration has started
*/
@@ -331,6 +347,9 @@ public class CollatingIterator implement
leastObject = values.get(i);
} else {
Object curObject = values.get(i);
+ if (comparator == null) {
+ throw new NullPointerException("You must invoke setComparator() to set a compator first.");
+ }
if (comparator.compare(curObject,leastObject) < 0) {
leastObject = curObject;
leastIndex = i;
Modified: commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH/src/test/org/apache/commons/collections/iterators/TestCollatingIterator.java
URL: http://svn.apache.org/viewvc/commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH/src/test/org/apache/commons/collections/iterators/TestCollatingIterator.java?rev=1079587&r1=1079586&r2=1079587&view=diff
==============================================================================
--- commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH/src/test/org/apache/commons/collections/iterators/TestCollatingIterator.java (original)
+++ commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH/src/test/org/apache/commons/collections/iterators/TestCollatingIterator.java Tue Mar 8 22:31:49 2011
@@ -17,8 +17,10 @@
package org.apache.commons.collections.iterators;
import java.util.ArrayList;
+import java.util.Arrays;
import java.util.Comparator;
import java.util.Iterator;
+import java.util.List;
import junit.framework.Test;
import junit.framework.TestSuite;
@@ -207,5 +209,25 @@ public class TestCollatingIterator exten
assertEquals(expectedSize,(evens.size() + odds.size()));
}
+ public void testNullComparator() {
+ List l1 = Arrays.asList(new Integer[]{new Integer(1), new Integer(3), new Integer(5)});
+ List l2 = Arrays.asList(new Integer[]{new Integer(2), new Integer(4), new Integer(6)});
+
+ CollatingIterator collatingIterator1 = new CollatingIterator(null, l1.iterator(), l2.iterator());
+ try {
+ collatingIterator1.next();
+ } catch (NullPointerException e) {
+ assertTrue(e.getMessage().startsWith("You must invoke setComparator"));
+ }
+
+ int i = 0;
+ CollatingIterator collatingIterator2 = new CollatingIterator(null, l1.iterator(), l2.iterator());
+ collatingIterator2.setComparator(new ComparableComparator());
+ for ( ; collatingIterator2.hasNext(); i++ ) {
+ Integer n = (Integer)collatingIterator2.next();
+ assertEquals("wrong order", n.intValue(), i + 1);
+ }
+ assertEquals("wrong size", i, l1.size() + l2.size());
+ }
}
Modified: commons/proper/collections/trunk/src/java/org/apache/commons/collections/comparators/ComparableComparator.java
URL: http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/java/org/apache/commons/collections/comparators/ComparableComparator.java?rev=1079587&r1=1079586&r2=1079587&view=diff
==============================================================================
--- commons/proper/collections/trunk/src/java/org/apache/commons/collections/comparators/ComparableComparator.java (original)
+++ commons/proper/collections/trunk/src/java/org/apache/commons/collections/comparators/ComparableComparator.java Tue Mar 8 22:31:49 2011
@@ -46,6 +46,7 @@ public class ComparableComparator<E exte
private static final long serialVersionUID=-291439688585137865L;
/** The singleton instance. */
+ @SuppressWarnings("rawtypes")
public static final ComparableComparator<?> INSTANCE = new ComparableComparator();
//-----------------------------------------------------------------------
Modified: commons/proper/collections/trunk/src/java/org/apache/commons/collections/iterators/CollatingIterator.java
URL: http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/java/org/apache/commons/collections/iterators/CollatingIterator.java?rev=1079587&r1=1079586&r2=1079587&view=diff
==============================================================================
--- commons/proper/collections/trunk/src/java/org/apache/commons/collections/iterators/CollatingIterator.java (original)
+++ commons/proper/collections/trunk/src/java/org/apache/commons/collections/iterators/CollatingIterator.java Tue Mar 8 22:31:49 2011
@@ -26,6 +26,7 @@ import java.util.NoSuchElementException;
import org.apache.commons.collections.list.UnmodifiableList;
+
/**
* Provides an ordered iteration over the elements contained in a collection of
* ordered Iterators.
@@ -63,8 +64,10 @@ public class CollatingIterator<E> implem
// Constructors
// ----------------------------------------------------------------------
/**
- * Constructs a new <code>CollatingIterator</code>. Natural sort order will
- * be used, and child iterators will have to be manually added using the
+ * Constructs a new <code>CollatingIterator</code>. A comparator must be
+ * set by calling {@link #setComparator(Comparator)} before invoking
+ * {@link #hasNext()}, or {@link #next()} for the first time. Child
+ * iterators will have to be manually added using the
* {@link #addIterator(Iterator)} method.
*/
public CollatingIterator() {
@@ -76,8 +79,9 @@ public class CollatingIterator<E> implem
* specified comparator for ordering. Child iterators will have to be
* manually added using the {@link #addIterator(Iterator)} method.
*
- * @param comp the comparator to use to sort, or null to use natural sort
- * order
+ * @param comp the comparator to use to sort; must not be null,
+ * unless you'll be invoking {@link #setComparator(Comparator)}
+ * later on.
*/
public CollatingIterator(final Comparator<? super E> comp) {
this(comp, 2);
@@ -89,8 +93,9 @@ public class CollatingIterator<E> implem
* capacity. Child iterators will have to be manually added using the
* {@link #addIterator(Iterator)} method.
*
- * @param comp the comparator to use to sort, or null to use natural sort
- * order
+ * @param comp the comparator to use to sort; must not be null,
+ * unless you'll be invoking {@link #setComparator(Comparator)}
+ * later on.
* @param initIterCapacity the initial capacity for the internal list of
* child iterators
*/
@@ -104,8 +109,9 @@ public class CollatingIterator<E> implem
* specified comparator to provide ordered iteration over the two given
* iterators.
*
- * @param comp the comparator to use to sort, or null to use natural sort
- * order
+ * @param comp the comparator to use to sort; must not be null,
+ * unless you'll be invoking {@link #setComparator(Comparator)}
+ * later on.
* @param a the first child ordered iterator
* @param b the second child ordered iterator
* @throws NullPointerException if either iterator is null
@@ -121,8 +127,9 @@ public class CollatingIterator<E> implem
* specified comparator to provide ordered iteration over the array of
* iterators.
*
- * @param comp the comparator to use to sort, or null to use natural sort
- * order
+ * @param comp the comparator to use to sort; must not be null,
+ * unless you'll be invoking {@link #setComparator(Comparator)}
+ * later on.
* @param iterators the array of iterators
* @throws NullPointerException if iterators array is or contains null
*/
@@ -138,8 +145,9 @@ public class CollatingIterator<E> implem
* specified comparator to provide ordered iteration over the collection of
* iterators.
*
- * @param comp the comparator to use to sort, or null to use natural sort
- * order
+ * @param comp the comparator to use to sort; must not be null,
+ * unless you'll be invoking {@link #setComparator(Comparator)}
+ * later on.
* @param iterators the collection of iterators
* @throws NullPointerException if the iterators collection is or contains
* null
@@ -204,7 +212,11 @@ public class CollatingIterator<E> implem
}
/**
- * Sets the {@link Comparator} by which collation occurs.
+ * Sets the {@link Comparator} by which collation occurs. If you
+ * would like to use the natural sort order (or, in other words,
+ * if the elements in the iterators are implementing the
+ * {@link java.lang.Comparable} interface), then use the
+ * {@link org.apache.commons.collections.comparators.ComparableComparator}.
*
* @throws IllegalStateException if iteration has started
*/
@@ -349,6 +361,9 @@ public class CollatingIterator<E> implem
leastObject = values.get(i);
} else {
E curObject = values.get(i);
+ if (comparator == null) {
+ throw new NullPointerException("You must invoke setComparator() to set a compator first.");
+ }
if (comparator.compare(curObject, leastObject) < 0) {
leastObject = curObject;
leastIndex = i;
Modified: commons/proper/collections/trunk/src/test/org/apache/commons/collections/iterators/TestCollatingIterator.java
URL: http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/test/org/apache/commons/collections/iterators/TestCollatingIterator.java?rev=1079587&r1=1079586&r2=1079587&view=diff
==============================================================================
--- commons/proper/collections/trunk/src/test/org/apache/commons/collections/iterators/TestCollatingIterator.java (original)
+++ commons/proper/collections/trunk/src/test/org/apache/commons/collections/iterators/TestCollatingIterator.java Tue Mar 8 22:31:49 2011
@@ -17,7 +17,9 @@
package org.apache.commons.collections.iterators;
import java.util.ArrayList;
+import java.util.Arrays;
import java.util.Comparator;
+import java.util.List;
import org.apache.commons.collections.comparators.ComparableComparator;
@@ -237,5 +239,25 @@ public class TestCollatingIterator exten
assertEquals(expectedSize, (evens.size() + odds.size()));
}
+ public void testNullComparator() {
+ List<Integer> l1 = Arrays.asList(1, 3, 5);
+ List<Integer> l2 = Arrays.asList(2, 4, 6);
+
+ CollatingIterator<Integer> collatingIterator1 = new CollatingIterator<Integer>(null, l1.iterator(), l2.iterator());
+ try {
+ collatingIterator1.next();
+ } catch (NullPointerException e) {
+ assertTrue(e.getMessage().startsWith("You must invoke setComparator"));
+ }
+
+ int i = 0;
+ CollatingIterator<Integer> collatingIterator2 = new CollatingIterator<Integer>(null, l1.iterator(), l2.iterator());
+ collatingIterator2.setComparator(new ComparableComparator<Integer>());
+ for ( ; collatingIterator2.hasNext(); i++ ) {
+ Integer n = (Integer)collatingIterator2.next();
+ assertEquals("wrong order", (int)n, i + 1);
+ }
+ assertEquals("wrong size", i, l1.size() + l2.size());
+ }
}