java.util.Objects, round two

[Joseph D. Darcy]

Hello.

After recent discussions on the list, the following methods will be 
included in round two of the evolution of java.util.Objects:

Under bug 6889858: Add nonNull methods to java.util.Objects:

  /**
     * Checks that the specified object reference is not {@code null}. This
     * method is designed primarily for doing parameter validation in 
methods
     * and constructors, as demonstrated below:
     * <pre>
     * public Foo(Bar bar) {
     *     this.bar = Objects.nonNull(bar);
     * }
     * </pre>
     *
     * @param obj the object reference to check for nullity
     * @return {@code obj} if not {@code null}
     * @throws NullPointerException if {@code obj} is {@code null}
     */
    public static <T> T nonNull(T obj);
 
    /**
     * Checks that the specified object reference is not {@code null} and
     * throws a customized {@link NullPointerException} if it is. This 
method
     * is designed primarily for doing parameter validation in methods and
     * constructors with multiple parameters, as demonstrated below:
     * <pre>
     * public Foo(Bar bar, Baz baz) {
     *     this.bar = Objects.nonNull(bar, "bar must not be null");
     *     this.baz = Objects.nonNull(baz, "baz must not be null");
     * }
     * </pre>
     *
     * @param obj     the object reference to check for nullity
     * @param message detail message to be used in the event that a {@code
     *                NullPointerException} is thrown
     * @return {@code obj} if not {@code null}
     * @throws NullPointerException if {@code obj} is {@code null}
     */
    public static <T> T nonNull(T obj, String message);

 Under bug 6891113:  More methods for java.util.Objects: deepEquals, 
hash, toString with default
    /**
     * Returns {@code true} if the arguments are deeply equal to each other
     * and {@code false} otherwise.
     *
     * Two {@code null} values are deeply equal.  If both arguments are
     * arrays, the algorithm in {@link Arrays.deepEquals(Object[],
     * Object[]) Arrays.deepEquals) is used to determine equality.
     * Otherwise, equality is determined by using the {@link Object#equals
     * equals} method of the first argument.
     *
     * @return {@code true} if the arguments are deeply equal to each other
     * and {@code false} otherwise
     * @see Arrays#deepEquals(Object[], Object[])
     * @see Objects#equals(Object, Object)
     */
    public static deepEquals(Object a, Object b);
       
    /**
     * Returns the result of calling {@code toString} on the first
     * argument if the first argument is not {@code null} and returns
     * the second argument otherwise.
     *
     * @return the result of calling {@code toString} on the first
     * argument if it is not {@code null} and the second argument
     * otherwise.
     * @see Objects#toString(Object)
     */
    public static toString(Object a, String nullDefault);
 
    /**
     * Generates a hash code for a sequence of input values. The hash 
code is
     * generated as if all the input values were placed into an array, 
and that
     * array were hashed by calling {@link Arrays#hashCode(Object[])}.
     *
     * <p>This method is useful for implementing {@link 
Object#hashCode()} on
     * objects containing multiple fields. For example, if an object 
that has
     * three  fields, {@code x}, {@code y}, and {@code z}, one could write:
     * <pre>
     * @Override public int hashCode() {
     *     return Objects.hashCode(x, y, z);
     * }
     * </pre>
     * <b>Warning: When a single object reference is supplied, the returned
     * value does not equal the hash code of that object reference.</b> This
     * value can be computed by calling {@link #hashCode(Object)}.
     *
     * @return a hash value of the sequence of input values
     * @see Arrays#hashCode
     */
    public static int hash(Object... components);

In addition, the Objects class will be explicitly marked as "final" to 
indicate its already implicit status as a non-instantiable, 
non-extendable class.

I've closed as "will not fix" the bug requesting to var-argify various 
constructors in String.

I'm open having being convinced that "toDefaultString(Object)" is a 
worthwhile addition to j.u.Objects as well.

Likewise, for "toDebugString(Object)", although someone else would have 
to specify, implement, and test that method.

-Joe