PR: COLLECTIONS-331

Documented the requirement to use a comparator.


git-svn-id: https://svn.apache.org/repos/asf/commons/proper/collections/trunk@1079587 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/commons/collections/comparators/ComparableComparator.java

@@ -46,6 +46,7 @@ public class ComparableComparator<E extends Comparable<? super E>> implements Co
     private static final long serialVersionUID=-291439688585137865L;
 
     /** The singleton instance. */
+    @SuppressWarnings("rawtypes")
     public static final ComparableComparator<?> INSTANCE = new ComparableComparator();
 
     //-----------------------------------------------------------------------

src/java/org/apache/commons/collections/iterators/CollatingIterator.java

@@ -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> implements Iterator<E> {
     // 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> implements Iterator<E> {
      * 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> implements Iterator<E> {
      * 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> implements Iterator<E> {
      * 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> implements Iterator<E> {
      * 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> implements Iterator<E> {
      * 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> implements Iterator<E> {
     }
 
     /**
-     * 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> implements Iterator<E> {
                     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;

src/test/org/apache/commons/collections/iterators/TestCollatingIterator.java

@@ -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 extends AbstractTestIterator<Integer> {
         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());
+    }
 }