1 /* 2 * Copyright (c) 2009, 2022, 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 import jdk.internal.util.Preconditions; 29 import jdk.internal.vm.annotation.ForceInline; 30 import jdk.internal.misc.Unsafe; 31 32 import java.util.function.Supplier; 33 34 /** 35 * This class consists of {@code static} utility methods for operating 36 * on objects, or checking certain conditions before operation. These utilities 37 * include {@code null}-safe or {@code null}-tolerant methods for computing the 38 * hash code of an object, returning a string for an object, comparing two 39 * objects, and checking if indexes or sub-range values are out of bounds. 40 * 41 * @since 1.7 42 */ 43 public final class Objects { 44 private Objects() { 45 throw new AssertionError("No java.util.Objects instances for you!"); 46 } 47 48 /** 49 * Returns {@code true} if the arguments are equal to each other 50 * and {@code false} otherwise. 51 * Consequently, if both arguments are {@code null}, {@code true} 52 * is returned. Otherwise, if the first argument is not {@code 53 * null}, equality is determined by calling the {@link 54 * Object#equals equals} method of the first argument with the 55 * second argument of this method. Otherwise, {@code false} is 56 * returned. 57 * 58 * @param a an object 59 * @param b an object to be compared with {@code a} for equality 60 * @return {@code true} if the arguments are equal to each other 61 * and {@code false} otherwise 62 * @see Object#equals(Object) 63 */ 64 public static boolean equals(Object a, Object b) { 65 return (a == b) || (a != null && a.equals(b)); 66 } 67 68 /** 69 * Returns {@code true} if the arguments are deeply equal to each other 70 * and {@code false} otherwise. 71 * 72 * Two {@code null} values are deeply equal. If both arguments are 73 * arrays, the algorithm in {@link Arrays#deepEquals(Object[], 74 * Object[]) Arrays.deepEquals} is used to determine equality. 75 * Otherwise, equality is determined by using the {@link 76 * Object#equals equals} method of the first argument. 77 * 78 * @param a an object 79 * @param b an object to be compared with {@code a} for deep equality 80 * @return {@code true} if the arguments are deeply equal to each other 81 * and {@code false} otherwise 82 * @see Arrays#deepEquals(Object[], Object[]) 83 * @see Objects#equals(Object, Object) 84 */ 85 public static boolean deepEquals(Object a, Object b) { 86 if (a == b) 87 return true; 88 else if (a == null || b == null) 89 return false; 90 else 91 return Arrays.deepEquals0(a, b); 92 } 93 94 /** 95 * Returns the hash code of a non-{@code null} argument and 0 for 96 * a {@code null} argument. 97 * 98 * @param o an object 99 * @return the hash code of a non-{@code null} argument and 0 for 100 * a {@code null} argument 101 * @see Object#hashCode 102 */ 103 public static int hashCode(Object o) { 104 return o != null ? o.hashCode() : 0; 105 } 106 107 /** 108 * Generates a hash code for a sequence of input values. The hash 109 * code is generated as if all the input values were placed into an 110 * array, and that array were hashed by calling {@link 111 * Arrays#hashCode(Object[])}. 112 * 113 * <p>This method is useful for implementing {@link 114 * Object#hashCode()} on objects containing multiple fields. For 115 * example, if an object that has three fields, {@code x}, {@code 116 * y}, and {@code z}, one could write: 117 * 118 * <blockquote><pre> 119 * @Override public int hashCode() { 120 * return Objects.hash(x, y, z); 121 * } 122 * </pre></blockquote> 123 * 124 * <b>Warning: When a single object reference is supplied, the returned 125 * value does not equal the hash code of that object reference.</b> This 126 * value can be computed by calling {@link #hashCode(Object)}. 127 * 128 * @param values the values to be hashed 129 * @return a hash value of the sequence of input values 130 * @see Arrays#hashCode(Object[]) 131 * @see List#hashCode 132 */ 133 public static int hash(Object... values) { 134 return Arrays.hashCode(values); 135 } 136 137 /** 138 * Returns the result of calling {@code toString} for a non-{@code 139 * null} argument and {@code "null"} for a {@code null} argument. 140 * 141 * @param o an object 142 * @return the result of calling {@code toString} for a non-{@code 143 * null} argument and {@code "null"} for a {@code null} argument 144 * @see Object#toString 145 * @see String#valueOf(Object) 146 */ 147 public static String toString(Object o) { 148 return String.valueOf(o); 149 } 150 151 /** 152 * Returns the result of calling {@code toString} on the first 153 * argument if the first argument is not {@code null} and returns 154 * the second argument otherwise. 155 * 156 * @param o an object 157 * @param nullDefault string to return if the first argument is 158 * {@code null} 159 * @return the result of calling {@code toString} on the first 160 * argument if it is not {@code null} and the second argument 161 * otherwise. 162 * @see Objects#toString(Object) 163 */ 164 public static String toString(Object o, String nullDefault) { 165 return (o != null) ? o.toString() : nullDefault; 166 } 167 168 /** 169 * {@return a string equivalent to the string returned by {@code 170 * Object.toString} if that method and {@code hashCode} are not 171 * overridden} 172 * 173 * @implNote 174 * This method constructs a string for an object without calling 175 * any overridable methods of the object. 176 * 177 * @implSpec 178 * The method returns a string equivalent to:<br> 179 * {@code o.getClass().getName() + "@" + Integer.toHexString(System.identityHashCode(o))} 180 * 181 * @param o an object 182 * @throws NullPointerException if the argument is null 183 * @see Object#toString 184 * @see System#identityHashCode(Object) 185 * @since 19 186 */ 187 public static String toIdentityString(Object o) { 188 requireNonNull(o); 189 return o.getClass().getName() + "@" + Integer.toHexString(System.identityHashCode(o)); 190 } 191 192 /** 193 * Checks that the specified object reference is an identity object. 194 * 195 * @param obj the object reference to check for identity 196 * @param <T> the type of the reference 197 * @return {@code obj} if {@code obj} is an identity object 198 * @throws NullPointerException if {@code obj} is {@code null} 199 * @throws IdentityException if {@code obj} is not an identity object 200 * @since Valhalla 201 */ 202 @ForceInline 203 public static <T> T requireIdentity(T obj) { 204 Objects.requireNonNull(obj); 205 var cl = obj.getClass(); 206 if (cl.isValue()) 207 throw new IdentityException(cl); 208 return obj; 209 } 210 211 /** 212 * Checks that the specified object reference is an identity object. 213 * 214 * @param obj the object reference to check for identity 215 * @param message detail message to be used in the event that an 216 * {@code IdentityException} is thrown; may be null 217 * @param <T> the type of the reference 218 * @return {@code obj} if {@code obj} is an identity object 219 * @throws NullPointerException if {@code obj} is {@code null} 220 * @throws IdentityException if {@code obj} is not an identity object 221 * @since Valhalla 222 */ 223 @ForceInline 224 public static <T> T requireIdentity(T obj, String message) { 225 Objects.requireNonNull(obj); 226 if (obj.getClass().isValue()) 227 throw new IdentityException(message); 228 return obj; 229 } 230 231 /** 232 * Checks that the specified object reference is an identity object. 233 * 234 * @param obj the object reference to check for identity 235 * @param messageSupplier supplier of the detail message to be 236 * used in the event that an {@code IdentityException} is thrown; may be null 237 * @param <T> the type of the reference 238 * @return {@code obj} if {@code obj} is an identity object 239 * @throws NullPointerException if {@code obj} is {@code null} 240 * @throws IdentityException if {@code obj} is not an identity object 241 * @since Valhalla 242 */ 243 @ForceInline 244 public static <T> T requireIdentity(T obj, Supplier<String> messageSupplier) { 245 Objects.requireNonNull(obj); 246 if (obj.getClass().isValue()) 247 throw new IdentityException(messageSupplier == null ? 248 null : messageSupplier.get()); 249 return obj; 250 } 251 252 /** 253 * Returns 0 if the arguments are identical and {@code 254 * c.compare(a, b)} otherwise. 255 * Consequently, if both arguments are {@code null} 0 256 * is returned. 257 * 258 * <p>Note that if one of the arguments is {@code null}, a {@code 259 * NullPointerException} may or may not be thrown depending on 260 * what ordering policy, if any, the {@link Comparator Comparator} 261 * chooses to have for {@code null} values. 262 * 263 * @param <T> the type of the objects being compared 264 * @param a an object 265 * @param b an object to be compared with {@code a} 266 * @param c the {@code Comparator} to compare the first two arguments 267 * @return 0 if the arguments are identical and {@code 268 * c.compare(a, b)} otherwise. 269 * @see Comparable 270 * @see Comparator 271 */ 272 public static <T> int compare(T a, T b, Comparator<? super T> c) { 273 return (a == b) ? 0 : c.compare(a, b); 274 } 275 276 /** 277 * Checks that the specified object reference is not {@code null}. This 278 * method is designed primarily for doing parameter validation in methods 279 * and constructors, as demonstrated below: 280 * <blockquote><pre> 281 * public Foo(Bar bar) { 282 * this.bar = Objects.requireNonNull(bar); 283 * } 284 * </pre></blockquote> 285 * 286 * @param obj the object reference to check for nullity 287 * @param <T> the type of the reference 288 * @return {@code obj} if not {@code null} 289 * @throws NullPointerException if {@code obj} is {@code null} 290 */ 291 @ForceInline 292 public static <T> T requireNonNull(T obj) { 293 if (obj == null) 294 throw new NullPointerException(); 295 return obj; 296 } 297 298 /** 299 * Checks that the specified object reference is not {@code null} and 300 * throws a customized {@link NullPointerException} if it is. This method 301 * is designed primarily for doing parameter validation in methods and 302 * constructors with multiple parameters, as demonstrated below: 303 * <blockquote><pre> 304 * public Foo(Bar bar, Baz baz) { 305 * this.bar = Objects.requireNonNull(bar, "bar must not be null"); 306 * this.baz = Objects.requireNonNull(baz, "baz must not be null"); 307 * } 308 * </pre></blockquote> 309 * 310 * @param obj the object reference to check for nullity 311 * @param message detail message to be used in the event that a {@code 312 * NullPointerException} is thrown 313 * @param <T> the type of the reference 314 * @return {@code obj} if not {@code null} 315 * @throws NullPointerException if {@code obj} is {@code null} 316 */ 317 @ForceInline 318 public static <T> T requireNonNull(T obj, String message) { 319 if (obj == null) 320 throw new NullPointerException(message); 321 return obj; 322 } 323 324 /** 325 * Returns {@code true} if the provided reference is {@code null} otherwise 326 * returns {@code false}. 327 * 328 * @apiNote This method exists to be used as a 329 * {@link java.util.function.Predicate}, {@code filter(Objects::isNull)} 330 * 331 * @param obj a reference to be checked against {@code null} 332 * @return {@code true} if the provided reference is {@code null} otherwise 333 * {@code false} 334 * 335 * @see java.util.function.Predicate 336 * @since 1.8 337 */ 338 public static boolean isNull(Object obj) { 339 return obj == null; 340 } 341 342 /** 343 * Returns {@code true} if the provided reference is non-{@code null} 344 * otherwise returns {@code false}. 345 * 346 * @apiNote This method exists to be used as a 347 * {@link java.util.function.Predicate}, {@code filter(Objects::nonNull)} 348 * 349 * @param obj a reference to be checked against {@code null} 350 * @return {@code true} if the provided reference is non-{@code null} 351 * otherwise {@code false} 352 * 353 * @see java.util.function.Predicate 354 * @since 1.8 355 */ 356 public static boolean nonNull(Object obj) { 357 return obj != null; 358 } 359 360 /** 361 * Returns the first argument if it is non-{@code null} and 362 * otherwise returns the non-{@code null} second argument. 363 * 364 * @param obj an object 365 * @param defaultObj a non-{@code null} object to return if the first argument 366 * is {@code null} 367 * @param <T> the type of the reference 368 * @return the first argument if it is non-{@code null} and 369 * otherwise the second argument if it is non-{@code null} 370 * @throws NullPointerException if both {@code obj} is null and 371 * {@code defaultObj} is {@code null} 372 * @since 9 373 */ 374 public static <T> T requireNonNullElse(T obj, T defaultObj) { 375 return (obj != null) ? obj : requireNonNull(defaultObj, "defaultObj"); 376 } 377 378 /** 379 * Returns the first argument if it is non-{@code null} and otherwise 380 * returns the non-{@code null} value of {@code supplier.get()}. 381 * 382 * @param obj an object 383 * @param supplier of a non-{@code null} object to return if the first argument 384 * is {@code null} 385 * @param <T> the type of the first argument and return type 386 * @return the first argument if it is non-{@code null} and otherwise 387 * the value from {@code supplier.get()} if it is non-{@code null} 388 * @throws NullPointerException if both {@code obj} is null and 389 * either the {@code supplier} is {@code null} or 390 * the {@code supplier.get()} value is {@code null} 391 * @since 9 392 */ 393 public static <T> T requireNonNullElseGet(T obj, Supplier<? extends T> supplier) { 394 return (obj != null) ? obj 395 : requireNonNull(requireNonNull(supplier, "supplier").get(), "supplier.get()"); 396 } 397 398 /** 399 * Checks that the specified object reference is not {@code null} and 400 * throws a customized {@link NullPointerException} if it is. 401 * 402 * <p>Unlike the method {@link #requireNonNull(Object, String)}, 403 * this method allows creation of the message to be deferred until 404 * after the null check is made. While this may confer a 405 * performance advantage in the non-null case, when deciding to 406 * call this method care should be taken that the costs of 407 * creating the message supplier are less than the cost of just 408 * creating the string message directly. 409 * 410 * @param obj the object reference to check for nullity 411 * @param messageSupplier supplier of the detail message to be 412 * used in the event that a {@code NullPointerException} is thrown 413 * @param <T> the type of the reference 414 * @return {@code obj} if not {@code null} 415 * @throws NullPointerException if {@code obj} is {@code null} 416 * @since 1.8 417 */ 418 public static <T> T requireNonNull(T obj, Supplier<String> messageSupplier) { 419 if (obj == null) 420 throw new NullPointerException(messageSupplier == null ? 421 null : messageSupplier.get()); 422 return obj; 423 } 424 425 /** 426 * Checks if the {@code index} is within the bounds of the range from 427 * {@code 0} (inclusive) to {@code length} (exclusive). 428 * 429 * <p>The {@code index} is defined to be out of bounds if any of the 430 * following inequalities is true: 431 * <ul> 432 * <li>{@code index < 0}</li> 433 * <li>{@code index >= length}</li> 434 * <li>{@code length < 0}, which is implied from the former inequalities</li> 435 * </ul> 436 * 437 * @param index the index 438 * @param length the upper-bound (exclusive) of the range 439 * @return {@code index} if it is within bounds of the range 440 * @throws IndexOutOfBoundsException if the {@code index} is out of bounds 441 * @since 9 442 */ 443 @ForceInline 444 public static 445 int checkIndex(int index, int length) { 446 return Preconditions.checkIndex(index, length, null); 447 } 448 449 /** 450 * Checks if the sub-range from {@code fromIndex} (inclusive) to 451 * {@code toIndex} (exclusive) is within the bounds of range from {@code 0} 452 * (inclusive) to {@code length} (exclusive). 453 * 454 * <p>The sub-range is defined to be out of bounds if any of the following 455 * inequalities is true: 456 * <ul> 457 * <li>{@code fromIndex < 0}</li> 458 * <li>{@code fromIndex > toIndex}</li> 459 * <li>{@code toIndex > length}</li> 460 * <li>{@code length < 0}, which is implied from the former inequalities</li> 461 * </ul> 462 * 463 * @param fromIndex the lower-bound (inclusive) of the sub-range 464 * @param toIndex the upper-bound (exclusive) of the sub-range 465 * @param length the upper-bound (exclusive) the range 466 * @return {@code fromIndex} if the sub-range within bounds of the range 467 * @throws IndexOutOfBoundsException if the sub-range is out of bounds 468 * @since 9 469 */ 470 public static 471 int checkFromToIndex(int fromIndex, int toIndex, int length) { 472 return Preconditions.checkFromToIndex(fromIndex, toIndex, length, null); 473 } 474 475 /** 476 * Checks if the sub-range from {@code fromIndex} (inclusive) to 477 * {@code fromIndex + size} (exclusive) is within the bounds of range from 478 * {@code 0} (inclusive) to {@code length} (exclusive). 479 * 480 * <p>The sub-range is defined to be out of bounds if any of the following 481 * inequalities is true: 482 * <ul> 483 * <li>{@code fromIndex < 0}</li> 484 * <li>{@code size < 0}</li> 485 * <li>{@code fromIndex + size > length}, taking into account integer overflow</li> 486 * <li>{@code length < 0}, which is implied from the former inequalities</li> 487 * </ul> 488 * 489 * @param fromIndex the lower-bound (inclusive) of the sub-interval 490 * @param size the size of the sub-range 491 * @param length the upper-bound (exclusive) of the range 492 * @return {@code fromIndex} if the sub-range within bounds of the range 493 * @throws IndexOutOfBoundsException if the sub-range is out of bounds 494 * @since 9 495 */ 496 public static 497 int checkFromIndexSize(int fromIndex, int size, int length) { 498 return Preconditions.checkFromIndexSize(fromIndex, size, length, null); 499 } 500 501 /** 502 * Return the size of the object in the heap. 503 * 504 * @param o an object 505 * @return the objects's size 506 * @since Valhalla 507 */ 508 public static long getObjectSize(Object o) { 509 return Unsafe.getUnsafe().getObjectSize(o); 510 } 511 512 /** 513 * Checks if the {@code index} is within the bounds of the range from 514 * {@code 0} (inclusive) to {@code length} (exclusive). 515 * 516 * <p>The {@code index} is defined to be out of bounds if any of the 517 * following inequalities is true: 518 * <ul> 519 * <li>{@code index < 0}</li> 520 * <li>{@code index >= length}</li> 521 * <li>{@code length < 0}, which is implied from the former inequalities</li> 522 * </ul> 523 * 524 * @param index the index 525 * @param length the upper-bound (exclusive) of the range 526 * @return {@code index} if it is within bounds of the range 527 * @throws IndexOutOfBoundsException if the {@code index} is out of bounds 528 * @since 16 529 */ 530 @ForceInline 531 public static 532 long checkIndex(long index, long length) { 533 return Preconditions.checkIndex(index, length, null); 534 } 535 536 /** 537 * Checks if the sub-range from {@code fromIndex} (inclusive) to 538 * {@code toIndex} (exclusive) is within the bounds of range from {@code 0} 539 * (inclusive) to {@code length} (exclusive). 540 * 541 * <p>The sub-range is defined to be out of bounds if any of the following 542 * inequalities is true: 543 * <ul> 544 * <li>{@code fromIndex < 0}</li> 545 * <li>{@code fromIndex > toIndex}</li> 546 * <li>{@code toIndex > length}</li> 547 * <li>{@code length < 0}, which is implied from the former inequalities</li> 548 * </ul> 549 * 550 * @param fromIndex the lower-bound (inclusive) of the sub-range 551 * @param toIndex the upper-bound (exclusive) of the sub-range 552 * @param length the upper-bound (exclusive) the range 553 * @return {@code fromIndex} if the sub-range within bounds of the range 554 * @throws IndexOutOfBoundsException if the sub-range is out of bounds 555 * @since 16 556 */ 557 public static 558 long checkFromToIndex(long fromIndex, long toIndex, long length) { 559 return Preconditions.checkFromToIndex(fromIndex, toIndex, length, null); 560 } 561 562 /** 563 * Checks if the sub-range from {@code fromIndex} (inclusive) to 564 * {@code fromIndex + size} (exclusive) is within the bounds of range from 565 * {@code 0} (inclusive) to {@code length} (exclusive). 566 * 567 * <p>The sub-range is defined to be out of bounds if any of the following 568 * inequalities is true: 569 * <ul> 570 * <li>{@code fromIndex < 0}</li> 571 * <li>{@code size < 0}</li> 572 * <li>{@code fromIndex + size > length}, taking into account integer overflow</li> 573 * <li>{@code length < 0}, which is implied from the former inequalities</li> 574 * </ul> 575 * 576 * @param fromIndex the lower-bound (inclusive) of the sub-interval 577 * @param size the size of the sub-range 578 * @param length the upper-bound (exclusive) of the range 579 * @return {@code fromIndex} if the sub-range within bounds of the range 580 * @throws IndexOutOfBoundsException if the sub-range is out of bounds 581 * @since 16 582 */ 583 public static 584 long checkFromIndexSize(long fromIndex, long size, long length) { 585 return Preconditions.checkFromIndexSize(fromIndex, size, length, null); 586 } 587 } --- EOF ---