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