1 /* 2 * Copyright 2009 Sun Microsystems, Inc. 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. Sun designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 22 * CA 95054 USA or visit www.sun.com if you need additional information or 23 * have any 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 * @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.nonNull(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 nonNull(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.nonNull(bar, "bar must not be null"); 213 * this.baz = Objects.nonNull(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 nonNull(T obj, String message) { 225 if (obj == null) 226 throw new NullPointerException(message); 227 return obj; 228 } 229 }