151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski/* 2607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * Copyright (c) 2009, 2013, Oracle and/or its affiliates. All rights reserved. 351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This code is free software; you can redistribute it and/or modify it 651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * under the terms of the GNU General Public License version 2 only, as 751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * published by the Free Software Foundation. Oracle designates this 851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * particular file as subject to the "Classpath" exception as provided 951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * by Oracle in the LICENSE file that accompanied this code. 1051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 1151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This code is distributed in the hope that it will be useful, but WITHOUT 1251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * version 2 for more details (a copy is included in the LICENSE file that 1551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * accompanied this code). 1651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 1751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * You should have received a copy of the GNU General Public License version 1851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 2 along with this work; if not, write to the Free Software Foundation, 1951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 2151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * or visit www.oracle.com if you need additional information or have any 2351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * questions. 2451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 2551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 2651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskipackage java.util; 2751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 28607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fullerimport java.util.function.Supplier; 29607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller 3051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski/** 3151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This class consists of {@code static} utility methods for operating 3251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * on objects. These utilities include {@code null}-safe or {@code 3351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * null}-tolerant methods for computing the hash code of an object, 3451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * returning a string for an object, and comparing two objects. 3551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 3651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @since 1.7 3751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 3851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskipublic final class Objects { 3951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski private Objects() { 4051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski throw new AssertionError("No java.util.Objects instances for you!"); 4151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 4251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 4351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 4451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns {@code true} if the arguments are equal to each other 4551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * and {@code false} otherwise. 4651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Consequently, if both arguments are {@code null}, {@code true} 4751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is returned and if exactly one argument is {@code null}, {@code 4851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * false} is returned. Otherwise, equality is determined by using 4951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the {@link Object#equals equals} method of the first 5051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * argument. 5151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 5251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param a an object 5351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param b an object to be compared with {@code a} for equality 5451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return {@code true} if the arguments are equal to each other 5551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * and {@code false} otherwise 5651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see Object#equals(Object) 5751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 5851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public static boolean equals(Object a, Object b) { 5951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return (a == b) || (a != null && a.equals(b)); 6051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 6151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 6251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 6351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns {@code true} if the arguments are deeply equal to each other 6451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * and {@code false} otherwise. 6551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 6651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Two {@code null} values are deeply equal. If both arguments are 6751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * arrays, the algorithm in {@link Arrays#deepEquals(Object[], 6851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Object[]) Arrays.deepEquals} is used to determine equality. 6951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Otherwise, equality is determined by using the {@link 7051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Object#equals equals} method of the first argument. 7151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 7251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param a an object 7351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param b an object to be compared with {@code a} for deep equality 7451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return {@code true} if the arguments are deeply equal to each other 7551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * and {@code false} otherwise 7651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see Arrays#deepEquals(Object[], Object[]) 7751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see Objects#equals(Object, Object) 7851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 7951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public static boolean deepEquals(Object a, Object b) { 8051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski if (a == b) 8151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return true; 8251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski else if (a == null || b == null) 8351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return false; 8451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski else 8551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return Arrays.deepEquals0(a, b); 8651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 8751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 8851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 8951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns the hash code of a non-{@code null} argument and 0 for 9051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * a {@code null} argument. 9151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 9251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param o an object 9351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the hash code of a non-{@code null} argument and 0 for 9451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * a {@code null} argument 9551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see Object#hashCode 9651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 9751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public static int hashCode(Object o) { 9851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return o != null ? o.hashCode() : 0; 9951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 10051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 10151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 10251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Generates a hash code for a sequence of input values. The hash 10351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * code is generated as if all the input values were placed into an 10451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * array, and that array were hashed by calling {@link 10551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Arrays#hashCode(Object[])}. 10651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 10751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>This method is useful for implementing {@link 10851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Object#hashCode()} on objects containing multiple fields. For 10951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * example, if an object that has three fields, {@code x}, {@code 11051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * y}, and {@code z}, one could write: 11151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 11251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <blockquote><pre> 11351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @Override public int hashCode() { 11451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * return Objects.hash(x, y, z); 11551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * } 11651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * </pre></blockquote> 11751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 11851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <b>Warning: When a single object reference is supplied, the returned 11951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * value does not equal the hash code of that object reference.</b> This 12051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * value can be computed by calling {@link #hashCode(Object)}. 12151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 12251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param values the values to be hashed 12351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return a hash value of the sequence of input values 12451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see Arrays#hashCode(Object[]) 12551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see List#hashCode 12651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 12751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public static int hash(Object... values) { 12851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return Arrays.hashCode(values); 12951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 13051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 13151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 13251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns the result of calling {@code toString} for a non-{@code 13351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * null} argument and {@code "null"} for a {@code null} argument. 13451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 13551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param o an object 13651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the result of calling {@code toString} for a non-{@code 13751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * null} argument and {@code "null"} for a {@code null} argument 13851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see Object#toString 13951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see String#valueOf(Object) 14051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 14151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public static String toString(Object o) { 14251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return String.valueOf(o); 14351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 14451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 14551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 14651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns the result of calling {@code toString} on the first 14751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * argument if the first argument is not {@code null} and returns 14851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the second argument otherwise. 14951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 15051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param o an object 15151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param nullDefault string to return if the first argument is 15251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@code null} 15351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the result of calling {@code toString} on the first 15451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * argument if it is not {@code null} and the second argument 15551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * otherwise. 15651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see Objects#toString(Object) 15751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 15851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public static String toString(Object o, String nullDefault) { 15951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return (o != null) ? o.toString() : nullDefault; 16051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 16151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 16251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 16351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns 0 if the arguments are identical and {@code 16451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * c.compare(a, b)} otherwise. 16551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Consequently, if both arguments are {@code null} 0 16651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is returned. 16751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 16851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>Note that if one of the arguments is {@code null}, a {@code 16951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * NullPointerException} may or may not be thrown depending on 17051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * what ordering policy, if any, the {@link Comparator Comparator} 17151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * chooses to have for {@code null} values. 17251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 17351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param <T> the type of the objects being compared 17451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param a an object 17551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param b an object to be compared with {@code a} 17651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param c the {@code Comparator} to compare the first two arguments 17751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return 0 if the arguments are identical and {@code 17851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * c.compare(a, b)} otherwise. 17951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see Comparable 18051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see Comparator 18151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 18251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public static <T> int compare(T a, T b, Comparator<? super T> c) { 18351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return (a == b) ? 0 : c.compare(a, b); 18451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 18551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 18651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 18751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Checks that the specified object reference is not {@code null}. This 18851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * method is designed primarily for doing parameter validation in methods 18951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * and constructors, as demonstrated below: 19051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <blockquote><pre> 19151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * public Foo(Bar bar) { 19251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * this.bar = Objects.requireNonNull(bar); 19351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * } 19451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * </pre></blockquote> 19551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 19651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param obj the object reference to check for nullity 19751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param <T> the type of the reference 19851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return {@code obj} if not {@code null} 19951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws NullPointerException if {@code obj} is {@code null} 20051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 20151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public static <T> T requireNonNull(T obj) { 20251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski if (obj == null) 20351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski throw new NullPointerException(); 20451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return obj; 20551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 20651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 20751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 20851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Checks that the specified object reference is not {@code null} and 20951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * throws a customized {@link NullPointerException} if it is. This method 21051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is designed primarily for doing parameter validation in methods and 21151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * constructors with multiple parameters, as demonstrated below: 21251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <blockquote><pre> 21351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * public Foo(Bar bar, Baz baz) { 21451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * this.bar = Objects.requireNonNull(bar, "bar must not be null"); 21551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * this.baz = Objects.requireNonNull(baz, "baz must not be null"); 21651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * } 21751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * </pre></blockquote> 21851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 21951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param obj the object reference to check for nullity 22051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param message detail message to be used in the event that a {@code 22151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * NullPointerException} is thrown 22251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param <T> the type of the reference 22351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return {@code obj} if not {@code null} 22451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws NullPointerException if {@code obj} is {@code null} 22551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 22651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public static <T> T requireNonNull(T obj, String message) { 22751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski if (obj == null) 22851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski throw new NullPointerException(message); 22951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return obj; 23051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 231607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller 232607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller /** 233607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * Returns {@code true} if the provided reference is {@code null} otherwise 234607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * returns {@code false}. 235607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * 236607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * @apiNote This method exists to be used as a 237607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * {@link java.util.function.Predicate}, {@code filter(Objects::isNull)} 238607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * 239607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * @param obj a reference to be checked against {@code null} 240607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * @return {@code true} if the provided reference is {@code null} otherwise 241607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * {@code false} 242607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * 243607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * @see java.util.function.Predicate 244607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * @since 1.8 245607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller */ 246607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller public static boolean isNull(Object obj) { 247607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller return obj == null; 248607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller } 249607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller 250607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller /** 251607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * Returns {@code true} if the provided reference is non-{@code null} 252607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * otherwise returns {@code false}. 253607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * 254607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * @apiNote This method exists to be used as a 255607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * {@link java.util.function.Predicate}, {@code filter(Objects::nonNull)} 256607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * 257607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * @param obj a reference to be checked against {@code null} 258607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * @return {@code true} if the provided reference is non-{@code null} 259607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * otherwise {@code false} 260607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * 261607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * @see java.util.function.Predicate 262607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * @since 1.8 263607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller */ 264607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller public static boolean nonNull(Object obj) { 265607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller return obj != null; 266607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller } 267607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller 268607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller /** 269607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * Checks that the specified object reference is not {@code null} and 270607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * throws a customized {@link NullPointerException} if it is. 271607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * 272607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * <p>Unlike the method {@link #requireNonNull(Object, String)}, 273607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * this method allows creation of the message to be deferred until 274607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * after the null check is made. While this may confer a 275607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * performance advantage in the non-null case, when deciding to 276607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * call this method care should be taken that the costs of 277607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * creating the message supplier are less than the cost of just 278607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * creating the string message directly. 279607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * 280607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * @param obj the object reference to check for nullity 281607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * @param messageSupplier supplier of the detail message to be 282607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * used in the event that a {@code NullPointerException} is thrown 283607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * @param <T> the type of the reference 284607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * @return {@code obj} if not {@code null} 285607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * @throws NullPointerException if {@code obj} is {@code null} 286607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * @since 1.8 287607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller */ 288607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller public static <T> T requireNonNull(T obj, Supplier<String> messageSupplier) { 289607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller if (obj == null) 290607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller throw new NullPointerException(messageSupplier.get()); 291607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller return obj; 292607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller } 29351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski} 294