rev 7044 : 8013712: Add Objects.nonNull and Objects.isNull
Reviewed-by: duke

   1 /*
   2  * Copyright (c) 2009, 2011, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.util;
  27 
  28 /**
  29  * This class consists of {@code static} utility methods for operating
  30  * on objects.  These utilities include {@code null}-safe or {@code
  31  * null}-tolerant methods for computing the hash code of an object,
  32  * returning a string for an object, and comparing two objects.
  33  *
  34  * @since 1.7
  35  */
  36 public final class Objects {
  37     private Objects() {
  38         throw new AssertionError("No java.util.Objects instances for you!");
  39     }
  40 
  41     /**
  42      * Returns {@code true} if the arguments are equal to each other
  43      * and {@code false} otherwise.
  44      * Consequently, if both arguments are {@code null}, {@code true}
  45      * is returned and if exactly one argument is {@code null}, {@code
  46      * false} is returned.  Otherwise, equality is determined by using
  47      * the {@link Object#equals equals} method of the first
  48      * argument.
  49      *
  50      * @param a an object
  51      * @param b an object to be compared with {@code a} for equality
  52      * @return {@code true} if the arguments are equal to each other
  53      * and {@code false} otherwise
  54      * @see Object#equals(Object)
  55      */
  56     public static boolean equals(Object a, Object b) {
  57         return (a == b) || (a != null && a.equals(b));
  58     }
  59 
  60    /**
  61     * Returns {@code true} if the arguments are deeply equal to each other
  62     * and {@code false} otherwise.
  63     *
  64     * Two {@code null} values are deeply equal.  If both arguments are
  65     * arrays, the algorithm in {@link Arrays#deepEquals(Object[],
  66     * Object[]) Arrays.deepEquals} is used to determine equality.
  67     * Otherwise, equality is determined by using the {@link
  68     * Object#equals equals} method of the first argument.
  69     *
  70     * @param a an object
  71     * @param b an object to be compared with {@code a} for deep equality
  72     * @return {@code true} if the arguments are deeply equal to each other
  73     * and {@code false} otherwise
  74     * @see Arrays#deepEquals(Object[], Object[])
  75     * @see Objects#equals(Object, Object)
  76     */
  77     public static boolean deepEquals(Object a, Object b) {
  78         if (a == b)
  79             return true;
  80         else if (a == null || b == null)
  81             return false;
  82         else
  83             return Arrays.deepEquals0(a, b);
  84     }
  85 
  86     /**
  87      * Returns the hash code of a non-{@code null} argument and 0 for
  88      * a {@code null} argument.
  89      *
  90      * @param o an object
  91      * @return the hash code of a non-{@code null} argument and 0 for
  92      * a {@code null} argument
  93      * @see Object#hashCode
  94      */
  95     public static int hashCode(Object o) {
  96         return o != null ? o.hashCode() : 0;
  97     }
  98 
  99    /**
 100     * Generates a hash code for a sequence of input values. The hash
 101     * code is generated as if all the input values were placed into an
 102     * array, and that array were hashed by calling {@link
 103     * Arrays#hashCode(Object[])}.
 104     *
 105     * <p>This method is useful for implementing {@link
 106     * Object#hashCode()} on objects containing multiple fields. For
 107     * example, if an object that has three fields, {@code x}, {@code
 108     * y}, and {@code z}, one could write:
 109     *
 110     * <blockquote><pre>
 111     * &#064;Override public int hashCode() {
 112     *     return Objects.hash(x, y, z);
 113     * }
 114     * </pre></blockquote>
 115     *
 116     * <b>Warning: When a single object reference is supplied, the returned
 117     * value does not equal the hash code of that object reference.</b> This
 118     * value can be computed by calling {@link #hashCode(Object)}.
 119     *
 120     * @param values the values to be hashed
 121     * @return a hash value of the sequence of input values
 122     * @see Arrays#hashCode(Object[])
 123     * @see List#hashCode
 124     */
 125     public static int hash(Object... values) {
 126         return Arrays.hashCode(values);
 127     }
 128 
 129     /**
 130      * Returns the result of calling {@code toString} for a non-{@code
 131      * null} argument and {@code "null"} for a {@code null} argument.
 132      *
 133      * @param o an object
 134      * @return the result of calling {@code toString} for a non-{@code
 135      * null} argument and {@code "null"} for a {@code null} argument
 136      * @see Object#toString
 137      * @see String#valueOf(Object)
 138      */
 139     public static String toString(Object o) {
 140         return String.valueOf(o);
 141     }
 142 
 143     /**
 144      * Returns the result of calling {@code toString} on the first
 145      * argument if the first argument is not {@code null} and returns
 146      * the second argument otherwise.
 147      *
 148      * @param o an object
 149      * @param nullDefault string to return if the first argument is
 150      *        {@code null}
 151      * @return the result of calling {@code toString} on the first
 152      * argument if it is not {@code null} and the second argument
 153      * otherwise.
 154      * @see Objects#toString(Object)
 155      */
 156     public static String toString(Object o, String nullDefault) {
 157         return (o != null) ? o.toString() : nullDefault;
 158     }
 159 
 160     /**
 161      * Returns 0 if the arguments are identical and {@code
 162      * c.compare(a, b)} otherwise.
 163      * Consequently, if both arguments are {@code null} 0
 164      * is returned.
 165      *
 166      * <p>Note that if one of the arguments is {@code null}, a {@code
 167      * NullPointerException} may or may not be thrown depending on
 168      * what ordering policy, if any, the {@link Comparator Comparator}
 169      * chooses to have for {@code null} values.
 170      *
 171      * @param <T> the type of the objects being compared
 172      * @param a an object
 173      * @param b an object to be compared with {@code a}
 174      * @param c the {@code Comparator} to compare the first two arguments
 175      * @return 0 if the arguments are identical and {@code
 176      * c.compare(a, b)} otherwise.
 177      * @see Comparable
 178      * @see Comparator
 179      */
 180     public static <T> int compare(T a, T b, Comparator<? super T> c) {
 181         return (a == b) ? 0 :  c.compare(a, b);
 182     }
 183 
 184     /**
 185      * Checks that the specified object reference is not {@code null}. This
 186      * method is designed primarily for doing parameter validation in methods
 187      * and constructors, as demonstrated below:
 188      * <blockquote><pre>
 189      * public Foo(Bar bar) {
 190      *     this.bar = Objects.requireNonNull(bar);
 191      * }
 192      * </pre></blockquote>
 193      *
 194      * @param obj the object reference to check for nullity
 195      * @param <T> the type of the reference
 196      * @return {@code obj} if not {@code null}
 197      * @throws NullPointerException if {@code obj} is {@code null}
 198      */
 199     public static <T> T requireNonNull(T obj) {
 200         if (obj == null)
 201             throw new NullPointerException();
 202         return obj;
 203     }
 204 
 205     /**
 206      * Checks that the specified object reference is not {@code null} and
 207      * throws a customized {@link NullPointerException} if it is. This method
 208      * is designed primarily for doing parameter validation in methods and
 209      * constructors with multiple parameters, as demonstrated below:
 210      * <blockquote><pre>
 211      * public Foo(Bar bar, Baz baz) {
 212      *     this.bar = Objects.requireNonNull(bar, "bar must not be null");
 213      *     this.baz = Objects.requireNonNull(baz, "baz must not be null");
 214      * }
 215      * </pre></blockquote>
 216      *
 217      * @param obj     the object reference to check for nullity
 218      * @param message detail message to be used in the event that a {@code
 219      *                NullPointerException} is thrown
 220      * @param <T> the type of the reference
 221      * @return {@code obj} if not {@code null}
 222      * @throws NullPointerException if {@code obj} is {@code null}
 223      */
 224     public static <T> T requireNonNull(T obj, String message) {
 225         if (obj == null)
 226             throw new NullPointerException(message);
 227         return obj;
 228     }




































 229 }
--- EOF ---