PR: COLLECTIONS-331 Documented the requirement to use a comparator.
git-svn-id: https://svn.apache.org/repos/asf/commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH@1079587 13f79535-47bb-0310-9956-ffa450edef68 Project: http://git-wip-us.apache.org/repos/asf/commons-collections/repo Commit: http://git-wip-us.apache.org/repos/asf/commons-collections/commit/ef4dd46d Tree: http://git-wip-us.apache.org/repos/asf/commons-collections/tree/ef4dd46d Diff: http://git-wip-us.apache.org/repos/asf/commons-collections/diff/ef4dd46d Branch: refs/heads/COLLECTIONS_3_2_BRANCH Commit: ef4dd46dbd48992830a94fcfc0a6d15f85bb1beb Parents: 1c23c02 Author: Jochen Wiedmann <joc...@apache.org> Authored: Tue Mar 8 22:31:49 2011 +0000 Committer: Jochen Wiedmann <joc...@apache.org> Committed: Tue Mar 8 22:31:49 2011 +0000 ---------------------------------------------------------------------- .../iterators/CollatingIterator.java | 35 +++++++++++++++----- .../iterators/TestCollatingIterator.java | 22 ++++++++++++ 2 files changed, 49 insertions(+), 8 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/commons-collections/blob/ef4dd46d/src/java/org/apache/commons/collections/iterators/CollatingIterator.java ---------------------------------------------------------------------- diff --git a/src/java/org/apache/commons/collections/iterators/CollatingIterator.java b/src/java/org/apache/commons/collections/iterators/CollatingIterator.java index 4451319..94c80da 100644 --- a/src/java/org/apache/commons/collections/iterators/CollatingIterator.java +++ b/src/java/org/apache/commons/collections/iterators/CollatingIterator.java @@ -60,8 +60,10 @@ public class CollatingIterator implements Iterator { // 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 implements Iterator { * 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 implements Iterator { * 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 implements Iterator { * 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 implements Iterator { * 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 implements Iterator { * 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 implements Iterator { } /** - * 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 implements Iterator { 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; http://git-wip-us.apache.org/repos/asf/commons-collections/blob/ef4dd46d/src/test/org/apache/commons/collections/iterators/TestCollatingIterator.java ---------------------------------------------------------------------- diff --git a/src/test/org/apache/commons/collections/iterators/TestCollatingIterator.java b/src/test/org/apache/commons/collections/iterators/TestCollatingIterator.java index b844a7d..a108644 100644 --- a/src/test/org/apache/commons/collections/iterators/TestCollatingIterator.java +++ b/src/test/org/apache/commons/collections/iterators/TestCollatingIterator.java @@ -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 extends AbstractTestIterator { 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()); + } }
