From 8fcf70e931cd2e69e644c459d16d1410ce7ff3ae Mon Sep 17 00:00:00 2001 From: Justin Lu Date: Mon, 2 Oct 2023 05:06:45 +0000 Subject: [PATCH] 5066247: Refine the spec of equals() and hashCode() for j.text.Format classes Reviewed-by: naoto, darcy --- .../share/classes/java/text/ChoiceFormat.java | 18 +++++++++++++++-- .../java/text/CompactNumberFormat.java | 18 ++++++++++++----- .../share/classes/java/text/DateFormat.java | 18 +++++++++++++++-- .../classes/java/text/DateFormatSymbols.java | 19 +++++++++++++++--- .../classes/java/text/DecimalFormat.java | 19 ++++++++++++++++-- .../java/text/DecimalFormatSymbols.java | 18 +++++++++++++++-- .../classes/java/text/MessageFormat.java | 18 +++++++++++++++-- .../share/classes/java/text/NumberFormat.java | 18 +++++++++++++++-- .../classes/java/text/SimpleDateFormat.java | 20 ++++++++++++++----- 9 files changed, 141 insertions(+), 25 deletions(-) diff --git a/src/java.base/share/classes/java/text/ChoiceFormat.java b/src/java.base/share/classes/java/text/ChoiceFormat.java index a75aad0a303..ed49b11bd45 100644 --- a/src/java.base/share/classes/java/text/ChoiceFormat.java +++ b/src/java.base/share/classes/java/text/ChoiceFormat.java @@ -572,7 +572,11 @@ public class ChoiceFormat extends NumberFormat { } /** - * 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 class ChoiceFormat extends NumberFormat { } /** - * 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) { diff --git a/src/java.base/share/classes/java/text/CompactNumberFormat.java b/src/java.base/share/classes/java/text/CompactNumberFormat.java index 14df610621f..3926a807b41 100644 --- a/src/java.base/share/classes/java/text/CompactNumberFormat.java +++ b/src/java.base/share/classes/java/text/CompactNumberFormat.java @@ -2343,13 +2343,17 @@ public final class CompactNumberFormat extends NumberFormat { } /** - * 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 final class CompactNumberFormat extends NumberFormat { } /** - * {@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() { diff --git a/src/java.base/share/classes/java/text/DateFormat.java b/src/java.base/share/classes/java/text/DateFormat.java index 162a89d7915..d5083f11965 100644 --- a/src/java.base/share/classes/java/text/DateFormat.java +++ b/src/java.base/share/classes/java/text/DateFormat.java @@ -767,7 +767,11 @@ public abstract class DateFormat extends Format { } /** - * 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(); @@ -775,7 +779,17 @@ public abstract class DateFormat extends Format { } /** - * 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; diff --git a/src/java.base/share/classes/java/text/DateFormatSymbols.java b/src/java.base/share/classes/java/text/DateFormatSymbols.java index d89c11f2c5a..372752bf737 100644 --- a/src/java.base/share/classes/java/text/DateFormatSymbols.java +++ b/src/java.base/share/classes/java/text/DateFormatSymbols.java @@ -657,8 +657,11 @@ public class DateFormatSymbols implements Serializable, Cloneable { } /** - * 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 class DateFormatSymbols implements Serializable, Cloneable { } /** - * 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) diff --git a/src/java.base/share/classes/java/text/DecimalFormat.java b/src/java.base/share/classes/java/text/DecimalFormat.java index 0cb7d430c8a..23c20266f41 100644 --- a/src/java.base/share/classes/java/text/DecimalFormat.java +++ b/src/java.base/share/classes/java/text/DecimalFormat.java @@ -2928,7 +2928,17 @@ public class DecimalFormat extends NumberFormat { } /** - * 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 class DecimalFormat extends NumberFormat { } /** - * 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() { diff --git a/src/java.base/share/classes/java/text/DecimalFormatSymbols.java b/src/java.base/share/classes/java/text/DecimalFormatSymbols.java index b5f2b404f78..eb47763faa5 100644 --- a/src/java.base/share/classes/java/text/DecimalFormatSymbols.java +++ b/src/java.base/share/classes/java/text/DecimalFormatSymbols.java @@ -737,7 +737,17 @@ public class DecimalFormatSymbols implements Cloneable, Serializable { } /** - * 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 class DecimalFormatSymbols implements Cloneable, Serializable { } /** - * 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() { diff --git a/src/java.base/share/classes/java/text/MessageFormat.java b/src/java.base/share/classes/java/text/MessageFormat.java index 76237df2972..89acc14cdb1 100644 --- a/src/java.base/share/classes/java/text/MessageFormat.java +++ b/src/java.base/share/classes/java/text/MessageFormat.java @@ -1141,7 +1141,17 @@ public class MessageFormat extends Format { } /** - * 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 class MessageFormat extends Format { } /** - * 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() { diff --git a/src/java.base/share/classes/java/text/NumberFormat.java b/src/java.base/share/classes/java/text/NumberFormat.java index 19d4e2b6ee2..86f56f9dd94 100644 --- a/src/java.base/share/classes/java/text/NumberFormat.java +++ b/src/java.base/share/classes/java/text/NumberFormat.java @@ -698,7 +698,11 @@ public abstract class NumberFormat extends Format { } /** - * 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 abstract class NumberFormat extends Format { } /** - * 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) { diff --git a/src/java.base/share/classes/java/text/SimpleDateFormat.java b/src/java.base/share/classes/java/text/SimpleDateFormat.java index b4bb3e3f31e..ee6ff005c49 100644 --- a/src/java.base/share/classes/java/text/SimpleDateFormat.java +++ b/src/java.base/share/classes/java/text/SimpleDateFormat.java @@ -2409,7 +2409,11 @@ public class SimpleDateFormat extends DateFormat { } /** - * {@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 class SimpleDateFormat extends DateFormat { } /** - * 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)