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