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 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 the hash code of a non-{@code null} argument and 0 for
  62      * a {@code null} argument.
  63      *
  64      * @param o an object
  65      * @return the hash code of a non-{@code null} argument and 0 for
  66      * a {@code null} argument
  67      * @see Object#hashCode
  68      */
  69     public static int hashCode(Object o) {
  70         return o != null ? o.hashCode() : 0;
  71     }
  72 
  73     /**
  74      * Returns the result of calling {@code toString} for a non-{@code
  75      * null} argument and {@code "null"} for a {@code null} argument.
  76      *
  77      * @param o an object
  78      * @return the result of calling {@code toString} for a non-{@code
  79      * null} argument and {@code "null"} for a {@code null} argument
  80      * @see Object#toString
  81      * @see String#valueOf(Object)
  82      */
  83     public static String toString(Object o) {
  84         return String.valueOf(o);
  85     }
  86 
  87     /**
  88      * Returns 0 if the arguments are identical and {@code
  89      * c.compare(a, b)} otherwise.
  90      * Consequently, if both arguments are {@code null} 0
  91      * is returned.
  92      *
  93      * <p>Note that if one of the arguments is {@code null}, a {@code
  94      * NullPointerException} may or may not be thrown depending on
  95      * what ordering policy, if any, the {@link Comparator Comparator}
  96      * chooses to have for {@code null} values.
  97      *
  98      * @param <T> the type of the objects being compared
  99      * @param a an object
 100      * @param b an object to be compared with {@code a}
 101      * @param c the {@code Comparator} to compare the first two arguments
 102      * @return 0 if the arguments are identical and {@code
 103      * c.compare(a, b)} otherwise.
 104      * @see Comparable
 105      * @see Comparator
 106      */
 107     public static <T> int compare(T a, T b, Comparator<? super T> c) {
 108         return (a == b) ? 0 :  c.compare(a, b);
 109     }
 110 
 111     /**
 112      * Checks that the specified object reference is not {@code null}. This
 113      * method is designed primarily for doing parameter validation in methods
 114      * and constructors, as demonstrated below:
 115      * <blockquote><pre>
 116      * public Foo(Bar bar) {
 117      *     this.bar = Objects.nonNull(bar);
 118      * }
 119      * </pre></blockquote>
 120      *
 121      * @param obj the object reference to check for nullity
 122      * @param <T> the type of the reference
 123      * @return {@code obj} if not {@code null}
 124      * @throws NullPointerException if {@code obj} is {@code null}
 125      */
 126     public static <T> T nonNull(T obj) {
 127         if (obj == null)
 128             throw new NullPointerException();
 129         return obj;
 130     }
 131 
 132     /**
 133      * Checks that the specified object reference is not {@code null} and
 134      * throws a customized {@link NullPointerException} if it is. This method
 135      * is designed primarily for doing parameter validation in methods and
 136      * constructors with multiple parameters, as demonstrated below:
 137      * <blockquote><pre>
 138      * public Foo(Bar bar, Baz baz) {
 139      *     this.bar = Objects.nonNull(bar, "bar must not be null");
 140      *     this.baz = Objects.nonNull(baz, "baz must not be null");
 141      * }
 142      * </pre></blockquote>
 143      *
 144      * @param obj     the object reference to check for nullity
 145      * @param message detail message to be used in the event that a {@code
 146      *                NullPointerException} is thrown
 147      * @param <T> the type of the reference
 148      * @return {@code obj} if not {@code null}
 149      * @throws NullPointerException if {@code obj} is {@code null}
 150      */
 151     public static <T> T nonNull(T obj, String message) {
 152         if (obj == null)
 153             throw new NullPointerException(message);
 154         return obj;
 155     }
 156 }