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
26package java.util;
27
28import 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 */
38public 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    * &#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    */
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     * 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     */
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     */
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     */
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