What methods should go into a java.util.Objects class in JDK 7?

[Joe Darcy]

Joe Darcy wrote:
> Joe Darcy wrote:
>> Joe Darcy wrote:
>>> Stephen Colebourne wrote:
>>>> Joe Darcy wrote:
>>>>> What other utility methods would have broad enough use and 
>>>>> applicability to go into a common java.util class?
>>>>
>>>> Joe,
>>>> You've asked for a call for ideas, but not given any indication of 
>>>> process. Are you going to evaluate everything that comes in and 
>>>> pick the best a la Coin? Or allow anyone to send in patches? 
>>>
>>> Those options are not mutually exclusive; patches are welcome 
>>> subject to the usual terms and conditions.
>>>
>>>> Who decides what is in and what is out?
>>>
>>> This is a little side project of mine and I wanted to get some 
>>> feedback before preparing a formal change for review, possibly 
>>> including patches from others.
>>>
>>> -Joe
>>
>> I'm getting caught up after the JVM Languages Summit and will post 
>> some java.util.Objects code for review in the near future.
>>
>> -Joe
>
> Below is a patch implementing the methods I think should go into 
> java.util.Objects as a first cut:
>
> * null safe two-argument equals method
> * null safe hashCode(Object) returning 0 for null
> * null safe toString(Object), returning "null" for a null argument
> * null tolerating compare method; tests if both arguments are == and 
> if not calls compare
>
> The need for the last of these in Objects isn't quite as clear.
>
> Var-arg-ifying some of the existing methods in Arrays, 
> (hashCode(Object[]), deepHashCode(Object[]) and toString(Object[])), 
> is probably worthwhile but can be done separately.
>
> I wouldn't oppose a toDebugString(Object) method going into the 
> platform somewhere, but I don't think it necessarily belongs in Objects.
>
> Further below is the code for an annotation processor which finds 
> candidate equals methods to be replaced with Objects.equals.  It found 
> over half a dozen good candidates in the jdk repository.  To run the 
> annotation processor, first compile the class and then run it with 
> javac similar to this:
>
> javac -proc:only -processor EqualsFinder -processorpath <path to 
> processor> sources
>
> -Joe
>

Updated patch of java.util.Objects with some spec clarifications 
suggested by Alan Bateman and the use of and reference to 
String.valueOf(Object) observed by Jason Mehrens.

-Joe


--- /dev/null    2009-08-12 17:12:33.000000000 -0700
+++ new/src/share/classes/java/util/Objects.java    2009-10-06 
15:47:16.000000000 -0700
@@ -0,0 +1,100 @@
+/*
+ * 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.
+ *
+ * @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.
+     *
+     * @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.
+     *
+     * @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.
+     *
+     * @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) {
+        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 argument 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.
+     *
+     * @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);
+    }
+}