Implement java.util.Objects.

2015-01-06  Andrew John Hughes  <gnu_andrew@member.fsf.org>

	* NEWS: Updated.
	* java/util/Objects.java: New class.
	(compareTo(T,T,Comparator)): Implemented.
	(deepEquals(Object,Object)): Likewise.
	(equals(Object,Object)): Likewise.
	(hash(Object...)): Likewise.
	(hashCode(Object)): Likewise.
	(requireNonNull(T)): Likewise.
	(requireNonNull(T,String)): Likewise.
	(toString(Object)): Likewise.
	(toString(Object,String)): Likewise.

Signed-off-by: Andrew John Hughes <gnu_andrew@member.fsf.org>

3 files changed, 317 insertions, 0 deletions

diff --git a/ChangeLog b/ChangeLog
index f2b03b028..0abf14e4e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+2015-01-06  Andrew John Hughes  <gnu_andrew@member.fsf.org>
+
+	* NEWS: Updated.
+	* java/util/Objects.java: New class.
+	(compareTo(T,T,Comparator)): Implemented.
+	(deepEquals(Object,Object)): Likewise.
+	(equals(Object,Object)): Likewise.
+	(hash(Object...)): Likewise.
+	(hashCode(Object)): Likewise.
+	(requireNonNull(T)): Likewise.
+	(requireNonNull(T,String)): Likewise.
+	(toString(Object)): Likewise.
+	(toString(Object,String)): Likewise.
+
 2014-12-15  Andrew John Hughes  <gnu_andrew@member.fsf.org>
 
 	PR classpath/64176
diff --git a/NEWS b/NEWS
index 916184869..9f5149a92 100644
--- a/NEWS
+++ b/NEWS
@@ -12,6 +12,13 @@ CVE-XXXX-YYYY: http://www.cve.mitre.org/cgi-bin/cvename.cgi?name=XXXX-YYYY
 
 New in release 0.99.1 (XXX XX, 2012)
 
+* Addition of java.util.Objects
+* Addition of java.lang.model.*
+* Addition of java.lang.model.element.*
+* Addition of java.lang.model.type.*
+* Addition of java.lang.model.util.*
+* Addition of javax.annotation.processing.*
+* Addition of javax.tools.*
 * Bug fixes:
   - PR42134: NPE in java.text.Bidi
   - PR54931: Classpath will not build docs with version of GJDoc included with itself
