Rename methods

Add chainedComparator


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

src/java/org/apache/commons/collections/ComparatorUtils.java

@@ -51,118 +51,181 @@
  * information on the Apache Software Foundation, please see
  * <http://www.apache.org/>.
  */
-
 package org.apache.commons.collections;
 
-
+import java.util.Collection;
 import java.util.Comparator;
+
 import org.apache.commons.collections.comparators.ComparableComparator;
-import org.apache.commons.collections.comparators.ReverseComparator;
+import org.apache.commons.collections.comparators.ComparatorChain;
 import org.apache.commons.collections.comparators.NullComparator;
+import org.apache.commons.collections.comparators.ReverseComparator;
 import org.apache.commons.collections.comparators.TransformingComparator;
-
-
 /**
- *  Provides convenient static utility methods for <Code>Comparator</Code>
+ * Provides convenient static utility methods for <Code>Comparator</Code>
- *  objects.<P>
+ * objects.
+ * <p>
+ * Most of the utility in this class can also be found in the 
+ * <code>comparators</code> package. This class merely provides a 
+ * convenient central place if you have use for more than one class
+ * in the <code>comparators</code> subpackage.
+ * <p>
+ * Note that <i>every</i> method in this class allows you to specify
+ * <code>null</code> instead of a comparator, in which case 
+ * {@link #NATURAL} will be used.
  *
- *  Most of the utility in this class can also be found in the 
+ * @since 2.1
- *  <Code>comparators</Code> package; this class merely provides a 
+ * @author Paul Jack
- *  convenient central place if you have use for more than one class
+ * @author <a href="mailto:scolebourne@joda.org">Stephen Colebourne</a>
- *  in the <Code>comparators</Code> subpackage.<P>
+ * @version $Id: $
- *
- *  Note that <I>every</I> method in this class allows you to specify
- *  <Code>null</Code> instead of a comparator, in which case 
- *  {@link #NATURAL} will be used.
- *
- *  @author Paul Jack
- *  @version $Id$
- *  @since 2.1
  */
 public class ComparatorUtils {
 
-
+    /**
+     * Restrictive constructor
+     */
     private ComparatorUtils() {
     }
 
+    /**
+     * Comparator for natural sort order.
+     *
+     * @see ComparableComparator#getInstance
+     */
+    final public static Comparator NATURAL = ComparableComparator.getInstance();
 
     /**
-     *  Comparator for natural sort order.
+     * Gets a comparator that uses the natural order of the objects.
      *
-     *  @see ComparableComparator#getInstance
+     * @return  a comparator which uses natural order
      */
-    final public static Comparator NATURAL = 
+    public static Comparator naturalComparator() {
-      ComparableComparator.getInstance();
+        return NATURAL;
-
+    }
 
     /**
-     *  Returns a comparator that reverses the order of the given 
+     * Gets a comparator that compares using two {@link Comparator}s.
-     *  comparator.
+     * <p>
+     * The second comparator is used if the first comparator returns
+     * that equal.
      *
-     *  @param comparator  the comparator whose order to reverse
+     * @param comparator1  the first comparator to use, not null
-     *  @return  a comparator who reverses that order
+     * @param comparator2  the first comparator to use, not null
-     *  @see ReverseComparator
+     * @return a combination comparator over the comparators
+     * @throws NullPointerException if either comparator is null
      */
-    public static Comparator reverse(Comparator comparator) {
+    public static Comparator chainedComparator(Comparator comparator1, Comparator comparator2) {
-        if (comparator == null) comparator = NATURAL;
+        return chainedComparator(new Comparator[] {comparator1, comparator2});
+    }
+
+    /**
+     * Gets a comparator that compares using an array of {@link Comparator}s.
+     * <p>
+     * The second comparator is used if the first comparator returns
+     * that equal and so on.
+     *
+     * @param iterators  the comparators to use, not null or empty or contain nulls
+     * @return a combination comparator over the comparators
+     * @throws NullPointerException if comparators array is null or contains a null
+     */
+    public static Comparator chainedComparator(Comparator[] comparators) {
+        ComparatorChain chain = new ComparatorChain();
+        for (int i = 0; i < comparators.length; i++) {
+            if (comparators[i] == null) {
+                throw new NullPointerException("Comparator cannot be null");
+            }
+            chain.addComparator(comparators[i]);
+        }
+        return chain;
+    }
+
+    /**
+     * Gets a comparator that compares using a collection of {@link Comparator}s.
+     * <p>
+     * The second comparator is used if the first comparator returns
+     * that equal and so on.
+     *
+     * @param comparators  the comparators to use, not null or empty or contain nulls
+     * @return a combination comparator over the comparators
+     * @throws NullPointerException if comparators collection is null or contains a null
+     * @throws ClassCastException if the comparators collection contains the wrong object type
+     */
+    public static Comparator chainedComparator(Collection comparators) {
+        return chainedComparator(
+            (Comparator[]) comparators.toArray(new Comparator[comparators.size()])
+        );
+    }
+
+    /**
+     * Gets a comparator that reverses the order of the given 
+     * comparator.
+     *
+     * @param comparator  the comparator whose order to reverse
+     * @return  a comparator who reverses that order
+     * @see ReverseComparator
+     */
+    public static Comparator reversedComparator(Comparator comparator) {
+        if (comparator == null) {
+            comparator = NATURAL;
+        }
         return new ReverseComparator(comparator);
     }
 
-
     /**
-     *  Allows the given comparator to compare <Code>null</Code> values.<P>
+     * Gets a Comparator that controls the comparison of <code>null</code> values.
+     * <p>
+     * The returned comparator will consider a null value to be less than
+     * any nonnull value, and equal to any other null value.  Two nonnull
+     * values will be evaluated with the given comparator.<P>
      *
-     *  The returned comparator will consider a null value to be less than
+     * @param comparator the comparator that wants to allow nulls
-     *  any nonnull value, and equal to any other null value.  Two nonnull
+     * @return  a version of that comparator that allows nulls
-     *  values will be evaluated with the given comparator.<P>
+     * @see NullComparator
-     *
-     *  @param comparator the comparator that wants to allow nulls
-     *  @return  a version of that comparator that allows nulls
-     *  @see NullComparator
      */
-    public static Comparator nullLow(Comparator comparator) {
+    public static Comparator nullLowComparator(Comparator comparator) {
-        if (comparator == null) comparator = NATURAL;
+        if (comparator == null) {
+            comparator = NATURAL;
+        }
         return new NullComparator(comparator, false);
     }
 
-
     /**
-     *  Allows the given comparator to compare <Code>null</Code> values.<P>
+     * Gets a Comparator that controls the comparison of <code>null</code> values.
+     * <p>
+     * The returned comparator will consider a null value to be greater than
+     * any nonnull value, and equal to any other null value.  Two nonnull
+     * values will be evaluated with the given comparator.<P>
      *
-     *  The returned comparator will consider a null value to be greater than
+     * @param comparator the comparator that wants to allow nulls
-     *  any nonnull value, and equal to any other null value.  Two nonnull
+     * @return  a version of that comparator that allows nulls
-     *  values will be evaluated with the given comparator.<P>
+     * @see NullComparator
-     *
-     *  @param comparator the comparator that wants to allow nulls
-     *  @return  a version of that comparator that allows nulls
-     *  @see NullComparator
      */
-    public static Comparator nullHigh(Comparator comparator) {
+    public static Comparator nullHighComparator(Comparator comparator) {
-        if (comparator == null) comparator = NATURAL;
+        if (comparator == null) {
+            comparator = NATURAL;
+        }
         return new NullComparator(comparator, true);
     }
 
-
-    
     /**
-     *  Passes transformed objects to the given comparator.<P>
+     * Gets a Comparator that passes transformed objects to the given comparator.
+     * <p>
+     * Objects passed to the returned comparator will first be transformed
+     * by the given transformer before they are compared by the given
+     * comparator.
      *
-     *  Objects passed to the returned comparator will first be transformed
+     * @param comparator  the sort order to use
-     *  by the given transformer before they are compared by the given
+     * @param transformer  the transformer to use
-     *  comparator.<P>
+     * @return  a comparator that transforms its input objects before comparing them
-     *
+     * @see  TransformingComparator
-     *  @param comparator  the sort order to use
-     *  @param t  the transformer to use
-     *  @return  a comparator that transforms its input objects before 
-     *    comparing them
-     *  @see  TransformingComparator
      */
-    public static Comparator transform(Comparator comparator, Transformer t) {
+    public static Comparator transformedComparator(Comparator comparator, Transformer transformer) {
-        if (comparator == null) comparator = NATURAL;
+        if (comparator == null) {
-        return new TransformingComparator(t, comparator);
+            comparator = NATURAL;
+        }
+        return new TransformingComparator(transformer, comparator);
     }
 
-
     /**
      *  Returns the smaller of the given objects according to the given 
      *  comparator.
@@ -173,12 +236,13 @@ public class ComparatorUtils {
      *  @return  the smaller of the two objects
      */
     public static Object min(Object o1, Object o2, Comparator comparator) {
-        if (comparator == null) comparator = NATURAL;
+        if (comparator == null) {
+            comparator = NATURAL;
+        }
         int c = comparator.compare(o1, o2);
         return (c < 0) ? o1 : o2;
     }
 
-
     /**
      *  Returns the smaller of the given objects according to the given 
      *  comparator.
@@ -189,7 +253,9 @@ public class ComparatorUtils {
      *  @return  the smaller of the two objects
      */
     public static Object max(Object o1, Object o2, Comparator comparator) {
-        if (comparator == null) comparator = NATURAL;
+        if (comparator == null) {
+            comparator = NATURAL;
+        }
         int c = comparator.compare(o1, o2);
         return (c > 0) ? o1 : o2;
     }