1 /* 2 * Copyright (c) 2009, 2013, 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 import java.util.function.Supplier; 29 30 /** 31 * This class consists of {@code static} utility methods for operating 32 * on objects. These utilities include {@code null}-safe or {@code 33 * null}-tolerant methods for computing the hash code of an object, 34 * returning a string for an object, and comparing two objects. 35 * 36 * @since 1.7 37 */ 38 public final class Objects { Objects()39 private Objects() { 40 throw new AssertionError("No java.util.Objects instances for you!"); 41 } 42 43 /** 44 * Returns {@code true} if the arguments are equal to each other 45 * and {@code false} otherwise. 46 * Consequently, if both arguments are {@code null}, {@code true} 47 * is returned and if exactly one argument is {@code null}, {@code 48 * false} is returned. Otherwise, equality is determined by using 49 * the {@link Object#equals equals} method of the first 50 * argument. 51 * 52 * @param a an object 53 * @param b an object to be compared with {@code a} for equality 54 * @return {@code true} if the arguments are equal to each other 55 * and {@code false} otherwise 56 * @see Object#equals(Object) 57 */ equals(Object a, Object b)58 public static boolean equals(Object a, Object b) { 59 return (a == b) || (a != null && a.equals(b)); 60 } 61 62 /** 63 * Returns {@code true} if the arguments are deeply equal to each other 64 * and {@code false} otherwise. 65 * 66 * Two {@code null} values are deeply equal. If both arguments are 67 * arrays, the algorithm in {@link Arrays#deepEquals(Object[], 68 * Object[]) Arrays.deepEquals} is used to determine equality. 69 * Otherwise, equality is determined by using the {@link 70 * Object#equals equals} method of the first argument. 71 * 72 * @param a an object 73 * @param b an object to be compared with {@code a} for deep equality 74 * @return {@code true} if the arguments are deeply equal to each other 75 * and {@code false} otherwise 76 * @see Arrays#deepEquals(Object[], Object[]) 77 * @see Objects#equals(Object, Object) 78 */ deepEquals(Object a, Object b)79 public static boolean deepEquals(Object a, Object b) { 80 if (a == b) 81 return true; 82 else if (a == null || b == null) 83 return false; 84 else 85 return Arrays.deepEquals0(a, b); 86 } 87 88 /** 89 * Returns the hash code of a non-{@code null} argument and 0 for 90 * a {@code null} argument. 91 * 92 * @param o an object 93 * @return the hash code of a non-{@code null} argument and 0 for 94 * a {@code null} argument 95 * @see Object#hashCode 96 */ hashCode(Object o)97 public static int hashCode(Object o) { 98 return o != null ? o.hashCode() : 0; 99 } 100 101 /** 102 * Generates a hash code for a sequence of input values. The hash 103 * code is generated as if all the input values were placed into an 104 * array, and that array were hashed by calling {@link 105 * Arrays#hashCode(Object[])}. 106 * 107 * <p>This method is useful for implementing {@link 108 * Object#hashCode()} on objects containing multiple fields. For 109 * example, if an object that has three fields, {@code x}, {@code 110 * y}, and {@code z}, one could write: 111 * 112 * <blockquote><pre> 113 * @Override public int hashCode() { 114 * return Objects.hash(x, y, z); 115 * } 116 * </pre></blockquote> 117 * 118 * <b>Warning: When a single object reference is supplied, the returned 119 * value does not equal the hash code of that object reference.</b> This 120 * value can be computed by calling {@link #hashCode(Object)}. 121 * 122 * @param values the values to be hashed 123 * @return a hash value of the sequence of input values 124 * @see Arrays#hashCode(Object[]) 125 * @see List#hashCode 126 */ hash(Object... values)127 public static int hash(Object... values) { 128 return Arrays.hashCode(values); 129 } 130 131 /** 132 * Returns the result of calling {@code toString} for a non-{@code 133 * null} argument and {@code "null"} for a {@code null} argument. 134 * 135 * @param o an object 136 * @return the result of calling {@code toString} for a non-{@code 137 * null} argument and {@code "null"} for a {@code null} argument 138 * @see Object#toString 139 * @see String#valueOf(Object) 140 */ toString(Object o)141 public static String toString(Object o) { 142 return String.valueOf(o); 143 } 144 145 /** 146 * Returns the result of calling {@code toString} on the first 147 * argument if the first argument is not {@code null} and returns 148 * the second argument otherwise. 149 * 150 * @param o an object 151 * @param nullDefault string to return if the first argument is 152 * {@code null} 153 * @return the result of calling {@code toString} on the first 154 * argument if it is not {@code null} and the second argument 155 * otherwise. 156 * @see Objects#toString(Object) 157 */ toString(Object o, String nullDefault)158 public static String toString(Object o, String nullDefault) { 159 return (o != null) ? o.toString() : nullDefault; 160 } 161 162 /** 163 * Returns 0 if the arguments are identical and {@code 164 * c.compare(a, b)} otherwise. 165 * Consequently, if both arguments are {@code null} 0 166 * is returned. 167 * 168 * <p>Note that if one of the arguments is {@code null}, a {@code 169 * NullPointerException} may or may not be thrown depending on 170 * what ordering policy, if any, the {@link Comparator Comparator} 171 * chooses to have for {@code null} values. 172 * 173 * @param <T> the type of the objects being compared 174 * @param a an object 175 * @param b an object to be compared with {@code a} 176 * @param c the {@code Comparator} to compare the first two arguments 177 * @return 0 if the arguments are identical and {@code 178 * c.compare(a, b)} otherwise. 179 * @see Comparable 180 * @see Comparator 181 */ compare(T a, T b, Comparator<? super T> c)182 public static <T> int compare(T a, T b, Comparator<? super T> c) { 183 return (a == b) ? 0 : c.compare(a, b); 184 } 185 186 /** 187 * Checks that the specified object reference is not {@code null}. This 188 * method is designed primarily for doing parameter validation in methods 189 * and constructors, as demonstrated below: 190 * <blockquote><pre> 191 * public Foo(Bar bar) { 192 * this.bar = Objects.requireNonNull(bar); 193 * } 194 * </pre></blockquote> 195 * 196 * @param obj the object reference to check for nullity 197 * @param <T> the type of the reference 198 * @return {@code obj} if not {@code null} 199 * @throws NullPointerException if {@code obj} is {@code null} 200 */ requireNonNull(T obj)201 public static <T> T requireNonNull(T obj) { 202 if (obj == null) 203 throw new NullPointerException(); 204 return obj; 205 } 206 207 /** 208 * Checks that the specified object reference is not {@code null} and 209 * throws a customized {@link NullPointerException} if it is. This method 210 * is designed primarily for doing parameter validation in methods and 211 * constructors with multiple parameters, as demonstrated below: 212 * <blockquote><pre> 213 * public Foo(Bar bar, Baz baz) { 214 * this.bar = Objects.requireNonNull(bar, "bar must not be null"); 215 * this.baz = Objects.requireNonNull(baz, "baz must not be null"); 216 * } 217 * </pre></blockquote> 218 * 219 * @param obj the object reference to check for nullity 220 * @param message detail message to be used in the event that a {@code 221 * NullPointerException} is thrown 222 * @param <T> the type of the reference 223 * @return {@code obj} if not {@code null} 224 * @throws NullPointerException if {@code obj} is {@code null} 225 */ requireNonNull(T obj, String message)226 public static <T> T requireNonNull(T obj, String message) { 227 if (obj == null) 228 throw new NullPointerException(message); 229 return obj; 230 } 231 232 /** 233 * Returns {@code true} if the provided reference is {@code null} otherwise 234 * returns {@code false}. 235 * 236 * @apiNote This method exists to be used as a 237 * {@link java.util.function.Predicate}, {@code filter(Objects::isNull)} 238 * 239 * @param obj a reference to be checked against {@code null} 240 * @return {@code true} if the provided reference is {@code null} otherwise 241 * {@code false} 242 * 243 * @see java.util.function.Predicate 244 * @since 1.8 245 */ isNull(Object obj)246 public static boolean isNull(Object obj) { 247 return obj == null; 248 } 249 250 /** 251 * Returns {@code true} if the provided reference is non-{@code null} 252 * otherwise returns {@code false}. 253 * 254 * @apiNote This method exists to be used as a 255 * {@link java.util.function.Predicate}, {@code filter(Objects::nonNull)} 256 * 257 * @param obj a reference to be checked against {@code null} 258 * @return {@code true} if the provided reference is non-{@code null} 259 * otherwise {@code false} 260 * 261 * @see java.util.function.Predicate 262 * @since 1.8 263 */ nonNull(Object obj)264 public static boolean nonNull(Object obj) { 265 return obj != null; 266 } 267 268 /** 269 * Checks that the specified object reference is not {@code null} and 270 * throws a customized {@link NullPointerException} if it is. 271 * 272 * <p>Unlike the method {@link #requireNonNull(Object, String)}, 273 * this method allows creation of the message to be deferred until 274 * after the null check is made. While this may confer a 275 * performance advantage in the non-null case, when deciding to 276 * call this method care should be taken that the costs of 277 * creating the message supplier are less than the cost of just 278 * creating the string message directly. 279 * 280 * @param obj the object reference to check for nullity 281 * @param messageSupplier supplier of the detail message to be 282 * used in the event that a {@code NullPointerException} is thrown 283 * @param <T> the type of the reference 284 * @return {@code obj} if not {@code null} 285 * @throws NullPointerException if {@code obj} is {@code null} 286 * @since 1.8 287 */ requireNonNull(T obj, Supplier<String> messageSupplier)288 public static <T> T requireNonNull(T obj, Supplier<String> messageSupplier) { 289 if (obj == null) 290 throw new NullPointerException(messageSupplier.get()); 291 return obj; 292 } 293 } 294