1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/rt/emul/compact/src/main/java/java/util/Objects.java Tue Feb 26 16:54:16 2013 +0100
1.3 @@ -0,0 +1,229 @@
1.4 +/*
1.5 + * Copyright (c) 2009, 2011, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Oracle designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Oracle in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + * or visit www.oracle.com if you need additional information or have any
1.26 + * questions.
1.27 + */
1.28 +
1.29 +package java.util;
1.30 +
1.31 +/**
1.32 + * This class consists of {@code static} utility methods for operating
1.33 + * on objects. These utilities include {@code null}-safe or {@code
1.34 + * null}-tolerant methods for computing the hash code of an object,
1.35 + * returning a string for an object, and comparing two objects.
1.36 + *
1.37 + * @since 1.7
1.38 + */
1.39 +public final class Objects {
1.40 + private Objects() {
1.41 + throw new AssertionError("No java.util.Objects instances for you!");
1.42 + }
1.43 +
1.44 + /**
1.45 + * Returns {@code true} if the arguments are equal to each other
1.46 + * and {@code false} otherwise.
1.47 + * Consequently, if both arguments are {@code null}, {@code true}
1.48 + * is returned and if exactly one argument is {@code null}, {@code
1.49 + * false} is returned. Otherwise, equality is determined by using
1.50 + * the {@link Object#equals equals} method of the first
1.51 + * argument.
1.52 + *
1.53 + * @param a an object
1.54 + * @param b an object to be compared with {@code a} for equality
1.55 + * @return {@code true} if the arguments are equal to each other
1.56 + * and {@code false} otherwise
1.57 + * @see Object#equals(Object)
1.58 + */
1.59 + public static boolean equals(Object a, Object b) {
1.60 + return (a == b) || (a != null && a.equals(b));
1.61 + }
1.62 +
1.63 + /**
1.64 + * Returns {@code true} if the arguments are deeply equal to each other
1.65 + * and {@code false} otherwise.
1.66 + *
1.67 + * Two {@code null} values are deeply equal. If both arguments are
1.68 + * arrays, the algorithm in {@link Arrays#deepEquals(Object[],
1.69 + * Object[]) Arrays.deepEquals} is used to determine equality.
1.70 + * Otherwise, equality is determined by using the {@link
1.71 + * Object#equals equals} method of the first argument.
1.72 + *
1.73 + * @param a an object
1.74 + * @param b an object to be compared with {@code a} for deep equality
1.75 + * @return {@code true} if the arguments are deeply equal to each other
1.76 + * and {@code false} otherwise
1.77 + * @see Arrays#deepEquals(Object[], Object[])
1.78 + * @see Objects#equals(Object, Object)
1.79 + */
1.80 + public static boolean deepEquals(Object a, Object b) {
1.81 + if (a == b)
1.82 + return true;
1.83 + else if (a == null || b == null)
1.84 + return false;
1.85 + else
1.86 + return Arrays.deepEquals0(a, b);
1.87 + }
1.88 +
1.89 + /**
1.90 + * Returns the hash code of a non-{@code null} argument and 0 for
1.91 + * a {@code null} argument.
1.92 + *
1.93 + * @param o an object
1.94 + * @return the hash code of a non-{@code null} argument and 0 for
1.95 + * a {@code null} argument
1.96 + * @see Object#hashCode
1.97 + */
1.98 + public static int hashCode(Object o) {
1.99 + return o != null ? o.hashCode() : 0;
1.100 + }
1.101 +
1.102 + /**
1.103 + * Generates a hash code for a sequence of input values. The hash
1.104 + * code is generated as if all the input values were placed into an
1.105 + * array, and that array were hashed by calling {@link
1.106 + * Arrays#hashCode(Object[])}.
1.107 + *
1.108 + * <p>This method is useful for implementing {@link
1.109 + * Object#hashCode()} on objects containing multiple fields. For
1.110 + * example, if an object that has three fields, {@code x}, {@code
1.111 + * y}, and {@code z}, one could write:
1.112 + *
1.113 + * <blockquote><pre>
1.114 + * @Override public int hashCode() {
1.115 + * return Objects.hash(x, y, z);
1.116 + * }
1.117 + * </pre></blockquote>
1.118 + *
1.119 + * <b>Warning: When a single object reference is supplied, the returned
1.120 + * value does not equal the hash code of that object reference.</b> This
1.121 + * value can be computed by calling {@link #hashCode(Object)}.
1.122 + *
1.123 + * @param values the values to be hashed
1.124 + * @return a hash value of the sequence of input values
1.125 + * @see Arrays#hashCode(Object[])
1.126 + * @see List#hashCode
1.127 + */
1.128 + public static int hash(Object... values) {
1.129 + return Arrays.hashCode(values);
1.130 + }
1.131 +
1.132 + /**
1.133 + * Returns the result of calling {@code toString} for a non-{@code
1.134 + * null} argument and {@code "null"} for a {@code null} argument.
1.135 + *
1.136 + * @param o an object
1.137 + * @return the result of calling {@code toString} for a non-{@code
1.138 + * null} argument and {@code "null"} for a {@code null} argument
1.139 + * @see Object#toString
1.140 + * @see String#valueOf(Object)
1.141 + */
1.142 + public static String toString(Object o) {
1.143 + return String.valueOf(o);
1.144 + }
1.145 +
1.146 + /**
1.147 + * Returns the result of calling {@code toString} on the first
1.148 + * argument if the first argument is not {@code null} and returns
1.149 + * the second argument otherwise.
1.150 + *
1.151 + * @param o an object
1.152 + * @param nullDefault string to return if the first argument is
1.153 + * {@code null}
1.154 + * @return the result of calling {@code toString} on the first
1.155 + * argument if it is not {@code null} and the second argument
1.156 + * otherwise.
1.157 + * @see Objects#toString(Object)
1.158 + */
1.159 + public static String toString(Object o, String nullDefault) {
1.160 + return (o != null) ? o.toString() : nullDefault;
1.161 + }
1.162 +
1.163 + /**
1.164 + * Returns 0 if the arguments are identical and {@code
1.165 + * c.compare(a, b)} otherwise.
1.166 + * Consequently, if both arguments are {@code null} 0
1.167 + * is returned.
1.168 + *
1.169 + * <p>Note that if one of the arguments is {@code null}, a {@code
1.170 + * NullPointerException} may or may not be thrown depending on
1.171 + * what ordering policy, if any, the {@link Comparator Comparator}
1.172 + * chooses to have for {@code null} values.
1.173 + *
1.174 + * @param <T> the type of the objects being compared
1.175 + * @param a an object
1.176 + * @param b an object to be compared with {@code a}
1.177 + * @param c the {@code Comparator} to compare the first two arguments
1.178 + * @return 0 if the arguments are identical and {@code
1.179 + * c.compare(a, b)} otherwise.
1.180 + * @see Comparable
1.181 + * @see Comparator
1.182 + */
1.183 + public static <T> int compare(T a, T b, Comparator<? super T> c) {
1.184 + return (a == b) ? 0 : c.compare(a, b);
1.185 + }
1.186 +
1.187 + /**
1.188 + * Checks that the specified object reference is not {@code null}. This
1.189 + * method is designed primarily for doing parameter validation in methods
1.190 + * and constructors, as demonstrated below:
1.191 + * <blockquote><pre>
1.192 + * public Foo(Bar bar) {
1.193 + * this.bar = Objects.requireNonNull(bar);
1.194 + * }
1.195 + * </pre></blockquote>
1.196 + *
1.197 + * @param obj the object reference to check for nullity
1.198 + * @param <T> the type of the reference
1.199 + * @return {@code obj} if not {@code null}
1.200 + * @throws NullPointerException if {@code obj} is {@code null}
1.201 + */
1.202 + public static <T> T requireNonNull(T obj) {
1.203 + if (obj == null)
1.204 + throw new NullPointerException();
1.205 + return obj;
1.206 + }
1.207 +
1.208 + /**
1.209 + * Checks that the specified object reference is not {@code null} and
1.210 + * throws a customized {@link NullPointerException} if it is. This method
1.211 + * is designed primarily for doing parameter validation in methods and
1.212 + * constructors with multiple parameters, as demonstrated below:
1.213 + * <blockquote><pre>
1.214 + * public Foo(Bar bar, Baz baz) {
1.215 + * this.bar = Objects.requireNonNull(bar, "bar must not be null");
1.216 + * this.baz = Objects.requireNonNull(baz, "baz must not be null");
1.217 + * }
1.218 + * </pre></blockquote>
1.219 + *
1.220 + * @param obj the object reference to check for nullity
1.221 + * @param message detail message to be used in the event that a {@code
1.222 + * NullPointerException} is thrown
1.223 + * @param <T> the type of the reference
1.224 + * @return {@code obj} if not {@code null}
1.225 + * @throws NullPointerException if {@code obj} is {@code null}
1.226 + */
1.227 + public static <T> T requireNonNull(T obj, String message) {
1.228 + if (obj == null)
1.229 + throw new NullPointerException(message);
1.230 + return obj;
1.231 + }
1.232 +}