* reduce ComparableComparator.compare to "return ((Comparable)o1).compareTo(o2)"

* some javadoc fixes


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

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

@@ -1,5 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/comparators/BooleanComparator.java,v 1.3 2003/01/11 01:07:13 rwaldhoff Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/comparators/BooleanComparator.java,v 1.4 2003/01/13 22:34:57 rwaldhoff Exp $
  * ====================================================================
  *
  * The Apache Software License, Version 1.1
@@ -69,7 +69,7 @@ import java.util.Comparator;
  * 
  * @since Commons Collections 2.2
  * 
- * @version $Revision: 1.3 $ $Date: 2003/01/11 01:07:13 $
+ * @version $Revision: 1.4 $ $Date: 2003/01/13 22:34:57 $
  * 
  * @author Rodney Waldhoff
  */
@@ -157,7 +157,7 @@ public final class BooleanComparator implements Comparator, Serializable {
      * I sort <code>true</code> values before 
      * <code>false</code> values.  In other words,
      * returns <code>true</code> iff
-     * {@link #compare(Boolean,Boolean) compare(Boolean.TRUE,Boolean.FALSE)}
+     * {@link #compare(Boolean,Boolean) compare(Boolean.FALSE,Boolean.TRUE)}
      * returns a positive value.
      */
     public boolean sortsTrueFirst() {

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

@@ -1,6 +1,6 @@
-package org.apache.commons.collections.comparators;
+/* 
-
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/comparators/ComparableComparator.java,v 1.9 2003/01/13 22:34:57 rwaldhoff Exp $
-/* ====================================================================
+ * ====================================================================
  * The Apache Software License, Version 1.1
  *
  * Copyright (c) 2001-2003 The Apache Software Foundation.  All rights
@@ -55,29 +55,36 @@ package org.apache.commons.collections.comparators;
  *
  */
 
+package org.apache.commons.collections.comparators;
+
 import java.io.Serializable;
 import java.util.Comparator;
 
 /**
- * A Comparator that compares Comparable objects.
+ * A {@link Comparator Comparator} that compares 
- * Throws ClassCastExceptions if the objects are not 
+ * {@link Comparable Comparable} objects.
- * Comparable, or if either is null.
+ * <p />
- * 
+ * This Comparator is useful, for example,
- * Throws ClassCastException if the compareTo of both 
- * objects do not provide an inverse result of each other 
- * as per the Comparable javadoc.  This Comparator is useful, for example,
  * for enforcing the natural order in custom implementations
  * of SortedSet and SortedMap.
+ * <p />
+ * Note: In the 2.0 and 2.1 releases of Commons Collections, 
+ * this class would throw a {@link ClassCastException} if
+ * either of the arguments to {@link #compare compare}
+ * were <code>null</code>, not {@link Comparable Comparable},
+ * or for which {@link Comparable#compareTo compareTo} gave
+ * inconsistent results.  This is no longer the case.  See
+ * {@link #compare} for details.
  *
  * @since Commons Collections 2.0
+ * @version $Revision: 1.9 $ $Date: 2003/01/13 22:34:57 $
+ *
  * @author bayard@generationjava.com
- * @version $Revision: 1.8 $ $Date: 2003/01/10 20:21:23 $
+ *
+ * @see java.util.Collections#reverseOrder
  */
 public class ComparableComparator implements Comparator, Serializable {
 
-    private static final ComparableComparator instance = 
-        new ComparableComparator();
-
     /**
      *  Return a shared instance of a ComparableComparator.  Developers are
      *  encouraged to use the comparator returned from this method instead of
@@ -88,58 +95,20 @@ public class ComparableComparator implements Comparator,Serializable {
         return instance;
     }
 
-    private static final long serialVersionUID=-291439688585137865L;
-
     public ComparableComparator() {
     }
 
+    /**
+     * Compare the two {@link Comparable Comparable} arguments.
+     * This method is equivalent to:
+     * <pre>(({@link Comparable Comparable})o1).{@link Comparable#compareTo compareTo}(o2)</pre>
+     * @throws NullPointerException when <i>o1</i> is <code>null</code>, 
+     *         or when <code>((Comparable)o1).compareTo(o2)</code> does
+     * @throws ClassCastException when <i>o1</i> is not a {@link Comparable Comparable}, 
+     *         or when <code>((Comparable)o1).compareTo(o2)</code> does
+     */
     public int compare(Object o1, Object o2) {
-        if( (o1 == null) || (o2 == null) ) {
+        return ((Comparable)o1).compareTo(o2);
-            throw new ClassCastException(
-                "There were nulls in the arguments for this method: "+
-                "compare("+o1 + ", " + o2 + ")"
-                );
-        }
-        
-        if(o1 instanceof Comparable) {
-            if(o2 instanceof Comparable) {
-                int result1 = ((Comparable)o1).compareTo(o2);
-                int result2 = ((Comparable)o2).compareTo(o1);
-
-                // enforce comparable contract
-                if(result1 == 0 && result2 == 0) {
-                    return 0;
-                } else
-                if(result1 < 0 && result2 > 0) {
-                    return result1;
-                } else
-                if(result1 > 0 && result2 < 0) {
-                    return result1;
-                } else {
-                    // results inconsistent
-                    throw new ClassCastException("o1 not comparable to o2");
-                }
-            } else {
-                // o2 wasn't comparable
-                throw new ClassCastException(
-                    "The first argument of this method was not a Comparable: " +
-                    o2.getClass().getName()
-                    );
-            }
-        } else 
-        if(o2 instanceof Comparable) {
-            // o1 wasn't comparable
-            throw new ClassCastException(
-                "The second argument of this method was not a Comparable: " +
-                o1.getClass().getName()
-                );
-        } else {
-            // neither were comparable
-            throw new ClassCastException(
-                "Both arguments of this method were not Comparables: " +
-                o1.getClass().getName() + " and " + o2.getClass().getName()
-                );
-        }
     }
 
     /**
@@ -155,8 +124,8 @@ public class ComparableComparator implements Comparator,Serializable {
 
     /**
      * Returns <code>true</code> iff <i>that</i> Object is 
-     * is a {@link Comparator} whose ordering is known to be 
+     * is a {@link Comparator Comparator} whose ordering is 
-     * equivalent to mine.
+     * known to be equivalent to mine.
      * <p>
      * This implementation returns <code>true</code>
      * iff <code><i>that</i>.{@link Object#getClass getClass()}</code>
@@ -169,4 +138,10 @@ public class ComparableComparator implements Comparator,Serializable {
         return (this == that) || 
                ((null != that) && (that.getClass().equals(this.getClass())));
     }
+
+    private static final ComparableComparator instance = 
+        new ComparableComparator();
+
+    private static final long serialVersionUID=-291439688585137865L;
+
 }

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

@@ -1,5 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/comparators/ReverseComparator.java,v 1.11 2003/01/10 20:21:25 rwaldhoff Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/comparators/ReverseComparator.java,v 1.12 2003/01/13 22:34:57 rwaldhoff Exp $
  * ====================================================================
  * The Apache Software License, Version 1.1
  *
@@ -61,37 +61,37 @@ import java.util.Comparator;
 
 /**
  * Reverses the order of another comparator by 
- * reversing the arguments to its {@link #compare} 
+ * reversing the arguments to its {@link #compare compare} 
  * method.
  * 
  * @since Commons Collections 2.0
- * @version $Revision: 1.11 $ $Date: 2003/01/10 20:21:25 $
+ * @version $Revision: 1.12 $ $Date: 2003/01/13 22:34:57 $
  *
  * @author bayard@generationjava.com
  * @author <a href="mailto:mas@apache.org">Michael A. Smith</a>
+ * 
+ * @see java.util.Collections#reverseOrder
  */
 public class ReverseComparator implements Comparator,Serializable {
 
-    private Comparator comparator;
-
     /**
      * Creates a comparator that compares objects based on the inverse of their
      * natural ordering.  Using this Constructor will create a ReverseComparator
      * that is functionaly identical to the Comparator returned by
      * java.util.Collections.<b>reverseOrder()</b>.
      * 
-     * @see java.util.Collections#reverseOrder()
+     * @see java.util.Collections#reverseOrder
      */
     public ReverseComparator() {
         this(null);
     }
 
     /**
-     * Creates a reverse comparator that inverts the comparison
+     * Creates a comparator that inverts the comparison
-     * of the passed in comparator.  If you pass in a null,
+     * of the given comparator.  If you pass in <code>null</code>,
      * the ReverseComparator defaults to reversing the
      * natural order, as per 
-     * java.util.Collections.<b>reverseOrder()</b>.
+     * {@link java.util.Collections#reverseOrder}</b>.
      * 
      * @param comparator Comparator to reverse
      */
@@ -145,5 +145,7 @@ public class ReverseComparator implements Comparator,Serializable {
     }
 
     // use serialVersionUID from Collections 2.0 for interoperability
-    private static final long serialVersionUID = 2858887242028539265L;;
+    private static final long serialVersionUID = 2858887242028539265L;
+
+    private Comparator comparator;
 }