001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * https://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.lang3; 018 019import java.io.IOException; 020import java.io.Serializable; 021import java.lang.reflect.Array; 022import java.time.Duration; 023import java.util.ArrayList; 024import java.util.Collection; 025import java.util.Collections; 026import java.util.Comparator; 027import java.util.HashMap; 028import java.util.Hashtable; 029import java.util.Map; 030import java.util.Objects; 031import java.util.Optional; 032import java.util.TreeSet; 033import java.util.function.Supplier; 034import java.util.stream.Stream; 035 036import org.apache.commons.lang3.exception.CloneFailedException; 037import org.apache.commons.lang3.function.Suppliers; 038import org.apache.commons.lang3.mutable.MutableInt; 039import org.apache.commons.lang3.stream.Streams; 040import org.apache.commons.lang3.text.StrBuilder; 041import org.apache.commons.lang3.time.DurationUtils; 042 043/** 044 * Operations on {@link Object}. 045 * 046 * <p> 047 * This class tries to handle {@code null} input gracefully. 048 * An exception will generally not be thrown for a {@code null} input. 049 * Each method documents its behavior in more detail. 050 * </p> 051 * 052 * <p>#ThreadSafe#</p> 053 * @since 1.0 054 */ 055//@Immutable 056@SuppressWarnings("deprecation") // deprecated class StrBuilder is imported 057// because it is part of the signature of deprecated methods 058public class ObjectUtils { 059 060 /** 061 * Class used as a null placeholder where {@code null} has another meaning. 062 * 063 * <p> 064 * For example, in a {@link HashMap} the {@link java.util.HashMap#get(Object)} method returns {@code null} if the {@link Map} contains {@code null} or if 065 * there is no matching key. The {@code null} placeholder can be used to distinguish between these two cases. 066 * </p> 067 * 068 * <p> 069 * Another example is {@link Hashtable}, where {@code null} cannot be stored. 070 * </p> 071 */ 072 public static class Null implements Serializable { 073 /** 074 * Required for serialization support. Declare serialization compatibility with Commons Lang 1.0 075 * 076 * @see java.io.Serializable 077 */ 078 private static final long serialVersionUID = 7092611880189329093L; 079 080 /** 081 * Restricted constructor - singleton. 082 */ 083 Null() { 084 } 085 086 /** 087 * Ensures singleton after serialization. 088 * 089 * @return the singleton value. 090 */ 091 private Object readResolve() { 092 return NULL; 093 } 094 } 095 096 private static final char AT_SIGN = '@'; 097 098 /** 099 * Singleton used as a {@code null} placeholder where {@code null} has another meaning. 100 * 101 * <p> 102 * For example, in a {@link HashMap} the {@link java.util.HashMap#get(Object)} method returns {@code null} if the {@link Map} contains {@code null} or if 103 * there is no matching key. The {@code null} placeholder can be used to distinguish between these two cases. 104 * </p> 105 * 106 * <p> 107 * Another example is {@link Hashtable}, where {@code null} cannot be stored. 108 * </p> 109 * 110 * <p> 111 * This instance is Serializable. 112 * </p> 113 */ 114 public static final Null NULL = new Null(); 115 116 /** 117 * Tests if all values in the array are not {@code nulls}. 118 * 119 * <p> 120 * If any value is {@code null} or the array is {@code null} then {@code false} is returned. If all elements in array are not {@code null} or the array is 121 * empty (contains no elements) {@code true} is returned. 122 * </p> 123 * 124 * <pre> 125 * ObjectUtils.allNotNull(*) = true 126 * ObjectUtils.allNotNull(*, *) = true 127 * ObjectUtils.allNotNull(null) = false 128 * ObjectUtils.allNotNull(null, null) = false 129 * ObjectUtils.allNotNull(null, *) = false 130 * ObjectUtils.allNotNull(*, null) = false 131 * ObjectUtils.allNotNull(*, *, null, *) = false 132 * </pre> 133 * 134 * @param values the values to test, may be {@code null} or empty. 135 * @return {@code false} if there is at least one {@code null} value in the array or the array is {@code null}, {@code true} if all values in the array are 136 * not {@code null}s or array contains no elements. 137 * @since 3.5 138 */ 139 public static boolean allNotNull(final Object... values) { 140 return values != null && Stream.of(values).noneMatch(Objects::isNull); 141 } 142 143 /** 144 * Tests if all values in the given array are {@code null}. 145 * 146 * <p> 147 * If all the values are {@code null} or the array is {@code null} or empty, then {@code true} is returned, otherwise {@code false} is returned. 148 * </p> 149 * 150 * <pre> 151 * ObjectUtils.allNull(*) = false 152 * ObjectUtils.allNull(*, null) = false 153 * ObjectUtils.allNull(null, *) = false 154 * ObjectUtils.allNull(null, null, *, *) = false 155 * ObjectUtils.allNull(null) = true 156 * ObjectUtils.allNull(null, null) = true 157 * </pre> 158 * 159 * @param values the values to test, may be {@code null} or empty. 160 * @return {@code true} if all values in the array are {@code null}s, {@code false} if there is at least one non-null value in the array. 161 * @since 3.11 162 */ 163 public static boolean allNull(final Object... values) { 164 return !anyNotNull(values); 165 } 166 167 /** 168 * Tests if any value in the given array is not {@code null}. 169 * 170 * <p> 171 * If all the values are {@code null} or the array is {@code null} or empty then {@code false} is returned. Otherwise {@code true} is returned. 172 * </p> 173 * 174 * <pre> 175 * ObjectUtils.anyNotNull(*) = true 176 * ObjectUtils.anyNotNull(*, null) = true 177 * ObjectUtils.anyNotNull(null, *) = true 178 * ObjectUtils.anyNotNull(null, null, *, *) = true 179 * ObjectUtils.anyNotNull(null) = false 180 * ObjectUtils.anyNotNull(null, null) = false 181 * </pre> 182 * 183 * @param values the values to test, may be {@code null} or empty. 184 * @return {@code true} if there is at least one non-null value in the array, {@code false} if all values in the array are {@code null}s. If the array is 185 * {@code null} or empty {@code false} is also returned. 186 * @since 3.5 187 */ 188 public static boolean anyNotNull(final Object... values) { 189 return firstNonNull(values) != null; 190 } 191 192 /** 193 * Tests if any value in the given array is {@code null}. 194 * 195 * <p> 196 * If any of the values are {@code null} or the array is {@code null}, then {@code true} is returned, otherwise {@code false} is returned. 197 * </p> 198 * 199 * <pre> 200 * ObjectUtils.anyNull(*) = false 201 * ObjectUtils.anyNull(*, *) = false 202 * ObjectUtils.anyNull(null) = true 203 * ObjectUtils.anyNull(null, null) = true 204 * ObjectUtils.anyNull(null, *) = true 205 * ObjectUtils.anyNull(*, null) = true 206 * ObjectUtils.anyNull(*, *, null, *) = true 207 * </pre> 208 * 209 * @param values the values to test, may be {@code null} or empty. 210 * @return {@code true} if there is at least one {@code null} value in the array, {@code false} if all the values are non-null. If the array is {@code null} 211 * or empty, {@code true} is also returned. 212 * @since 3.11 213 */ 214 public static boolean anyNull(final Object... values) { 215 return !allNotNull(values); 216 } 217 218 /** 219 * Clones an object. 220 * 221 * @param <T> the type of the object. 222 * @param obj the object to clone, null returns null. 223 * @return the clone if the object implements {@link Cloneable} otherwise {@code null}. 224 * @throws CloneFailedException if the object is cloneable and the clone operation fails. 225 * @since 3.0 226 */ 227 public static <T> T clone(final T obj) { 228 if (obj instanceof Cloneable) { 229 final Object result; 230 final Class<? extends Object> objClass = obj.getClass(); 231 if (isArray(obj)) { 232 final Class<?> componentType = objClass.getComponentType(); 233 if (componentType.isPrimitive()) { 234 int length = Array.getLength(obj); 235 result = Array.newInstance(componentType, length); 236 while (length-- > 0) { 237 Array.set(result, length, Array.get(obj, length)); 238 } 239 } else { 240 result = ((Object[]) obj).clone(); 241 } 242 } else { 243 try { 244 result = objClass.getMethod("clone").invoke(obj); 245 } catch (final ReflectiveOperationException e) { 246 throw new CloneFailedException("Exception cloning Cloneable type " + objClass.getName(), e); 247 } 248 } 249 return (T) result; 250 } 251 return null; 252 } 253 254 /** 255 * Clones an object if possible. 256 * 257 * <p> 258 * This method is similar to {@link #clone(Object)}, but will return the provided instance as the return value instead of {@code null} if the instance is 259 * not cloneable. This is more convenient if the caller uses different implementations (e.g. of a service) and some of the implementations do not allow 260 * concurrent processing or have state. In such cases the implementation can simply provide a proper clone implementation and the caller's code does not 261 * have to change. 262 * </p> 263 * 264 * @param <T> the type of the object. 265 * @param obj the object to clone, null returns null. 266 * @return the clone if the object implements {@link Cloneable} otherwise the object itself. 267 * @throws CloneFailedException if the object is cloneable and the clone operation fails. 268 * @since 3.0 269 */ 270 public static <T> T cloneIfPossible(final T obj) { 271 final T clone = clone(obj); 272 return clone == null ? obj : clone; 273 } 274 275 /** 276 * Null safe comparison of Comparables. {@code null} is assumed to be less than a non-{@code null} value. 277 * <p> 278 * TODO Move to ComparableUtils. 279 * </p> 280 * 281 * @param <T> type of the values processed by this method. 282 * @param c1 the first comparable, may be null. 283 * @param c2 the second comparable, may be null. 284 * @return a negative value if c1 < c2, zero if c1 = c2 and a positive value if c1 > c2. 285 */ 286 public static <T extends Comparable<? super T>> int compare(final T c1, final T c2) { 287 return compare(c1, c2, false); 288 } 289 290 /** 291 * Null safe comparison of Comparables. 292 * <p> 293 * TODO Move to ComparableUtils. 294 * </p> 295 * 296 * @param <T> type of the values processed by this method. 297 * @param c1 the first comparable, may be null. 298 * @param c2 the second comparable, may be null. 299 * @param nullGreater if true {@code null} is considered greater than a non-{@code null} value or if false {@code null} is considered less than a 300 * Non-{@code null} value. 301 * @return a negative value if c1 < c2, zero if c1 = c2 and a positive value if c1 > c2. 302 * @see java.util.Comparator#compare(Object, Object) 303 */ 304 public static <T extends Comparable<? super T>> int compare(final T c1, final T c2, final boolean nullGreater) { 305 if (c1 == c2) { 306 return 0; 307 } 308 if (c1 == null) { 309 return nullGreater ? 1 : -1; 310 } 311 if (c2 == null) { 312 return nullGreater ? -1 : 1; 313 } 314 return c1.compareTo(c2); 315 } 316 317 /** 318 * Returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g., 319 * 320 * <pre> 321 * public final static boolean MAGIC_FLAG = ObjectUtils.CONST(true); 322 * </pre> 323 * 324 * This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date. 325 * 326 * @param v the boolean value to return. 327 * @return the boolean v, unchanged. 328 * @since 3.2 329 */ 330 public static boolean CONST(final boolean v) { 331 return v; 332 } 333 334 /** 335 * Returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g., 336 * 337 * <pre> 338 * public final static byte MAGIC_BYTE = ObjectUtils.CONST((byte) 127); 339 * </pre> 340 * 341 * This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date. 342 * 343 * @param v the byte value to return. 344 * @return the byte v, unchanged. 345 * @since 3.2 346 */ 347 public static byte CONST(final byte v) { 348 return v; 349 } 350 351 /** 352 * Returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g., 353 * 354 * <pre> 355 * public final static char MAGIC_CHAR = ObjectUtils.CONST('a'); 356 * </pre> 357 * 358 * This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date. 359 * 360 * @param v the char value to return. 361 * @return the char v, unchanged. 362 * @since 3.2 363 */ 364 public static char CONST(final char v) { 365 return v; 366 } 367 368 /** 369 * Returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g., 370 * 371 * <pre> 372 * public final static double MAGIC_DOUBLE = ObjectUtils.CONST(1.0); 373 * </pre> 374 * 375 * This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date. 376 * 377 * @param v the double value to return. 378 * @return the double v, unchanged. 379 * @since 3.2 380 */ 381 public static double CONST(final double v) { 382 return v; 383 } 384 385 /** 386 * Returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g., 387 * 388 * <pre> 389 * public final static float MAGIC_FLOAT = ObjectUtils.CONST(1.0f); 390 * </pre> 391 * 392 * This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date. 393 * 394 * @param v the float value to return. 395 * @return the float v, unchanged. 396 * @since 3.2 397 */ 398 public static float CONST(final float v) { 399 return v; 400 } 401 402 /** 403 * Returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g., 404 * 405 * <pre> 406 * public final static int MAGIC_INT = ObjectUtils.CONST(123); 407 * </pre> 408 * 409 * This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date. 410 * 411 * @param v the int value to return. 412 * @return the int v, unchanged. 413 * @since 3.2 414 */ 415 public static int CONST(final int v) { 416 return v; 417 } 418 419 /** 420 * Returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g., 421 * 422 * <pre> 423 * public final static long MAGIC_LONG = ObjectUtils.CONST(123L); 424 * </pre> 425 * 426 * This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date. 427 * 428 * @param v the long value to return. 429 * @return the long v, unchanged. 430 * @since 3.2 431 */ 432 public static long CONST(final long v) { 433 return v; 434 } 435 436 /** 437 * Returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g., 438 * 439 * <pre> 440 * public final static short MAGIC_SHORT = ObjectUtils.CONST((short) 123); 441 * </pre> 442 * 443 * This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date. 444 * 445 * @param v the short value to return. 446 * @return the short v, unchanged. 447 * @since 3.2 448 */ 449 public static short CONST(final short v) { 450 return v; 451 } 452 453 /** 454 * Returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g., 455 * 456 * <pre> 457 * public final static String MAGIC_STRING = ObjectUtils.CONST("abc"); 458 * </pre> 459 * 460 * This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date. 461 * 462 * @param <T> the Object type. 463 * @param v the genericized Object value to return (typically a String). 464 * @return the genericized Object v, unchanged (typically a String). 465 * @since 3.2 466 */ 467 public static <T> T CONST(final T v) { 468 return v; 469 } 470 471 /** 472 * Returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g., 473 * 474 * <pre> 475 * public final static byte MAGIC_BYTE = ObjectUtils.CONST_BYTE(127); 476 * </pre> 477 * 478 * This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date. 479 * 480 * @param v the byte literal (as an int) value to return. 481 * @throws IllegalArgumentException if the value passed to v is larger than a byte, that is, smaller than -128 or larger than 127. 482 * @return the byte v, unchanged. 483 * @since 3.2 484 */ 485 public static byte CONST_BYTE(final int v) { 486 if (v < Byte.MIN_VALUE || v > Byte.MAX_VALUE) { 487 throw new IllegalArgumentException("Supplied value must be a valid byte literal between -128 and 127: [" + v + "]"); 488 } 489 return (byte) v; 490 } 491 492 /** 493 * Returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g., 494 * 495 * <pre> 496 * public final static short MAGIC_SHORT = ObjectUtils.CONST_SHORT(127); 497 * </pre> 498 * 499 * This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date. 500 * 501 * @param v the short literal (as an int) value to return. 502 * @throws IllegalArgumentException if the value passed to v is larger than a short, that is, smaller than -32768 or larger than 32767. 503 * @return the byte v, unchanged. 504 * @since 3.2 505 */ 506 public static short CONST_SHORT(final int v) { 507 if (v < Short.MIN_VALUE || v > Short.MAX_VALUE) { 508 throw new IllegalArgumentException("Supplied value must be a valid byte literal between -32768 and 32767: [" + v + "]"); 509 } 510 return (short) v; 511 } 512 513 /** 514 * Returns a default value if the object passed is {@code null}. 515 * 516 * <pre> 517 * ObjectUtils.defaultIfNull(null, null) = null 518 * ObjectUtils.defaultIfNull(null, "") = "" 519 * ObjectUtils.defaultIfNull(null, "zz") = "zz" 520 * ObjectUtils.defaultIfNull("abc", *) = "abc" 521 * ObjectUtils.defaultIfNull(Boolean.TRUE, *) = Boolean.TRUE 522 * </pre> 523 * 524 * @param <T> the type of the object. 525 * @param object the {@link Object} to test, may be {@code null}. 526 * @param defaultValue the default value to return, may be {@code null}. 527 * @return {@code object} if it is not {@code null}, defaultValue otherwise. 528 * @see #getIfNull(Object, Object) 529 * @see #getIfNull(Object, Supplier) 530 * @deprecated Use {@link #getIfNull(Object, Object)}. 531 */ 532 @Deprecated 533 public static <T> T defaultIfNull(final T object, final T defaultValue) { 534 return getIfNull(object, defaultValue); 535 } 536 537 // Null-safe equals/hashCode 538 /** 539 * Compares two objects for equality, where either one or both 540 * objects may be {@code null}. 541 * 542 * <pre> 543 * ObjectUtils.equals(null, null) = true 544 * ObjectUtils.equals(null, "") = false 545 * ObjectUtils.equals("", null) = false 546 * ObjectUtils.equals("", "") = true 547 * ObjectUtils.equals(Boolean.TRUE, null) = false 548 * ObjectUtils.equals(Boolean.TRUE, "true") = false 549 * ObjectUtils.equals(Boolean.TRUE, Boolean.TRUE) = true 550 * ObjectUtils.equals(Boolean.TRUE, Boolean.FALSE) = false 551 * </pre> 552 * 553 * @param object1 the first object, may be {@code null}. 554 * @param object2 the second object, may be {@code null}. 555 * @return {@code true} if the values of both objects are the same. 556 * @deprecated this method has been replaced by {@code java.util.Objects.equals(Object, Object)} in Java 7 and will 557 * be removed from future releases. 558 */ 559 @Deprecated 560 public static boolean equals(final Object object1, final Object object2) { 561 return Objects.equals(object1, object2); 562 } 563 564 /** 565 * Returns the first value in the array which is not {@code null}. 566 * If all the values are {@code null} or the array is {@code null} 567 * or empty then {@code null} is returned. 568 * 569 * <pre> 570 * ObjectUtils.firstNonNull(null, null) = null 571 * ObjectUtils.firstNonNull(null, "") = "" 572 * ObjectUtils.firstNonNull(null, null, "") = "" 573 * ObjectUtils.firstNonNull(null, "zz") = "zz" 574 * ObjectUtils.firstNonNull("abc", *) = "abc" 575 * ObjectUtils.firstNonNull(null, "xyz", *) = "xyz" 576 * ObjectUtils.firstNonNull(Boolean.TRUE, *) = Boolean.TRUE 577 * ObjectUtils.firstNonNull() = null 578 * </pre> 579 * 580 * @param <T> the component type of the array. 581 * @param values the values to test, may be {@code null} or empty. 582 * @return the first value from {@code values} which is not {@code null}, 583 * or {@code null} if there are no non-null values. 584 * @since 3.0 585 */ 586 @SafeVarargs 587 public static <T> T firstNonNull(final T... values) { 588 return Streams.of(values).filter(Objects::nonNull).findFirst().orElse(null); 589 } 590 591 /** 592 * Delegates to {@link Object#getClass()} using generics. 593 * 594 * @param <T> The argument type or null. 595 * @param object The argument. 596 * @return The argument's Class or null. 597 * @since 3.13.0 598 */ 599 @SuppressWarnings("unchecked") 600 public static <T> Class<T> getClass(final T object) { 601 return object == null ? null : (Class<T>) object.getClass(); 602 } 603 604 /** 605 * Executes the given suppliers in order and returns the first return value where a value other than {@code null} is returned. Once a non-{@code null} value 606 * is obtained, all following suppliers are not executed anymore. If all the return values are {@code null} or no suppliers are provided then {@code null} 607 * is returned. 608 * 609 * <pre> 610 * ObjectUtils.firstNonNullLazy(null, () -> null) = null 611 * ObjectUtils.firstNonNullLazy(() -> null, () -> "") = "" 612 * ObjectUtils.firstNonNullLazy(() -> "", () -> throw new IllegalStateException()) = "" 613 * ObjectUtils.firstNonNullLazy(() -> null, () -> "zz) = "zz" 614 * ObjectUtils.firstNonNullLazy() = null 615 * </pre> 616 * 617 * @param <T> the type of the return values. 618 * @param suppliers the suppliers returning the values to test. {@code null} values are ignored. Suppliers may return {@code null} or a value of type 619 * {@code T}. 620 * @return the first return value from {@code suppliers} which is not {@code null}, or {@code null} if there are no non-null values. 621 * @since 3.10 622 */ 623 @SafeVarargs 624 public static <T> T getFirstNonNull(final Supplier<T>... suppliers) { 625 return Streams.of(suppliers).filter(Objects::nonNull).map(Supplier::get).filter(Objects::nonNull).findFirst().orElse(null); 626 } 627 628 /** 629 * Returns the given {@code object} is it is non-null, otherwise returns the Supplier's {@link Supplier#get()} 630 * value. 631 * 632 * <p> 633 * The caller responsible for thread-safety and exception handling of default value supplier. 634 * </p> 635 * 636 * <pre> 637 * ObjectUtils.getIfNull(null, () -> null) = null 638 * ObjectUtils.getIfNull(null, null) = null 639 * ObjectUtils.getIfNull(null, () -> "") = "" 640 * ObjectUtils.getIfNull(null, () -> "zz") = "zz" 641 * ObjectUtils.getIfNull("abc", *) = "abc" 642 * ObjectUtils.getIfNull(Boolean.TRUE, *) = Boolean.TRUE 643 * </pre> 644 * 645 * @param <T> the type of the object. 646 * @param object the {@link Object} to test, may be {@code null}. 647 * @param defaultSupplier the default value to return, may be {@code null}. 648 * @return {@code object} if it is not {@code null}, {@code defaultValueSupplier.get()} otherwise. 649 * @see #getIfNull(Object, Object) 650 * @since 3.10 651 */ 652 public static <T> T getIfNull(final T object, final Supplier<T> defaultSupplier) { 653 return object != null ? object : Suppliers.get(defaultSupplier); 654 } 655 656 /** 657 * Returns a default value if the object passed is {@code null}. 658 * 659 * <pre> 660 * ObjectUtils.getIfNull(null, null) = null 661 * ObjectUtils.getIfNull(null, "") = "" 662 * ObjectUtils.getIfNull(null, "zz") = "zz" 663 * ObjectUtils.getIfNull("abc", *) = "abc" 664 * ObjectUtils.getIfNull(Boolean.TRUE, *) = Boolean.TRUE 665 * </pre> 666 * 667 * @param <T> the type of the object. 668 * @param object the {@link Object} to test, may be {@code null}. 669 * @param defaultValue the default value to return, may be {@code null}. 670 * @return {@code object} if it is not {@code null}, defaultValue otherwise. 671 * @see #getIfNull(Object, Supplier) 672 * @since 3.18.0 673 */ 674 public static <T> T getIfNull(final T object, final T defaultValue) { 675 return object != null ? object : defaultValue; 676 } 677 678 /** 679 * Gets the hash code of an object returning zero when the object is {@code null}. 680 * 681 * <pre> 682 * ObjectUtils.hashCode(null) = 0 683 * ObjectUtils.hashCode(obj) = obj.hashCode() 684 * </pre> 685 * 686 * @param obj the object to obtain the hash code of, may be {@code null}. 687 * @return the hash code of the object, or zero if null. 688 * @since 2.1 689 * @deprecated this method has been replaced by {@code java.util.Objects.hashCode(Object)} in Java 7 and will be removed in future releases. 690 */ 691 @Deprecated 692 public static int hashCode(final Object obj) { 693 // hashCode(Object) for performance vs. hashCodeMulti(Object[]), as hash code is often critical 694 return Objects.hashCode(obj); 695 } 696 697 /** 698 * Returns the hexadecimal hash code for the given object per {@link Objects#hashCode(Object)}. 699 * <p> 700 * Short hand for {@code Integer.toHexString(Objects.hashCode(object))}. 701 * </p> 702 * 703 * @param object object for which the hashCode is to be calculated. 704 * @return Hash code in hexadecimal format. 705 * @since 3.13.0 706 */ 707 public static String hashCodeHex(final Object object) { 708 return Integer.toHexString(Objects.hashCode(object)); 709 } 710 711 /** 712 * Gets the hash code for multiple objects. 713 * 714 * <p> 715 * This allows a hash code to be rapidly calculated for a number of objects. The hash code for a single object is the <em>not</em> same as 716 * {@link #hashCode(Object)}. The hash code for multiple objects is the same as that calculated by an {@link ArrayList} containing the specified objects. 717 * </p> 718 * 719 * <pre> 720 * ObjectUtils.hashCodeMulti() = 1 721 * ObjectUtils.hashCodeMulti((Object[]) null) = 1 722 * ObjectUtils.hashCodeMulti(a) = 31 + a.hashCode() 723 * ObjectUtils.hashCodeMulti(a,b) = (31 + a.hashCode()) * 31 + b.hashCode() 724 * ObjectUtils.hashCodeMulti(a,b,c) = ((31 + a.hashCode()) * 31 + b.hashCode()) * 31 + c.hashCode() 725 * </pre> 726 * 727 * @param objects the objects to obtain the hash code of, may be {@code null}. 728 * @return the hash code of the objects, or zero if null. 729 * @since 3.0 730 * @deprecated this method has been replaced by {@code java.util.Objects.hash(Object...)} in Java 7 and will be removed in future releases. 731 */ 732 @Deprecated 733 public static int hashCodeMulti(final Object... objects) { 734 int hash = 1; 735 if (objects != null) { 736 for (final Object object : objects) { 737 final int tmpHash = Objects.hashCode(object); 738 hash = hash * 31 + tmpHash; 739 } 740 } 741 return hash; 742 } 743 744 /** 745 * Returns the hexadecimal hash code for the given object per {@link System#identityHashCode(Object)}. 746 * <p> 747 * Short hand for {@code Integer.toHexString(System.identityHashCode(object))}. 748 * </p> 749 * 750 * @param object object for which the hashCode is to be calculated. 751 * @return Hash code in hexadecimal format. 752 * @since 3.13.0 753 */ 754 public static String identityHashCodeHex(final Object object) { 755 return Integer.toHexString(System.identityHashCode(object)); 756 } 757 758 /** 759 * Appends the toString that would be produced by {@link Object} 760 * if a class did not override toString itself. {@code null} 761 * will throw a NullPointerException for either of the two parameters. 762 * 763 * <pre> 764 * ObjectUtils.identityToString(appendable, "") = appendable.append("java.lang.String@1e23") 765 * ObjectUtils.identityToString(appendable, Boolean.TRUE) = appendable.append("java.lang.Boolean@7fa") 766 * ObjectUtils.identityToString(appendable, Boolean.TRUE) = appendable.append("java.lang.Boolean@7fa") 767 * </pre> 768 * 769 * @param appendable the appendable to append to. 770 * @param object the object to create a toString for. 771 * @throws IOException if an I/O error occurs. 772 * @since 3.2 773 */ 774 public static void identityToString(final Appendable appendable, final Object object) throws IOException { 775 Objects.requireNonNull(object, "object"); 776 appendable.append(object.getClass().getName()) 777 .append(AT_SIGN) 778 .append(identityHashCodeHex(object)); 779 } 780 781 /** 782 * Gets the toString that would be produced by {@link Object} if a class did not override toString itself. {@code null} will return {@code null}. 783 * 784 * <pre> 785 * ObjectUtils.identityToString(null) = null 786 * ObjectUtils.identityToString("") = "java.lang.String@1e23" 787 * ObjectUtils.identityToString(Boolean.TRUE) = "java.lang.Boolean@7fa" 788 * </pre> 789 * 790 * @param object the object to create a toString for, may be {@code null}. 791 * @return the default toString text, or {@code null} if {@code null} passed in. 792 */ 793 public static String identityToString(final Object object) { 794 if (object == null) { 795 return null; 796 } 797 final String name = object.getClass().getName(); 798 final String hexString = identityHashCodeHex(object); 799 final StringBuilder builder = new StringBuilder(name.length() + 1 + hexString.length()); 800 // @formatter:off 801 builder.append(name) 802 .append(AT_SIGN) 803 .append(hexString); 804 // @formatter:on 805 return builder.toString(); 806 } 807 808 /** 809 * Appends the toString that would be produced by {@link Object} 810 * if a class did not override toString itself. {@code null} 811 * will throw a NullPointerException for either of the two parameters. 812 * 813 * <pre> 814 * ObjectUtils.identityToString(builder, "") = builder.append("java.lang.String@1e23") 815 * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa") 816 * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa") 817 * </pre> 818 * 819 * @param builder the builder to append to. 820 * @param object the object to create a toString for. 821 * @since 3.2 822 * @deprecated as of 3.6, because StrBuilder was moved to commons-text, 823 * use one of the other {@code identityToString} methods instead 824 */ 825 @Deprecated 826 public static void identityToString(final StrBuilder builder, final Object object) { 827 Objects.requireNonNull(object, "object"); 828 final String name = object.getClass().getName(); 829 final String hexString = identityHashCodeHex(object); 830 builder.ensureCapacity(builder.length() + name.length() + 1 + hexString.length()); 831 builder.append(name) 832 .append(AT_SIGN) 833 .append(hexString); 834 } 835 836 /** 837 * Appends the toString that would be produced by {@link Object} 838 * if a class did not override toString itself. {@code null} 839 * will throw a NullPointerException for either of the two parameters. 840 * 841 * <pre> 842 * ObjectUtils.identityToString(buf, "") = buf.append("java.lang.String@1e23") 843 * ObjectUtils.identityToString(buf, Boolean.TRUE) = buf.append("java.lang.Boolean@7fa") 844 * ObjectUtils.identityToString(buf, Boolean.TRUE) = buf.append("java.lang.Boolean@7fa") 845 * </pre> 846 * 847 * @param buffer the buffer to append to. 848 * @param object the object to create a toString for. 849 * @since 2.4 850 */ 851 public static void identityToString(final StringBuffer buffer, final Object object) { 852 Objects.requireNonNull(object, "object"); 853 final String name = object.getClass().getName(); 854 final String hexString = identityHashCodeHex(object); 855 buffer.ensureCapacity(buffer.length() + name.length() + 1 + hexString.length()); 856 buffer.append(name) 857 .append(AT_SIGN) 858 .append(hexString); 859 } 860 861 /** 862 * Appends the toString that would be produced by {@link Object} 863 * if a class did not override toString itself. {@code null} 864 * will throw a NullPointerException for either of the two parameters. 865 * 866 * <pre> 867 * ObjectUtils.identityToString(builder, "") = builder.append("java.lang.String@1e23") 868 * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa") 869 * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa") 870 * </pre> 871 * 872 * @param builder the builder to append to. 873 * @param object the object to create a toString for. 874 * @since 3.2 875 */ 876 public static void identityToString(final StringBuilder builder, final Object object) { 877 Objects.requireNonNull(object, "object"); 878 final String name = object.getClass().getName(); 879 final String hexString = identityHashCodeHex(object); 880 builder.ensureCapacity(builder.length() + name.length() + 1 + hexString.length()); 881 builder.append(name) 882 .append(AT_SIGN) 883 .append(hexString); 884 } 885 886 /** 887 * Tests whether the given object is an Object array or a primitive array in a null-safe manner. 888 * 889 * <p> 890 * A {@code null} {@code object} Object will return {@code false}. 891 * </p> 892 * 893 * <pre> 894 * ObjectUtils.isArray(null) = false 895 * ObjectUtils.isArray("") = false 896 * ObjectUtils.isArray("ab") = false 897 * ObjectUtils.isArray(new int[]{}) = true 898 * ObjectUtils.isArray(new int[]{1,2,3}) = true 899 * ObjectUtils.isArray(1234) = false 900 * </pre> 901 * 902 * @param object the object to check, may be {@code null}. 903 * @return {@code true} if the object is an {@code array}, {@code false} otherwise. 904 * @since 3.13.0 905 */ 906 public static boolean isArray(final Object object) { 907 return object != null && object.getClass().isArray(); 908 } 909 910 /** 911 * Tests if an Object is empty or null. 912 * <p> 913 * The following types are supported: 914 * </p> 915 * <ul> 916 * <li>{@link CharSequence}: Considered empty if its length is zero.</li> 917 * <li>{@link Array}: Considered empty if its length is zero.</li> 918 * <li>{@link Collection}: Considered empty if it has zero elements.</li> 919 * <li>{@link Map}: Considered empty if it has zero key-value mappings.</li> 920 * <li>{@link Optional}: Considered empty if {@link Optional#isPresent} returns false, regardless of the "emptiness" of the contents.</li> 921 * </ul> 922 * 923 * <pre> 924 * ObjectUtils.isEmpty(null) = true 925 * ObjectUtils.isEmpty("") = true 926 * ObjectUtils.isEmpty("ab") = false 927 * ObjectUtils.isEmpty(new int[]{}) = true 928 * ObjectUtils.isEmpty(new int[]{1,2,3}) = false 929 * ObjectUtils.isEmpty(1234) = false 930 * ObjectUtils.isEmpty(1234) = false 931 * ObjectUtils.isEmpty(Optional.of("")) = false 932 * ObjectUtils.isEmpty(Optional.empty()) = true 933 * </pre> 934 * 935 * @param object the {@link Object} to test, may be {@code null}. 936 * @return {@code true} if the object has a supported type and is empty or null, {@code false} otherwise. 937 * @since 3.9 938 */ 939 public static boolean isEmpty(final Object object) { 940 if (object == null) { 941 return true; 942 } 943 if (object instanceof CharSequence) { 944 return ((CharSequence) object).length() == 0; 945 } 946 if (isArray(object)) { 947 return Array.getLength(object) == 0; 948 } 949 if (object instanceof Collection<?>) { 950 return ((Collection<?>) object).isEmpty(); 951 } 952 if (object instanceof Map<?, ?>) { 953 return ((Map<?, ?>) object).isEmpty(); 954 } 955 if (object instanceof Optional<?>) { 956 // TODO Java 11 Use Optional#isEmpty() 957 return !((Optional<?>) object).isPresent(); 958 } 959 return false; 960 } 961 962 /** 963 * Tests if an Object is not empty and not null. 964 * <p> 965 * The following types are supported: 966 * </p> 967 * <ul> 968 * <li>{@link CharSequence}: Considered empty if its length is zero.</li> 969 * <li>{@link Array}: Considered empty if its length is zero.</li> 970 * <li>{@link Collection}: Considered empty if it has zero elements.</li> 971 * <li>{@link Map}: Considered empty if it has zero key-value mappings.</li> 972 * <li>{@link Optional}: Considered empty if {@link Optional#isPresent} returns false, regardless of the "emptiness" of the contents.</li> 973 * </ul> 974 * 975 * <pre> 976 * ObjectUtils.isNotEmpty(null) = false 977 * ObjectUtils.isNotEmpty("") = false 978 * ObjectUtils.isNotEmpty("ab") = true 979 * ObjectUtils.isNotEmpty(new int[]{}) = false 980 * ObjectUtils.isNotEmpty(new int[]{1,2,3}) = true 981 * ObjectUtils.isNotEmpty(1234) = true 982 * ObjectUtils.isNotEmpty(Optional.of("")) = true 983 * ObjectUtils.isNotEmpty(Optional.empty()) = false 984 * </pre> 985 * 986 * @param object the {@link Object} to test, may be {@code null}. 987 * @return {@code true} if the object has an unsupported type or is not empty. 988 * and not null, {@code false} otherwise. 989 * @since 3.9 990 */ 991 public static boolean isNotEmpty(final Object object) { 992 return !isEmpty(object); 993 } 994 995 /** 996 * Null safe comparison of Comparables. 997 * <p> 998 * TODO Move to ComparableUtils. 999 * </p> 1000 * 1001 * @param <T> type of the values processed by this method. 1002 * @param values the set of comparable values, may be null. 1003 * @return 1004 * <ul> 1005 * <li>If any objects are non-null and unequal, the greater object. 1006 * <li>If all objects are non-null and equal, the first. 1007 * <li>If any of the comparables are null, the greater of the non-null objects. 1008 * <li>If all the comparables are null, null is returned. 1009 * </ul> 1010 */ 1011 @SafeVarargs 1012 public static <T extends Comparable<? super T>> T max(final T... values) { 1013 T result = null; 1014 if (values != null) { 1015 for (final T value : values) { 1016 if (compare(value, result, false) > 0) { 1017 result = value; 1018 } 1019 } 1020 } 1021 return result; 1022 } 1023 1024 /** 1025 * Finds the "best guess" middle value among comparables. If there is an even 1026 * number of total values, the lower of the two middle values will be returned. 1027 * 1028 * @param <T> type of values processed by this method. 1029 * @param comparator to use for comparisons. 1030 * @param items to compare. 1031 * @return T at middle position. 1032 * @throws NullPointerException if items or comparator is {@code null}. 1033 * @throws IllegalArgumentException if items is empty or contains {@code null} values. 1034 * @since 3.0.1 1035 */ 1036 @SafeVarargs 1037 public static <T> T median(final Comparator<T> comparator, final T... items) { 1038 Validate.notEmpty(items, "null/empty items"); 1039 Validate.noNullElements(items); 1040 Objects.requireNonNull(comparator, "comparator"); 1041 final TreeSet<T> treeSet = new TreeSet<>(comparator); 1042 Collections.addAll(treeSet, items); 1043 return (T) treeSet.toArray()[(treeSet.size() - 1) / 2]; 1044 } 1045 1046 /** 1047 * Finds the "best guess" middle value among comparables. If there is an even number of total values, the lower of the two middle values will be returned. 1048 * 1049 * @param <T> type of values processed by this method. 1050 * @param items to compare. 1051 * @return T at middle position. 1052 * @throws NullPointerException if items is {@code null}. 1053 * @throws IllegalArgumentException if items is empty or contains {@code null} values. 1054 * @since 3.0.1 1055 */ 1056 @SafeVarargs 1057 public static <T extends Comparable<? super T>> T median(final T... items) { 1058 Validate.notEmpty(items); 1059 Validate.noNullElements(items); 1060 final TreeSet<T> sort = new TreeSet<>(); 1061 Collections.addAll(sort, items); 1062 return (T) sort.toArray()[(sort.size() - 1) / 2]; 1063 } 1064 1065 /** 1066 * Null safe comparison of Comparables. 1067 * <p> 1068 * TODO Move to ComparableUtils. 1069 * </p> 1070 * 1071 * @param <T> type of the values processed by this method 1072 * @param values the set of comparable values, may be null 1073 * @return 1074 * <ul> 1075 * <li>If any objects are non-null and unequal, the lesser object. 1076 * <li>If all objects are non-null and equal, the first. 1077 * <li>If any of the comparables are null, the lesser of the non-null objects. 1078 * <li>If all the comparables are null, null is returned. 1079 * </ul> 1080 */ 1081 @SafeVarargs 1082 public static <T extends Comparable<? super T>> T min(final T... values) { 1083 T result = null; 1084 if (values != null) { 1085 for (final T value : values) { 1086 if (compare(value, result, true) < 0) { 1087 result = value; 1088 } 1089 } 1090 } 1091 return result; 1092 } 1093 1094 /** 1095 * Finds the most frequently occurring item. 1096 * 1097 * @param <T> type of values processed by this method. 1098 * @param items to check. 1099 * @return most populous T, {@code null} if non-unique or no items supplied. 1100 * @since 3.0.1 1101 */ 1102 @SafeVarargs 1103 public static <T> T mode(final T... items) { 1104 if (ArrayUtils.isNotEmpty(items)) { 1105 final HashMap<T, MutableInt> occurrences = new HashMap<>(items.length); 1106 for (final T t : items) { 1107 ArrayUtils.increment(occurrences, t); 1108 } 1109 T result = null; 1110 int max = 0; 1111 for (final Map.Entry<T, MutableInt> e : occurrences.entrySet()) { 1112 final int cmp = e.getValue().intValue(); 1113 if (cmp == max) { 1114 result = null; 1115 } else if (cmp > max) { 1116 max = cmp; 1117 result = e.getKey(); 1118 } 1119 } 1120 return result; 1121 } 1122 return null; 1123 } 1124 1125 /** 1126 * Compares two objects for inequality, where either one or both 1127 * objects may be {@code null}. 1128 * 1129 * <pre> 1130 * ObjectUtils.notEqual(null, null) = false 1131 * ObjectUtils.notEqual(null, "") = true 1132 * ObjectUtils.notEqual("", null) = true 1133 * ObjectUtils.notEqual("", "") = false 1134 * ObjectUtils.notEqual(Boolean.TRUE, null) = true 1135 * ObjectUtils.notEqual(Boolean.TRUE, "true") = true 1136 * ObjectUtils.notEqual(Boolean.TRUE, Boolean.TRUE) = false 1137 * ObjectUtils.notEqual(Boolean.TRUE, Boolean.FALSE) = true 1138 * </pre> 1139 * 1140 * @param object1 the first object, may be {@code null}. 1141 * @param object2 the second object, may be {@code null}. 1142 * @return {@code false} if the values of both objects are the same. 1143 */ 1144 public static boolean notEqual(final Object object1, final Object object2) { 1145 return !Objects.equals(object1, object2); 1146 } 1147 1148 /** 1149 * Checks that the specified object reference is not {@code null} or empty per {@link #isEmpty(Object)}. Use this 1150 * method for validation, for example: 1151 * 1152 * <pre> 1153 * public Foo(Bar bar) { 1154 * this.bar = Objects.requireNonEmpty(bar); 1155 * } 1156 * </pre> 1157 * 1158 * @param <T> the type of the reference. 1159 * @param obj the object reference to check for nullity. 1160 * @return {@code obj} if not {@code null}. 1161 * @throws NullPointerException if {@code obj} is {@code null}. 1162 * @throws IllegalArgumentException if {@code obj} is empty per {@link #isEmpty(Object)}. 1163 * @see #isEmpty(Object) 1164 * @since 3.12.0 1165 */ 1166 public static <T> T requireNonEmpty(final T obj) { 1167 return requireNonEmpty(obj, "object"); 1168 } 1169 1170 /** 1171 * Checks that the specified object reference is not {@code null} or empty per {@link #isEmpty(Object)}. Use this 1172 * method for validation, for example: 1173 * 1174 * <pre> 1175 * public Foo(Bar bar) { 1176 * this.bar = Objects.requireNonEmpty(bar, "bar"); 1177 * } 1178 * </pre> 1179 * 1180 * @param <T> the type of the reference. 1181 * @param obj the object reference to check for nullity. 1182 * @param message the exception message. 1183 * @return {@code obj} if not {@code null}. 1184 * @throws NullPointerException if {@code obj} is {@code null}. 1185 * @throws IllegalArgumentException if {@code obj} is empty per {@link #isEmpty(Object)}. 1186 * @see #isEmpty(Object) 1187 * @since 3.12.0 1188 */ 1189 public static <T> T requireNonEmpty(final T obj, final String message) { 1190 // check for null first to give the most precise exception. 1191 Objects.requireNonNull(obj, message); 1192 if (isEmpty(obj)) { 1193 throw new IllegalArgumentException(message); 1194 } 1195 return obj; 1196 } 1197 1198 /** 1199 * Gets the {@code toString()} of an {@link Object} or the empty string ({@code ""}) if the input is {@code null}. 1200 * 1201 * <pre> 1202 * ObjectUtils.toString(null) = "" 1203 * ObjectUtils.toString("") = "" 1204 * ObjectUtils.toString("bat") = "bat" 1205 * ObjectUtils.toString(Boolean.TRUE) = "true" 1206 * </pre> 1207 * 1208 * @param obj the Object to {@code toString()}, may be {@code null}. 1209 * @return the input's {@code toString()}, or {@code ""} if the input is {@code null}. 1210 * @see Objects#toString(Object) 1211 * @see Objects#toString(Object, String) 1212 * @see StringUtils#defaultString(String) 1213 * @see String#valueOf(Object) 1214 * @since 2.0 1215 */ 1216 public static String toString(final Object obj) { 1217 return Objects.toString(obj, StringUtils.EMPTY); 1218 } 1219 1220 /** 1221 * Gets the {@code toString} of an {@link Object} returning 1222 * a specified text if {@code null} input. 1223 * 1224 * <pre> 1225 * ObjectUtils.toString(null, null) = null 1226 * ObjectUtils.toString(null, "null") = "null" 1227 * ObjectUtils.toString("", "null") = "" 1228 * ObjectUtils.toString("bat", "null") = "bat" 1229 * ObjectUtils.toString(Boolean.TRUE, "null") = "true" 1230 * </pre> 1231 * 1232 * @param obj the Object to {@code toString}, may be null. 1233 * @param nullStr the String to return if {@code null} input, may be null. 1234 * @return the passed in Object's toString, or {@code nullStr} if {@code null} input. 1235 * @see Objects#toString(Object) 1236 * @see Objects#toString(Object, String) 1237 * @see StringUtils#defaultString(String,String) 1238 * @see String#valueOf(Object) 1239 * @since 2.0 1240 * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object, String)} in Java 7 and 1241 * will be removed in future releases. 1242 */ 1243 @Deprecated 1244 public static String toString(final Object obj, final String nullStr) { 1245 return Objects.toString(obj, nullStr); 1246 } 1247 1248 /** 1249 * Gets the {@code toString} of an {@link Supplier}'s {@link Supplier#get()} returning 1250 * a specified text if {@code null} input. 1251 * 1252 * <pre> 1253 * ObjectUtils.toString(() -> obj, () -> expensive()) 1254 * </pre> 1255 * <pre> 1256 * ObjectUtils.toString(() -> null, () -> expensive()) = result of expensive() 1257 * ObjectUtils.toString(() -> null, () -> expensive()) = result of expensive() 1258 * ObjectUtils.toString(() -> "", () -> expensive()) = "" 1259 * ObjectUtils.toString(() -> "bat", () -> expensive()) = "bat" 1260 * ObjectUtils.toString(() -> Boolean.TRUE, () -> expensive()) = "true" 1261 * </pre> 1262 * 1263 * @param obj the Object to {@code toString}, may be null. 1264 * @param supplier the Supplier of String used on {@code null} input, may be null. 1265 * @return the passed in Object's toString, or {@code nullStr} if {@code null} input. 1266 * @since 3.14.0 1267 */ 1268 public static String toString(final Supplier<Object> obj, final Supplier<String> supplier) { 1269 return obj == null ? Suppliers.get(supplier) : toString(obj.get(), supplier); 1270 } 1271 1272 /** 1273 * Gets the {@code toString} of an {@link Object} returning 1274 * a specified text if {@code null} input. 1275 * 1276 * <pre> 1277 * ObjectUtils.toString(obj, () -> expensive()) 1278 * </pre> 1279 * <pre> 1280 * ObjectUtils.toString(null, () -> expensive()) = result of expensive() 1281 * ObjectUtils.toString(null, () -> expensive()) = result of expensive() 1282 * ObjectUtils.toString("", () -> expensive()) = "" 1283 * ObjectUtils.toString("bat", () -> expensive()) = "bat" 1284 * ObjectUtils.toString(Boolean.TRUE, () -> expensive()) = "true" 1285 * </pre> 1286 * 1287 * @param <T> the obj type (used to provide better source compatibility in 3.14.0). 1288 * @param obj the Object to {@code toString}, may be null. 1289 * @param supplier the Supplier of String used on {@code null} input, may be null. 1290 * @return the passed in Object's toString, or {@code nullStr} if {@code null} input. 1291 * @since 3.11 1292 */ 1293 public static <T> String toString(final T obj, final Supplier<String> supplier) { 1294 return obj == null ? Suppliers.get(supplier) : obj.toString(); 1295 } 1296 1297 /** 1298 * Calls {@link Object#wait(long, int)} for the given Duration. 1299 * 1300 * @param obj The receiver of the wait call. 1301 * @param duration How long to wait. 1302 * @throws IllegalArgumentException if the timeout duration is negative. 1303 * @throws IllegalMonitorStateException if the current thread is not the owner of the {@code obj}'s monitor. 1304 * @throws InterruptedException if any thread interrupted the current thread before or while the current thread was 1305 * waiting for a notification. The <em>interrupted status</em> of the current thread is cleared when this 1306 * exception is thrown. 1307 * @see Object#wait(long, int) 1308 * @since 3.12.0 1309 */ 1310 public static void wait(final Object obj, final Duration duration) throws InterruptedException { 1311 DurationUtils.accept(obj::wait, DurationUtils.zeroIfNull(duration)); 1312 } 1313 1314 /** 1315 * {@link ObjectUtils} instances should NOT be constructed in standard programming. Instead, the static methods on the class should be used, such as 1316 * {@code ObjectUtils.defaultIfNull("a","b");}. 1317 * 1318 * <p> 1319 * This constructor is public to permit tools that require a JavaBean instance to operate. 1320 * </p> 1321 * 1322 * @deprecated TODO Make private in 4.0. 1323 */ 1324 @Deprecated 1325 public ObjectUtils() { 1326 // empty 1327 } 1328 1329}