JDK-6797535 : Add shared two argument static equals method to the platform
  • Type: Bug
  • Component: core-libs
  • Sub-Component: java.util
  • Affected Version: 5.0,7
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • OS: generic,solaris_9
  • CPU: generic,sparc
  • Submitted: 2009-01-25
  • Updated: 2021-10-14
  • Resolved: 2009-10-24
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 7
7 b75Fixed
Related Reports
Duplicate :  
JDK-5006670 - RFE: Please provide java.util.Objects utility class
Relates :  
JDK-6582946 - Add suite of compare(T, T) methods for ints, longs etc
Relates :  
JDK-8226785 - MandatoryWarningHandler.java contains implementation of Object.equals functionality
Relates :  
JDK-4520573 - Object.equals is not well fitted for 'null' comparison
Relates :  
JDK-8011800 - Add java.util.Objects.requireNonNull(T, Supplier)
Relates :  
JDK-8014357 - Minor refactorings to sun.reflect.generics.reflectiveObjects.*
Relates :  
JDK-6891113 - More methods for java.util.Objects: deepEquals, hash, toString with default
Relates :  
JDK-7068795 - Make java.util.Objects#equals generic
Relates :  
JDK-7041136 - Use Objects.equals in JDK platform classes
Relates :  
JDK-8196069 - Misleading documentation of Objects.equals
Relates :  
JDK-8223112 - Clarify operational semantics of java.util.Objects.equals()
Relates :  
JDK-8015417 - profile pollution after call through invokestatic to shared code
Relates :  
JDK-6889858 - Add nonNull methods to java.util.Objects
Relates :  
JDK-6897166 - java.util.Objects.compare(...): unspecified NullPointerException for null comparator
Description
A common programming need is for a static two argument equals method that does that right thing for nulls; that is, if both arguments are null it returns true, if one argument is null it returns false, and if both arguments are nonnull, it calls a.equals(b).