diff --git a/java/util/Objects.java b/java/util/Objects.java
new file mode 100644
index 000000000..6917f2cc6
--- /dev/null
+++ b/java/util/Objects.java
@@ -0,0 +1,296 @@
+/* Objects.java -- Utility methods for working with objects.
+   Copyright 2014, 2015 Free Software Foundation, Inc.
+
+This file is a part of GNU Classpath.
+
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or (at
+your option) any later version.
+
+GNU Classpath 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 for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; if not, write to the Free Software
+Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301
+USA
+
+Linking this library statically or dynamically with other modules is
+making a combined work based on this library.  Thus, the terms and
+conditions of the GNU General Public License cover the whole
+combination.
+
+As a special exception, the copyright holders of this library give you
+permission to link this library with independent modules to produce an
+executable, regardless of the license terms of these independent
+modules, and to copy and distribute the resulting executable under
+terms of your choice, provided that you also meet, for each linked
+independent module, the terms and conditions of the license of that
+module.  An independent module is a module which is not derived from
+or based on this library.  If you modify this library, you may extend
+this exception to your version of the library, but you are not
+obligated to do so.  If you do not wish to do so, delete this
+exception statement from your version.  */
+
+package java.util;
+
+/**
+ * This class collects together a number of utility methods
+ * for working with objects. It includes implementations of
+ * {@link java.lang.Object#hashCode}, {@link java.lang.Object#toString}
+ * and {@link java.lang.Object#equals(boolean)} which are
+ * safe to use when one or more of the supplied objects
+ * are {@code null}.
+ *
+ * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
+ * @since 1.7
+ */
+public final class Objects
+{
+
+  /**
+   * <p>
+   * Compares the two arguments using the specified
+   * {@link Comparator} object and can be used to
+   * order such objects. A negative integer is
+   * returned if the first argument is less than
+   * the second and a positive integer if it is
+   * greater. If both arguments are equal (including
+   * if both arguments are {@code null}), zero is
+   * returned.
+   * </p>
+   * <p>
+   * The method may throw a {@link NullPointerException}
+   * if one argument is {@code null} but not the other.
+   * This behaviour depends on the behaviour of the
+   * {@code Comparator} object supplied.
+   * </p>
+   *
+   * @param T the type of objects to compare.
+   * @param a the first object.
+   * @param b the object to compare to {@code a}.
+   * @param c the comparator to use to compare the objects.
+   * @return 0 if the objects are equal, {@code c.compare(a,b)}
+   *         otherwise.
+   * @see java.lang.Comparable
+   * @see java.util.Comparator
+   */
+  public static <T> int compare(T a, T b, Comparator<? super T> c)
+  {
+    if (a == b)
+      return 0;
+    return c.compare(a,b);
+  }
+
+  /**
+   * <p>
+   * Returns true if the two arguments are <emph>deeply equal</emph>
+   * to one another. Deep equality is defined as follows:
+   * </p>
+   * <ul>
+   * <li>If both objects are {@code null}, the result is {@code true}.</li>
+   * <li>If one object is {@code null} and the other is not, the result is
+   * false.</li>
+   * <li>If both objects are arrays of primitive types, the result is
+   * equal to {@code Arrays.equals(a,b)}.</li>
+   * <li>If both objects are arrays of {@code Object}s, the result is equal to
+   * {@code Arrays.deepEquals(a,b)}.</li>
+   * <li>Otherwise, the result is equal to {@code a.equals(b)}.</li>
+   * </ul>
+   *
+   * @param a the first object.
+   * @param b the object to be compared with {@code b}.
+   * @return true if the objects are deeply equal, as defined above.
+   * @see java.util.Arrays#deepEquals(Object[],Object[])
+   * @see java.lang.Object#equals(Object)
+   * @see #equals(Object,Object)
+   */
+  public static boolean deepEquals(Object a, Object b)
+  {
+    if (a == null && b == null)
+      return true;
+    if (a == null || b == null)
+      return false;
+
+    Class<?> aClass = a.getClass();
+    Class<?> bClass = b.getClass();
+    if (aClass.isArray() && bClass.isArray())
+      {
+        if (aClass == bClass)
+          {
+            if (aClass == boolean[].class)
+              return Arrays.equals((boolean[]) a, (boolean[]) b);
+            if (aClass == byte[].class)
+              return Arrays.equals((byte[]) a, (byte[]) b);
+            if (aClass == char[].class)
+              return Arrays.equals((char[]) a, (char[]) b);
+            if (aClass == double[].class)
+              return Arrays.equals((double[]) a, (double[]) b);
+            if (aClass == float[].class)
+              return Arrays.equals((float[]) a, (float[]) b);
+            if (aClass == int[].class)
+              return Arrays.equals((int[]) a, (int[]) b);
+            if (aClass == long[].class)
+              return Arrays.equals((long[]) a, (long[]) b);
+            if (aClass == short[].class)
+              return Arrays.equals((short[]) a, (short[]) b);
+          }
+        if (Object[].class.isAssignableFrom(a.getClass()) &&
+            Object[].class.isAssignableFrom(b.getClass()))
+          return Arrays.deepEquals((Object[]) a, (Object[]) b);
+      }
+
+    return equals(a, b);
+  }
+
+  /**
+   * <p>
+   * Returns true if the two arguments are <emph>equal</emph>
+   * to one another. Equality is defined as follows:
+   * </p>
+   * <ul>
+   * <li>If both objects are {@code null}, the result is {@code true}.</li>
+   * <li>If one object is {@code null} and the other is not, the result is
+   * false.</li>
+   * <li>Otherwise, the result is equal to {@code a.equals(b)}.</li>
+   * </ul>
+   *
+   * @param a the first object.
+   * @param b the object to be compared with {@code b}.
+   * @return true if the objects are deeply equal, as defined above.
+   * @see java.util.Arrays#deepEquals(Object[],Object[])
+   * @see java.lang.Object#equals(Object)
+   * @see #equals(Object,Object)
+   */
+  public static boolean equals(Object a, Object b)
+  {
+    if (a == null && b == null)
+      return true;
+    if (a == null || b == null)
+      return false;
+
+    return a.equals(b);
+  }
+
+  /**
+   * <p>
+   * Generates a hash code from the specified input values.
+   * The hash code generated is the same as if each value
+   * was added to an array of {@code Object}s and the
+   * method {@code Arrays.hashCode(Object[])} run on this
+   * array. In turn, this is the same as if
+   * {@code Arrays.asList} was run on the array and the
+   * result obtained from the {@code hashCode()} method
+   * of the resulting {@code List} object.
+   * </p>
+   * <p>As a consequence, this means that, for a single
+   * object, {@code x}, the value returned by this method
+   * is not equal to {@code x.hashCode()} or
+   * {@code hashCode(x)}, but to
+   * <code>Arrays.hashCode(new Object[]{x})}</code>.
+   * </p>
+   *
+   * @param values the values to compute the hash code of.
+   * @return the hash code of the sequence of values.
+   * @see java.util.Arrays#hashCode(Object[])
+   * @see java.util.Arrays#asList(Object[])
+   * @see #hashCode(Object)
+   */
+  public static int hash(Object... values)
+  {
+    return Arrays.hashCode(values);
+  }
+
+  /**
+   * Returns the hash code of the supplied argument
+   * if it is not {@code null}, or 0 if it is.
+   *
+   * @param o the object to obtain the hash code of.
+   * @return the hash code of the object, or 0 if
+   *         the object was {@code null}.
+   */
+  public static int hashCode(Object o)
+  {
+    if (o == null)
+      return 0;
+    return o.hashCode();
+  }
+
+  /**
+   * Checks that the supplied argument is not
+   * {@code null}. If it is, then a
+   * {@link NullPointerException} is thrown.
+   * This method is designed as an aid for validating
+   * input parameters to a method.
+   *
+   * @param o the object to check.
+   * @return the object if it is not {@code null}.
+   * @throws NullPointerException if the object is
+   *         {@code null}.
+   */
+  public static <T> T requireNonNull(T o)
+  {
+    if (o == null)
+      throw new NullPointerException();
+    return o;
+  }
+
+  /**
+   * Checks that the supplied argument is not
+   * {@code null}. If it is, then a
+   * {@link NullPointerException} is thrown
+   * using the specified error message.
+   * This method is designed as an aid for validating
+   * input parameters to a method.
+   *
+   * @param o the object to check.
+   * @param message the error message to use.
+   * @return the object if it is not {@code null}.
+   * @throws NullPointerException if the object is
+   *         {@code null}.
+   */
+  public static <T> T requireNonNull(T o, String message)
+  {
+    if (o == null)
+      throw new NullPointerException(message);
+    return o;
+  }
+
+  /**
+   * Returns the {@link Object#toString()} output of
+   * the specified object, or {@code "null"} if the
+   * object is {@code null}.
+   *
+   * @param o the object on which to call {@code toString()}.
+   * @return the output of {@code o.toString()} or
+   *         {@code "null"} if the object was {@code null}.
+   */
+  public static String toString(Object o)
+  {
+    if (o == null)
+      return "null";
+    return o.toString();
+  }
+
+  /**
+   * Returns the {@link Object#toString()} output of
+   * the specified object, or the supplied default
+   * string if the object is {@code null}.
+   *
+   * @param o the object on which to call {@code toString()}.
+   * @param defStr the default string to return if the
+   *        object is {@code null}.
+   * @return the output of {@code o.toString()} or
+   *         {@code defStr} if the object was {@code null}.
+   */
+  public static String toString(Object o, String defStr)
+  {
+    if (o == null)
+      return defStr;
+    return o.toString();
+  }
+
+}