Home » openjdk-7 » java » util » [javadoc | source]

    1   /*
    2    * Copyright (c) 2009, 2011, 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   /**
   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 final 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 {@code true} if the arguments are deeply equal to each other
   62       * and {@code false} otherwise.
   63       *
   64       * Two {@code null} values are deeply equal.  If both arguments are
   65       * arrays, the algorithm in {@link Arrays#deepEquals(Object[],
   66       * Object[]) Arrays.deepEquals} is used to determine equality.
   67       * Otherwise, equality is determined by using the {@link
   68       * Object#equals equals} method of the first argument.
   69       *
   70       * @param a an object
   71       * @param b an object to be compared with {@code a} for deep equality
   72       * @return {@code true} if the arguments are deeply equal to each other
   73       * and {@code false} otherwise
   74       * @see Arrays#deepEquals(Object[], Object[])
   75       * @see Objects#equals(Object, Object)
   76       */
   77       public static boolean deepEquals(Object a, Object b) {
   78           if (a == b)
   79               return true;
   80           else if (a == null || b == null)
   81               return false;
   82           else
   83               return Arrays.deepEquals0(a, b);
   84       }
   85   
   86       /**
   87        * Returns the hash code of a non-{@code null} argument and 0 for
   88        * a {@code null} argument.
   89        *
   90        * @param o an object
   91        * @return the hash code of a non-{@code null} argument and 0 for
   92        * a {@code null} argument
   93        * @see Object#hashCode
   94        */
   95       public static int hashCode(Object o) {
   96           return o != null ? o.hashCode() : 0;
   97       }
   98   
   99      /**
  100       * Generates a hash code for a sequence of input values. The hash
  101       * code is generated as if all the input values were placed into an
  102       * array, and that array were hashed by calling {@link
  103       * Arrays#hashCode(Object[])}.
  104       *
  105       * <p>This method is useful for implementing {@link
  106       * Object#hashCode()} on objects containing multiple fields. For
  107       * example, if an object that has three fields, {@code x}, {@code
  108       * y}, and {@code z}, one could write:
  109       *
  110       * <blockquote><pre>
  111       * &#064;Override public int hashCode() {
  112       *     return Objects.hash(x, y, z);
  113       * }
  114       * </pre></blockquote>
  115       *
  116       * <b>Warning: When a single object reference is supplied, the returned
  117       * value does not equal the hash code of that object reference.</b> This
  118       * value can be computed by calling {@link #hashCode(Object)}.
  119       *
  120       * @param values the values to be hashed
  121       * @return a hash value of the sequence of input values
  122       * @see Arrays#hashCode(Object[])
  123       * @see List#hashCode
  124       */
  125       public static int hash(Object... values) {
  126           return Arrays.hashCode(values);
  127       }
  128   
  129       /**
  130        * Returns the result of calling {@code toString} for a non-{@code
  131        * null} argument and {@code "null"} for a {@code null} argument.
  132        *
  133        * @param o an object
  134        * @return the result of calling {@code toString} for a non-{@code
  135        * null} argument and {@code "null"} for a {@code null} argument
  136        * @see Object#toString
  137        * @see String#valueOf(Object)
  138        */
  139       public static String toString(Object o) {
  140           return String.valueOf(o);
  141       }
  142   
  143       /**
  144        * Returns the result of calling {@code toString} on the first
  145        * argument if the first argument is not {@code null} and returns
  146        * the second argument otherwise.
  147        *
  148        * @param o an object
  149        * @param nullDefault string to return if the first argument is
  150        *        {@code null}
  151        * @return the result of calling {@code toString} on the first
  152        * argument if it is not {@code null} and the second argument
  153        * otherwise.
  154        * @see Objects#toString(Object)
  155        */
  156       public static String toString(Object o, String nullDefault) {
  157           return (o != null) ? o.toString() : nullDefault;
  158       }
  159   
  160       /**
  161        * Returns 0 if the arguments are identical and {@code
  162        * c.compare(a, b)} otherwise.
  163        * Consequently, if both arguments are {@code null} 0
  164        * is returned.
  165        *
  166        * <p>Note that if one of the arguments is {@code null}, a {@code
  167        * NullPointerException} may or may not be thrown depending on
  168        * what ordering policy, if any, the {@link Comparator Comparator}
  169        * chooses to have for {@code null} values.
  170        *
  171        * @param <T> the type of the objects being compared
  172        * @param a an object
  173        * @param b an object to be compared with {@code a}
  174        * @param c the {@code Comparator} to compare the first two arguments
  175        * @return 0 if the arguments are identical and {@code
  176        * c.compare(a, b)} otherwise.
  177        * @see Comparable
  178        * @see Comparator
  179        */
  180       public static <T> int compare(T a, T b, Comparator<? super T> c) {
  181           return (a == b) ? 0 :  c.compare(a, b);
  182       }
  183   
  184       /**
  185        * Checks that the specified object reference is not {@code null}. This
  186        * method is designed primarily for doing parameter validation in methods
  187        * and constructors, as demonstrated below:
  188        * <blockquote><pre>
  189        * public Foo(Bar bar) {
  190        *     this.bar = Objects.requireNonNull(bar);
  191        * }
  192        * </pre></blockquote>
  193        *
  194        * @param obj the object reference to check for nullity
  195        * @param <T> the type of the reference
  196        * @return {@code obj} if not {@code null}
  197        * @throws NullPointerException if {@code obj} is {@code null}
  198        */
  199       public static <T> T requireNonNull(T obj) {
  200           if (obj == null)
  201               throw new NullPointerException();
  202           return obj;
  203       }
  204   
  205       /**
  206        * Checks that the specified object reference is not {@code null} and
  207        * throws a customized {@link NullPointerException} if it is. This method
  208        * is designed primarily for doing parameter validation in methods and
  209        * constructors with multiple parameters, as demonstrated below:
  210        * <blockquote><pre>
  211        * public Foo(Bar bar, Baz baz) {
  212        *     this.bar = Objects.requireNonNull(bar, "bar must not be null");
  213        *     this.baz = Objects.requireNonNull(baz, "baz must not be null");
  214        * }
  215        * </pre></blockquote>
  216        *
  217        * @param obj     the object reference to check for nullity
  218        * @param message detail message to be used in the event that a {@code
  219        *                NullPointerException} is thrown
  220        * @param <T> the type of the reference
  221        * @return {@code obj} if not {@code null}
  222        * @throws NullPointerException if {@code obj} is {@code null}
  223        */
  224       public static <T> T requireNonNull(T obj, String message) {
  225           if (obj == null)
  226               throw new NullPointerException(message);
  227           return obj;
  228       }
  229   }

Home » openjdk-7 » java » util » [javadoc | source]