Summary
-------
Augment the discussion of requirements for `equals` and `compareTo` methods, including an update to `BigDecimal`, whose natural order is *not* consistent with equals.
Problem
-------
The related requirements for `equals` and `compareTo` methods is not necessarily clearly explained in the relevant javadoc.
Solution
--------
Update the specs of `Object.equals`, `java.lang.Comparable`, `java.math.BigDecimal`, etc. to better explain the relationships at hand. Use @implSpec, @apiNote, and related tags in Object and elsewhere. These new tags are not spec changes per se, but will affect what text gets @inheritDoc'ed by subclasses.
Specification
-------------
diff --git a/src/java.base/share/classes/java/lang/Comparable.java b/src/java.base/share/classes/java/lang/Comparable.java
index 0b5075c5e5f..eede91e30e2 100644
--- a/src/java.base/share/classes/java/lang/Comparable.java
+++ b/src/java.base/share/classes/java/lang/Comparable.java
@@ -64,9 +64,12 @@
*
* Virtually all Java core classes that implement {@code Comparable} have natural
* orderings that are consistent with equals. One exception is
- * {@code java.math.BigDecimal}, whose natural ordering equates
- * {@code BigDecimal} objects with equal values and different precisions
- * (such as 4.0 and 4.00).<p>
+ * {@link java.math.BigDecimal}, whose {@linkplain java.math.BigDecimal#compareTo natural ordering} equates
+ * {@code BigDecimal} objects with equal numerical values and different representations
+ * (such as 4.0 and 4.00). For {@link java.math.BigDecimal#equals
+ * BigDecimal.equals()} to return true, the representation and
+ * numerical value of the two {@code BigDecimal} objects must be the
+ * same.<p>
*
* For the mathematically inclined, the <i>relation</i> that defines
* the natural ordering on a given class C is:<pre>{@code
@@ -83,7 +86,12 @@
* the class's {@link Object#equals(Object) equals(Object)} method:<pre>
* {(x, y) such that x.equals(y)}. </pre><p>
*
- * This interface is a member of the
+ * In other words, when a class's natural ordering is consistent with
+ * equals, the equivalence classes defined by the equivalence relation
+ * of the {@code equals} method and the equivalence classes defined by
+ * the quotient of the {@code compareTo} method are the same.
+ *
+ * <p>This interface is a member of the
* <a href="{@docRoot}/java.base/java/util/package-summary.html#CollectionsFramework">
* Java Collections Framework</a>.
*
@@ -100,9 +108,9 @@
* than, equal to, or greater than the specified object.
*
* <p>The implementor must ensure
- * {@code sgn(x.compareTo(y)) == -sgn(y.compareTo(x))}
+ * {@link Integer#signum signum}{@code (x.compareTo(y)) == -signum(y.compareTo(x))}
* for all {@code x} and {@code y}. (This
- * implies that {@code x.compareTo(y)} must throw an exception iff
+ * implies that {@code x.compareTo(y)} must throw an exception if and only if
* {@code y.compareTo(x)} throws an exception.)
*
* <p>The implementor must also ensure that the relation is transitive:
@@ -110,22 +118,17 @@
* {@code x.compareTo(z) > 0}.
*
* <p>Finally, the implementor must ensure that {@code x.compareTo(y)==0}
- * implies that {@code sgn(x.compareTo(z)) == sgn(y.compareTo(z))}, for
+ * implies that {@code signum(x.compareTo(z)) == signum(y.compareTo(z))}, for
* all {@code z}.
*
- * <p>It is strongly recommended, but <i>not</i> strictly required that
+ * @apiNote
+ * It is strongly recommended, but <i>not</i> strictly required that
* {@code (x.compareTo(y)==0) == (x.equals(y))}. Generally speaking, any
* class that implements the {@code Comparable} interface and violates
* this condition should clearly indicate this fact. The recommended
* language is "Note: this class has a natural ordering that is
* inconsistent with equals."
*
- * <p>In the foregoing description, the notation
- * {@code sgn(}<i>expression</i>{@code )} designates the mathematical
- * <i>signum</i> function, which is defined to return one of {@code -1},
- * {@code 0}, or {@code 1} according to whether the value of
- * <i>expression</i> is negative, zero, or positive, respectively.
- *
* @param o the object to be compared.
* @return a negative integer, zero, or a positive integer as this object
* is less than, equal to, or greater than the specified object.
diff --git a/src/java.base/share/classes/java/lang/Object.java b/src/java.base/share/classes/java/lang/Object.java
index a155e1e8ba8..ad09e6bd5d6 100644
--- a/src/java.base/share/classes/java/lang/Object.java
+++ b/src/java.base/share/classes/java/lang/Object.java
@@ -78,11 +78,11 @@ public Object() {}
* used in {@code equals} comparisons on the object is modified.
* This integer need not remain consistent from one execution of an
* application to another execution of the same application.
- * <li>If two objects are equal according to the {@code equals(Object)}
+ * <li>If two objects are equal according to the {@link equals(Object) equals}
* method, then calling the {@code hashCode} method on each of
* the two objects must produce the same integer result.
* <li>It is <em>not</em> required that if two objects are unequal
- * according to the {@link java.lang.Object#equals(java.lang.Object)}
+ * according to the {@link equals(Object) equals}
* method, then calling the {@code hashCode} method on each of the
* two objects must produce distinct integer results. However, the
* programmer should be aware that producing distinct integer results
@@ -127,15 +127,26 @@ public Object() {}
* <li>For any non-null reference value {@code x},
* {@code x.equals(null)} should return {@code false}.
* </ul>
+ *
* <p>
+ * An equivalence relation partitions the elements it operates on
+ * into <i>equivalence classes</i>; all the members of an
+ * equivalence class are equal to each other. Members of an equivalence class
+ * are substitutable for each other, at least for some purposes.
+ *
+ * @implSpec
* The {@code equals} method for class {@code Object} implements
* the most discriminating possible equivalence relation on objects;
* that is, for any non-null reference values {@code x} and
* {@code y}, this method returns {@code true} if and only
* if {@code x} and {@code y} refer to the same object
* ({@code x == y} has the value {@code true}).
- * <p>
- * Note that it is generally necessary to override the {@code hashCode}
+ *
+ * In other words, under the reference equality equivalence
+ * relation, each equivalence class only has a single element.
+ *
+ * @apiNote
+ * It is generally necessary to override the {@link hashCode hashCode}
* method whenever this method is overridden, so as to maintain the
* general contract for the {@code hashCode} method, which states
* that equal objects must have equal hash codes.
@@ -183,7 +194,8 @@ public boolean equals(Object obj) {
* primitive fields or references to immutable objects, then it is usually
* the case that no fields in the object returned by {@code super.clone}
* need to be modified.
- * <p>
+ *
+ * @implSpec
* The method {@code clone} for class {@code Object} performs a
* specific cloning operation. First, if the class of this object does
* not implement the interface {@code Cloneable}, then a
@@ -214,13 +226,16 @@ public boolean equals(Object obj) {
protected native Object clone() throws CloneNotSupportedException;
/**
- * Returns a string representation of the object. In general, the
+ * Returns a string representation of the object.
+ * @apiNote
+ * In general, the
* {@code toString} method returns a string that
* "textually represents" this object. The result should
* be a concise but informative representation that is easy for a
* person to read.
* It is recommended that all subclasses override this method.
- * <p>
+ * The string output is not necessarily stable over time or across JVM invocations.
+ * @implSpec
* The {@code toString} method for class {@code Object}
* returns a string consisting of the name of the class of which the
* object is an instance, the at-sign character `{@code @}', and
diff --git a/src/java.base/share/classes/java/math/BigDecimal.java b/src/java.base/share/classes/java/math/BigDecimal.java
index bb698a555b6..b4e28e6697c 100644
--- a/src/java.base/share/classes/java/math/BigDecimal.java
+++ b/src/java.base/share/classes/java/math/BigDecimal.java
@@ -63,8 +63,7 @@
* <p>When a {@code MathContext} object is supplied with a precision
* setting of 0 (for example, {@link MathContext#UNLIMITED}),
* arithmetic operations are exact, as are the arithmetic methods
- * which take no {@code MathContext} object. (This is the only
- * behavior that was supported in releases prior to 5.) As a
+ * which take no {@code MathContext} object. As a
* corollary of computing the exact result, the rounding mode setting
* of a {@code MathContext} object with a precision setting of 0 is
* not used and thus irrelevant. In the case of divide, the exact
@@ -79,9 +78,8 @@
* {@code BigDecimal} arithmetic are broadly compatible with selected
* modes of operation of the arithmetic defined in ANSI X3.274-1996
* and ANSI X3.274-1996/AM 1-2000 (section 7.4). Unlike those
- * standards, {@code BigDecimal} includes many rounding modes, which
- * were mandatory for division in {@code BigDecimal} releases prior
- * to 5. Any conflicts between these ANSI standards and the
+ * standards, {@code BigDecimal} includes many rounding modes.
+ * Any conflicts between these ANSI standards and the
* {@code BigDecimal} specification are resolved in favor of
* {@code BigDecimal}.
*
@@ -90,6 +88,15 @@
* and rounding must specify both the numerical result and the scale
* used in the result's representation.
*
+ * The different representations of the same numerical value are
+ * called members of the same <i>cohort</i>. The {@linkplain
+ * compareTo(BigDecimal) natural order} of {@code BigDecimal}
+ * considers members of the same cohort to be equal to each other. In
+ * contrast, the {@link equals equals} method requires both the
+ * numerical value and representation to be the same for equality to
+ * hold. The results of methods like {@link scale} and {@link
+ * unscaledValue} will differ for numerically equal values with
+ * different representations.
*
* <p>In general the rounding modes and precision setting determine
* how operations return results with a limited number of digits when
@@ -3040,16 +3047,21 @@ public BigDecimal stripTrailingZeros() {
// Comparison Operations
/**
- * Compares this {@code BigDecimal} with the specified
+ * Compares this {@code BigDecimal} numerically with the specified
* {@code BigDecimal}. Two {@code BigDecimal} objects that are
* equal in value but have a different scale (like 2.0 and 2.00)
- * are considered equal by this method. This method is provided
+ * are considered equal by this method. Such values are in the same <i>cohort</i>.
+ *
+ * This method is provided
* in preference to individual methods for each of the six boolean
* comparison operators ({@literal <}, ==,
* {@literal >}, {@literal >=}, !=, {@literal <=}). The
* suggested idiom for performing these comparisons is:
* {@code (x.compareTo(y)} <<i>op</i>> {@code 0)}, where
* <<i>op</i>> is one of the six comparison operators.
+
+ * @apiNote
+ * Note: this class has a natural ordering that is inconsistent with equals.
*
* @param val {@code BigDecimal} to which this {@code BigDecimal} is
* to be compared.
@@ -3129,8 +3141,8 @@ else if (ys != INFLATED)
* {@code Object} for equality. Unlike {@link
* #compareTo(BigDecimal) compareTo}, this method considers two
* {@code BigDecimal} objects equal only if they are equal in
- * value and scale (thus 2.0 is not equal to 2.00 when compared by
- * this method).
+ * value and scale. Therefore 2.0 is not equal to 2.00 when compared by
+ * this method.
*
* @param x {@code Object} to which this {@code BigDecimal} is
* to be compared.
diff --git a/src/java.base/share/classes/java/util/Comparator.java b/src/java.base/share/classes/java/util/Comparator.java
index d009807a75a..b1b445bf55a 100644
--- a/src/java.base/share/classes/java/util/Comparator.java
+++ b/src/java.base/share/classes/java/util/Comparator.java
@@ -38,9 +38,9 @@
* as {@link Collections#sort(List,Comparator) Collections.sort} or {@link
* Arrays#sort(Object[],Comparator) Arrays.sort}) to allow precise control
* over the sort order. Comparators can also be used to control the order of
- * certain data structures (such as {@link SortedSet sorted sets} or {@link
+ * certain data structures (such as {@linkplain SortedSet sorted sets} or {@linkplain
* SortedMap sorted maps}), or to provide an ordering for collections of
- * objects that don't have a {@link Comparable natural ordering}.<p>
+ * objects that don't have a {@linkplain Comparable natural ordering}.<p>
*
* The ordering imposed by a comparator {@code c} on a set of elements
* {@code S} is said to be <i>consistent with equals</i> if and only if
@@ -89,6 +89,11 @@
* equals(Object)} method(s):<pre>
* {(x, y) such that x.equals(y)}. </pre>
*
+ * In other words, when the imposed ordering is consistent with
+ * equals, the equivalence classes defined by the equivalence relation
+ * of the {@code equals} method and the equivalence classes defined by
+ * the quotient of the {@code compare} method are the same.
+
* <p>Unlike {@code Comparable}, a comparator may optionally permit
* comparison of null arguments, while maintaining the requirements for
* an equivalence relation.
@@ -112,8 +117,8 @@
* zero, or a positive integer as the first argument is less than, equal
* to, or greater than the second.<p>
*
- * The implementor must ensure that {@code sgn(compare(x, y)) ==
- * -sgn(compare(y, x))} for all {@code x} and {@code y}. (This
+ * The implementor must ensure that {@link Integer#signum signum}{@code (compare(x, y)) ==
+ * -signum(compare(y, x))} for all {@code x} and {@code y}. (This
* implies that {@code compare(x, y)} must throw an exception if and only
* if {@code compare(y, x)} throws an exception.)<p>
*
@@ -122,21 +127,16 @@
* {@code compare(x, z)>0}.<p>
*
* Finally, the implementor must ensure that {@code compare(x, y)==0}
- * implies that {@code sgn(compare(x, z))==sgn(compare(y, z))} for all
+ * implies that {@code signum(compare(x, z))==signum(compare(y, z))} for all
* {@code z}.<p>
*
+ * @apiNote
* It is generally the case, but <i>not</i> strictly required that
* {@code (compare(x, y)==0) == (x.equals(y))}. Generally speaking,
* any comparator that violates this condition should clearly indicate
* this fact. The recommended language is "Note: this comparator
* imposes orderings that are inconsistent with equals."<p>
*
- * In the foregoing description, the notation
- * {@code sgn(}<i>expression</i>{@code )} designates the mathematical
- * <i>signum</i> function, which is defined to return one of {@code -1},
- * {@code 0}, or {@code 1} according to whether the value of
- * <i>expression</i> is negative, zero, or positive, respectively.
- *
* @param o1 the first object to be compared.
* @param o2 the second object to be compared.
* @return a negative integer, zero, or a positive integer as the
@@ -155,8 +155,8 @@
* {@link Object#equals(Object)}. Additionally, this method can return
* {@code true} <i>only</i> if the specified object is also a comparator
* and it imposes the same ordering as this comparator. Thus,
- * {@code comp1.equals(comp2)} implies that {@code sgn(comp1.compare(o1,
- * o2))==sgn(comp2.compare(o1, o2))} for every object reference
+ * {@code comp1.equals(comp2)} implies that {@link Integer#signum signum}{@code (comp1.compare(o1,
+ * o2))==signum(comp2.compare(o1, o2))} for every object reference
* {@code o1} and {@code o2}.<p>
*
* Note that it is <i>always</i> safe <i>not</i> to override