6797535: Add shared two argument static equals method to the platform

Reviewed-by: sherman

jdk/make/java/java/FILES_java.gmk

@@ -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 \

jdk/src/share/classes/java/util/Objects.java

+/*
+ * 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);
+    }
+}

jdk/test/java/util/Objects/BasicObjectsTest.java

+/*
+ * 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;
+    }
+}