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     * &#064;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