5066247: Refine the spec of equals() and hashCode() for j.text.Format classes

Reviewed-by: naoto, darcy

Author: Justin Lu

src/java.base/share/classes/java/text/ChoiceFormat.java

@@ -572,7 +572,11 @@ public Object clone()
     }
 
     /**
-     * Generates a hash code for the message format object.
+     * {@return the hash code for this {@code ChoiceFormat}}
+     *
+     * @implSpec This method calculates the hash code value using the values returned by
+     * {@link #getFormats()} and {@link #getLimits()}.
+     * @see Object#hashCode()
      */
     @Override
     public int hashCode() {
@@ -585,7 +589,17 @@ public int hashCode() {
     }
 
     /**
-     * Equality comparison between two
+     * Compares the specified object with this {@code ChoiceFormat} for equality.
+     * Returns true if the object is also a {@code ChoiceFormat} and the
+     * two formats would format any value the same.
+     *
+     * @implSpec This method performs an equality check with a notion of class
+     * identity based on {@code getClass()}, rather than {@code instanceof}.
+     * Therefore, in the equals methods in subclasses, no instance of this class
+     * should compare as equal to an instance of a subclass.
+     * @param  obj object to be compared for equality
+     * @return {@code true} if the specified object is equal to this {@code ChoiceFormat}
+     * @see Object#equals(Object)
      */
     @Override
     public boolean equals(Object obj) {

src/java.base/share/classes/java/text/CompactNumberFormat.java

@@ -2343,13 +2343,17 @@ public void setParseBigDecimal(boolean newValue) {
     }
 
     /**
-     * Checks if this {@code CompactNumberFormat} is equal to the
-     * specified {@code obj}. The objects of type {@code CompactNumberFormat}
-     * are compared, other types return false; obeys the general contract of
-     * {@link java.lang.Object#equals(java.lang.Object) Object.equals}.
+     * Compares the specified object with this {@code CompactNumberFormat} for equality.
+     * Returns true if the object is also a {@code CompactNumberFormat} and the
+     * two formats would format any value the same.
      *
+     * @implSpec This method performs an equality check with a notion of class
+     * identity based on {@code getClass()}, rather than {@code instanceof}.
+     * Therefore, in the equals methods in subclasses, no instance of this class
+     * should compare as equal to an instance of a subclass.
      * @param obj the object to compare with
      * @return true if this is equal to the other {@code CompactNumberFormat}
+     * @see Object#hashCode()
      */
     @Override
     public boolean equals(Object obj) {
@@ -2373,7 +2377,11 @@ public boolean equals(Object obj) {
     }
 
     /**
-     * {@return the hash code for this {@code CompactNumberFormat} instance}
+     * {@return the hash code for this {@code CompactNumberFormat}}
+     *
+     * @implSpec Non-transient instance fields of this class are used to calculate
+     * a hash code value which adheres to the contract defined in {@link Objects#hashCode}
+     * @see Object#hashCode()
      */
     @Override
     public int hashCode() {

src/java.base/share/classes/java/text/DateFormat.java

@@ -767,15 +767,29 @@ public boolean isLenient()
     }
 
     /**
-     * Overrides hashCode
+     * {@return the hash code for this {@code DateFormat}}
+     *
+     * @implSpec This method calculates the hash code value using the value returned by
+     * {@link #getNumberFormat()}.
+     * @see Object#hashCode()
      */
     public int hashCode() {
         return numberFormat.hashCode();
         // just enough fields for a reasonable distribution
     }
 
     /**
-     * Overrides equals
+     * Compares the specified object with this {@code DateFormat} for equality.
+     * Returns true if the object is also a {@code DateFormat} and the
+     * two formats would format any value the same.
+     *
+     * @implSpec This method performs an equality check with a notion of class
+     * identity based on {@code getClass()}, rather than {@code instanceof}.
+     * Therefore, in the equals methods in subclasses, no instance of this class
+     * should compare as equal to an instance of a subclass.
+     * @param  obj object to be compared for equality
+     * @return {@code true} if the specified object is equal to this {@code DateFormat}
+     * @see Object#equals(Object)
      */
     public boolean equals(Object obj) {
         if (this == obj) return true;

src/java.base/share/classes/java/text/DateFormatSymbols.java

@@ -657,8 +657,11 @@ public Object clone()
     }
 
     /**
-     * Override hashCode.
-     * Generates a hash code for the DateFormatSymbols object.
+     * {@return the hash code for this {@code DateFormatSymbols}}
+     *
+     * @implSpec Non-transient instance fields of this class are used to calculate
+     * a hash code value which adheres to the contract defined in {@link Objects#hashCode}.
+     * @see Object#hashCode()
      */
     @Override
     public int hashCode() {
@@ -682,7 +685,17 @@ public int hashCode() {
     }
 
     /**
-     * Override equals
+     * Compares the specified object with this {@code DateFormatSymbols} for equality.
+     * Returns true if the object is also a {@code DateFormatSymbols} and the two
+     * {@code DateFormatSymbols} objects represent the same date-time formatting data.
+     *
+     * @implSpec This method performs an equality check with a notion of class
+     * identity based on {@code getClass()}, rather than {@code instanceof}.
+     * Therefore, in the equals methods in subclasses, no instance of this class
+     * should compare as equal to an instance of a subclass.
+     * @param  obj object to be compared for equality
+     * @return {@code true} if the specified object is equal to this {@code DateFormatSymbols}
+     * @see Object#equals(Object)
      */
     @Override
     public boolean equals(Object obj)

src/java.base/share/classes/java/text/DecimalFormat.java

@@ -2928,7 +2928,17 @@ public Object clone() {
     }
 
     /**
-     * Overrides equals
+     * Compares the specified object with this {@code DecimalFormat} for equality.
+     * Returns true if the object is also a {@code DecimalFormat} and the
+     * two formats would format any value the same.
+     *
+     * @implSpec This method performs an equality check with a notion of class
+     * identity based on {@code getClass()}, rather than {@code instanceof}.
+     * Therefore, in the equals methods in subclasses, no instance of this class
+     * should compare as equal to an instance of a subclass.
+     * @param  obj object to be compared for equality
+     * @return {@code true} if the specified object is equal to this {@code DecimalFormat}
+     * @see Object#equals(Object)
      */
     @Override
     public boolean equals(Object obj)
@@ -2973,7 +2983,12 @@ public boolean equals(Object obj)
     }
 
     /**
-     * Overrides hashCode
+     * {@return the hash code for this {@code DecimalFormat}}
+     *
+     * @implSpec This method calculates the hash code value using the values returned from
+     * {@link #getPositivePrefix()} and {@link NumberFormat#hashCode()}.
+     * @see Object#hashCode()
+     * @see NumberFormat#hashCode()
      */
     @Override
     public int hashCode() {

src/java.base/share/classes/java/text/DecimalFormatSymbols.java

@@ -737,7 +737,17 @@ public Object clone() {
     }
 
     /**
-     * Override equals.
+     * Compares the specified object with this {@code DecimalFormatSymbols} for equality.
+     * Returns true if the object is also a {@code DecimalFormatSymbols} and the two
+     * {@code DecimalFormatSymbols} objects represent the same set of symbols.
+     *
+     * @implSpec This method performs an equality check with a notion of class
+     * identity based on {@code getClass()}, rather than {@code instanceof}.
+     * Therefore, in the equals methods in subclasses, no instance of this class
+     * should compare as equal to an instance of a subclass.
+     * @param  obj object to be compared for equality
+     * @return {@code true} if the specified object is equal to this {@code DecimalFormatSymbols}
+     * @see Object#equals(Object)
      */
     @Override
     public boolean equals(Object obj) {
@@ -767,7 +777,11 @@ public boolean equals(Object obj) {
     }
 
     /**
-     * Override hashCode.
+     * {@return the hash code for this {@code DecimalFormatSymbols}}
+     *
+     * @implSpec Non-transient instance fields of this class are used to calculate
+     * a hash code value which adheres to the contract defined in {@link Objects#hashCode}.
+     * @see Object#hashCode()
      */
     @Override
     public int hashCode() {

src/java.base/share/classes/java/text/MessageFormat.java

@@ -1141,7 +1141,17 @@ public Object clone() {
     }
 
     /**
-     * Equality comparison between two message format objects
+     * Compares the specified object with this {@code MessageFormat} for equality.
+     * Returns true if the object is also a {@code MessageFormat} and the
+     * two formats would format any value the same.
+     *
+     * @implSpec This method performs an equality check with a notion of class
+     * identity based on {@code getClass()}, rather than {@code instanceof}.
+     * Therefore, in the equals methods in subclasses, no instance of this class
+     * should compare as equal to an instance of a subclass.
+     * @param  obj object to be compared for equality
+     * @return {@code true} if the specified object is equal to this {@code MessageFormat}
+     * @see Object#equals(Object)
      */
     @Override
     public boolean equals(Object obj) {
@@ -1159,7 +1169,11 @@ public boolean equals(Object obj) {
     }
 
     /**
-     * Generates a hash code for the message format object.
+     * {@return the hash code value for this {@code MessageFormat}}
+     *
+     * @implSpec This method calculates the hash code value using the value returned by
+     * {@link #toPattern()}.
+     * @see Object#hashCode()
      */
     @Override
     public int hashCode() {

src/java.base/share/classes/java/text/NumberFormat.java

@@ -698,7 +698,11 @@ public static Locale[] getAvailableLocales() {
     }
 
     /**
-     * Overrides hashCode.
+     * {@return the hash code for this {@code NumberFormat}}
+     *
+     * @implSpec This method calculates the hash code value using the values returned by
+     * {@link #getMaximumIntegerDigits()} and {@link #getMaximumFractionDigits()}.
+     * @see Object#hashCode()
      */
     @Override
     public int hashCode() {
@@ -707,7 +711,17 @@ public int hashCode() {
     }
 
     /**
-     * Overrides equals.
+     * Compares the specified object with this {@code NumberFormat} for equality.
+     * Returns true if the object is also a {@code NumberFormat} and the
+     * two formats would format any value the same.
+     *
+     * @implSpec This method performs an equality check with a notion of class
+     * identity based on {@code getClass()}, rather than {@code instanceof}.
+     * Therefore, in the equals methods in subclasses, no instance of this class
+     * should compare as equal to an instance of a subclass.
+     * @param  obj object to be compared for equality
+     * @return {@code true} if the specified object is equal to this {@code NumberFormat}
+     * @see Object#equals(Object)
      */
     @Override
     public boolean equals(Object obj) {

src/java.base/share/classes/java/text/SimpleDateFormat.java

@@ -2409,7 +2409,11 @@ public Object clone() {
     }
 
     /**
-     * {@return the hash code value for this {@code SimpleDateFormat} object}
+     * {@return the hash code value for this {@code SimpleDateFormat}}
+     *
+     * @implSpec This method calculates the hash code value using the value returned by
+     * {@link #toPattern()}.
+     * @see Object#hashCode()
      */
     @Override
     public int hashCode()
@@ -2419,11 +2423,17 @@ public int hashCode()
     }
 
     /**
-     * Compares the given object with this {@code SimpleDateFormat} for
-     * equality.
+     * Compares the specified object with this {@code SimpleDateFormat} for equality.
+     * Returns true if the object is also a {@code SimpleDateFormat} and the
+     * two formats would format any value the same.
      *
-     * @return true if the given object is equal to this
-     * {@code SimpleDateFormat}
+     * @implSpec This method performs an equality check with a notion of class
+     * identity based on {@code getClass()}, rather than {@code instanceof}.
+     * Therefore, in the equals methods in subclasses, no instance of this class
+     * should compare as equal to an instance of a subclass.
+     * @param  obj object to be compared for equality
+     * @return {@code true} if the specified object is equal to this {@code SimpleDateFormat}
+     * @see Object#equals(Object)
      */
     @Override
     public boolean equals(Object obj)