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 {
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 * Checks that the specified object reference is not {@code null} and
234 * throws a customized {@link NullPointerException} if it is.
235 *
236 * <p>Compared to the sibling method {@link requireNonNull(Object,
237 * String}, this methods allows creation of the message to be
238 * deferred until after the null check is made. Note that if the
239 * supplier is provided via a lambda expression, there can be an
240 * overhead involved in creating the supplier. Therefore, while
241 * this method may confer a net performance advantage in the
242 * non-null case, it is most likely to do so if creating the
243 * message string is expensive.
244 *
245 * @param obj the object reference to check for nullity
246 * @param messageSupplier supplier of the detail message to be
247 * used in the event that a {@code NullPointerException} is thrown
248 * @param <T> the type of the reference
249 * @return {@code obj} if not {@code null}
250 * @throws NullPointerException if {@code obj} is {@code null}
251 * @since 1.8
252 */
253 public static <T> T requireNonNull(T obj, Supplier<String> messageSupplier) {
254 if (obj == null)
255 throw new NullPointerException(messageSupplier.get());
256 return obj;
257 }
258 }