This idiom is common enough that the platform should have a method to provide this functionality.
Comments
SUGGESTED FIX # HG changeset patch # User darcy # Date 1255129871 25200 # Node ID 3b45b809d8fffc64180d89a1b280de1f04fcbaaf # Parent e7ad502130baae09e4edc34dbf4f129fc5f3946d 6797535: Add shared two argument static equals method to the platform Reviewed-by: sherman --- a/make/java/java/FILES_java.gmk Wed Oct 07 14:04:20 2009 -0700 +++ b/make/java/java/FILES_java.gmk Fri Oct 09 16:11:11 2009 -0700 @@ -258,6 +258,7 @@ JAVA_JAVA_java = \ java/util/ServiceConfigurationError.java \ java/util/Timer.java \ java/util/TimerTask.java \ + java/util/Objects.java \ java/util/UUID.java \ java/util/concurrent/AbstractExecutorService.java \ java/util/concurrent/ArrayBlockingQueue.java \ --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/share/classes/java/util/Objects.java Fri Oct 09 16:11:11 2009 -0700 @@ -0,0 +1,110 @@ +/* + * Copyright 2009 Sun Microsystems, Inc. All Rights Reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Sun designates this + * particular file as subject to the "Classpath" exception as provided + * by Sun in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, + * CA 95054 USA or visit www.sun.com if you need additional information or + * have any questions. + */ + +package java.util; + +/** + * This class consists of {@code static} utility methods for operating + * on objects. These utilities include {@code null}-safe or {@code + * null}-tolerant methods for computing the hash code of an object, + * returning a string for an object, and comparing two objects. + * + * @since 1.7 + */ +public class Objects { + private Objects() { + throw new AssertionError("No java.util.Objects instances for you!"); + } + + /** + * Returns {@code true} if the arguments are equal to each other + * and {@code false} otherwise. + * Consequently, if both arguments are {@code null}, {@code true} + * is returned and if exactly one argument is {@code null}, {@code + * false} is returned. Otherwise, equality is determined by using + * the {@link Object#equals equals} method of the first + * argument. + * + * @param a an object + * @param b an object to be compared with {@code a} for equality + * @return {@code true} if the arguments are equal to each other + * and {@code false} otherwise + * @see Object#equals(Object) + */ + public static boolean equals(Object a, Object b) { + return (a == b) || (a != null && a.equals(b)); + } + + /** + * Returns the hash code of a non-{@code null} argument and 0 for + * a {@code null} argument. + * + * @param o an object + * @return the hash code of a non-{@code null} argument and 0 for + * a {@code null} argument + * @see Object#hashCode + */ + public static int hashCode(Object o) { + return o != null ? o.hashCode() : 0; + } + + /** + * Returns the result of calling {@code toString} for a non-{@code + * null} argument and {@code "null"} for a {@code null} argument. + * + * @param o an object + * @return the result of calling {@code toString} for a non-{@code + * null} argument and {@code "null"} for a {@code null} argument + * @see Object#toString + * @see String#valueOf(Object) + */ + public static String toString(Object o) { + return String.valueOf(o); + } + + /** + * Returns 0 if the arguments are identical and {@code + * c.compare(a, b)} otherwise. + * Consequently, if both arguments are {@code null} 0 + * is returned. + * + * <p>Note that if one of the arguments is {@code null}, a {@code + * NullPointerException} may or may not be thrown depending on + * what ordering policy, if any, the {@link Comparator Comparator} + * chooses to have for {@code null} values. + * + * @param <T> the type of the objects being compared + * @param a an object + * @param b an object to be compared with {@code a} + * @param c the {@code Comparator} to compare the first two arguments + * @return 0 if the arguments are identical and {@code + * c.compare(a, b)} otherwise. + * @see Comparable + * @see Comparator + */ + public static <T> int compare(T a, T b, Comparator<? super T> c) { + return (a == b) ? 0 : c.compare(a, b); + } +} --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/test/java/util/Objects/BasicObjectsTest.java Fri Oct 09 16:11:11 2009 -0700 @@ -0,0 +1,105 @@ +/* + * Copyright 2009 Sun Microsystems, Inc. All Rights Reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, + * CA 95054 USA or visit www.sun.com if you need additional information or + * have any questions. + */ + +/* + * @test + * @bug 6797535 + * @summary Basic tests for methods in java.util.Objects + * @author Joseph D. Darcy + */ + +import java.util.*; + +public class BasicObjectsTest { + public static void main(String... args) { + int errors = 0; + errors += testEquals(); + errors += testHashCode(); + errors += testToString(); + errors += testCompare(); + if (errors > 0 ) + throw new RuntimeException(); + } + + private static int testEquals() { + int errors = 0; + Object[] values = {null, "42", 42}; + for(int i = 0; i < values.length; i++) + for(int j = 0; j < values.length; j++) { + boolean expected = (i == j); + Object a = values[i]; + Object b = values[j]; + boolean result = Objects.equals(a, b); + if (result != expected) { + errors++; + System.err.printf("When equating %s to %s, got %b instead of %b%n.", + a, b, result, expected); + } + } + return errors; + } + + private static int testHashCode() { + int errors = 0; + errors += (Objects.hashCode(null) == 0 ) ? 0 : 1; + String s = "42"; + errors += (Objects.hashCode(s) == s.hashCode() ) ? 0 : 1; + return errors; + } + + private static int testToString() { + int errors = 0; + errors += ("null".equals(Objects.toString(null)) ) ? 0 : 1; + String s = "Some string"; + errors += (s.equals(Objects.toString(s)) ) ? 0 : 1; + return errors; + } + + private static int testCompare() { + int errors = 0; + String[] values = {"e. e. cummings", "zzz"}; + String[] VALUES = {"E. E. Cummings", "ZZZ"}; + errors += compareTest(null, null, 0); + for(int i = 0; i < values.length; i++) { + String a = values[i]; + errors += compareTest(a, a, 0); + for(int j = 0; j < VALUES.length; j++) { + int expected = Integer.compare(i, j); + String b = VALUES[j]; + errors += compareTest(a, b, expected); + } + } + return errors; + } + + private static int compareTest(String a, String b, int expected) { + int errors = 0; + int result = Objects.compare(a, b, String.CASE_INSENSITIVE_ORDER); + if (Integer.signum(result) != Integer.signum(expected)) { + errors++; + System.err.printf("When comparing %s to %s, got %d instead of %d%n.", + a, b, result, expected); + } + return errors; + } +}
09-10-2009
PUBLIC COMMENTS See http://hg.openjdk.java.net/jdk7/tl/jdk/rev/3b45b809d8ff
09-10-2009
PUBLIC COMMENTS See also http://mail.openjdk.java.net/pipermail/core-libs-dev/2009-September/002572.html
09-09-2009
PUBLIC COMMENTS As suggested by Tim Keith, http://mail.openjdk.java.net/pipermail/coin-dev/2009-April/001399.html consider adding a static hashCode method too: public static int hashCode(Object o) { return o == null ? 0 : o.hashCode(); }
03-04-2009
EVALUATION A fine idea.
25-01-2009