ObjectUtils (Apache Commons Lang 3.17.0 API)
Description: declaration: package: org.apache.commons.lang3, class: ObjectUtils

Package org.apache.commons.lang3

# Class ObjectUtils

java.lang.Object
org.apache.commons.lang3.ObjectUtils

public class ObjectUtils extends Object
Operations on `Object`.

This class tries to handle `null` input gracefully. An exception will generally not be thrown for a `null` input. Each method documents its behavior in more detail.

#ThreadSafe#

Since:
  1.0

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `ObjectUtils.Null`
  Class used as a null placeholder where `null` has another meaning.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final ObjectUtils.Null`
  `NULL`
  Singleton used as a `null` placeholder where `null` has another meaning.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ObjectUtils()`
  Deprecated.
  TODO Make private in 4.0.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static boolean`
  `allNotNull(Object... values)`
  Tests if all values in the array are not `nulls`.
  `static boolean`
  `allNull(Object... values)`
  Tests if all values in the given array are `null`.
  `static boolean`
  `anyNotNull(Object... values)`
  Tests if any value in the given array is not `null`.
  `static boolean`
  `anyNull(Object... values)`
  Tests if any value in the given array is `null`.
  `static <T> T`
  `clone(T obj)`
  Clones an object.
  `static <T> T`
  `cloneIfPossible(T obj)`
  Clones an object if possible.
  `static <T extends Comparable<? super T>>
  int`
  `compare(T c1, T c2)`
  Null safe comparison of Comparables.
  `static <T extends Comparable<? super T>>
  int`
  `compare(T c1, T c2, boolean nullGreater)`
  Null safe comparison of Comparables.
  `static boolean`
  `CONST(boolean v)`
  Returns the provided value unchanged.
  `static byte`
  `CONST(byte v)`
  Returns the provided value unchanged.
  `static char`
  `CONST(char v)`
  Returns the provided value unchanged.
  `static double`
  `CONST(double v)`
  Returns the provided value unchanged.
  `static float`
  `CONST(float v)`
  Returns the provided value unchanged.
  `static int`
  `CONST(int v)`
  Returns the provided value unchanged.
  `static long`
  `CONST(long v)`
  Returns the provided value unchanged.
  `static short`
  `CONST(short v)`
  Returns the provided value unchanged.
  `static <T> T`
  `CONST(T v)`
  Returns the provided value unchanged.
  `static byte`
  `CONST_BYTE(int v)`
  Returns the provided value unchanged.
  `static short`
  `CONST_SHORT(int v)`
  Returns the provided value unchanged.
  `static <T> T`
  `defaultIfNull(T object, T defaultValue)`
  Returns a default value if the object passed is `null`.
  `static boolean`
  `equals(Object object1, Object object2)`
  Deprecated.
  this method has been replaced by `java.util.Objects.equals(Object, Object)` in Java 7 and will be removed from future releases.
  `static <T> T`
  `firstNonNull(T... values)`
  Returns the first value in the array which is not `null`.
  `static <T> Class<T>`
  `getClass(T object)`
  Delegates to `Object.getClass()` using generics.
  `static <T> T`
  `getFirstNonNull(Supplier<T>... suppliers)`
  Executes the given suppliers in order and returns the first return value where a value other than `null` is returned.
  `static <T> T`
  `getIfNull(T object, Supplier<T> defaultSupplier)`
  Returns the given `object` is it is non-null, otherwise returns the Supplier's `Supplier.get()` value.
  `static int`
  `hashCode(Object obj)`
  Deprecated.
  this method has been replaced by `java.util.Objects.hashCode(Object)` in Java 7 and will be removed in future releases
  `static String`
  `hashCodeHex(Object object)`
  Returns the hexadecimal hash code for the given object per `Objects.hashCode(Object)`.
  `static int`
  `hashCodeMulti(Object... objects)`
  Deprecated.
  this method has been replaced by `java.util.Objects.hash(Object...)` in Java 7 and will be removed in future releases.
  `static String`
  `identityHashCodeHex(Object object)`
  Returns the hexadecimal hash code for the given object per `System.identityHashCode(Object)`.
  `static void`
  `identityToString(Appendable appendable, Object object)`
  Appends the toString that would be produced by `Object` if a class did not override toString itself.
  `static String`
  `identityToString(Object object)`
  Gets the toString that would be produced by `Object` if a class did not override toString itself.
  `static void`
  `identityToString(StringBuffer buffer, Object object)`
  Appends the toString that would be produced by `Object` if a class did not override toString itself.
  `static void`
  `identityToString(StringBuilder builder, Object object)`
  Appends the toString that would be produced by `Object` if a class did not override toString itself.
  `static void`
  `identityToString(StrBuilder builder, Object object)`
  Deprecated.
  as of 3.6, because StrBuilder was moved to commons-text, use one of the other `identityToString` methods instead
  `static boolean`
  `isArray(Object object)`
  Tests whether the given object is an Object array or a primitive array in a null-safe manner.
  `static boolean`
  `isEmpty(Object object)`
  Tests if an Object is empty or null.
  `static boolean`
  `isNotEmpty(Object object)`
  Tests if an Object is not empty and not null.
  `static <T extends Comparable<? super T>>
  T`
  `max(T... values)`
  Null safe comparison of Comparables.
  `static <T> T`
  `median(Comparator<T> comparator, T... items)`
  Find the "best guess" middle value among comparables.
  `static <T extends Comparable<? super T>>
  T`
  `median(T... items)`
  Find the "best guess" middle value among comparables.
  `static <T extends Comparable<? super T>>
  T`
  `min(T... values)`
  Null safe comparison of Comparables.
  `static <T> T`
  `mode(T... items)`
  Find the most frequently occurring item.
  `static boolean`
  `notEqual(Object object1, Object object2)`
  Compares two objects for inequality, where either one or both objects may be `null`.
  `static <T> T`
  `requireNonEmpty(T obj)`
  Checks that the specified object reference is not `null` or empty per `isEmpty(Object)`.
  `static <T> T`
  `requireNonEmpty(T obj, String message)`
  Checks that the specified object reference is not `null` or empty per `isEmpty(Object)`.
  `static String`
  `toString(Object obj)`
  Deprecated.
  this method has been replaced by `java.util.Objects.toString(Object)` in Java 7 and will be removed in future releases.
  `static String`
  `toString(Object obj, String nullStr)`
  Deprecated.
  this method has been replaced by `java.util.Objects.toString(Object, String)` in Java 7 and will be removed in future releases.
  `static String`
  `toString(Supplier<Object> obj, Supplier<String> supplier)`
  Gets the `toString` of an `Supplier`'s `Supplier.get()` returning a specified text if `null` input.
  `static <T> String`
  `toString(T obj, Supplier<String> supplier)`
  Gets the `toString` of an `Object` returning a specified text if `null` input.
  `static void`
  `wait(Object obj, Duration duration)`
  Calls `Object.wait(long, int)` for the given Duration.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### NULL

    public static final ObjectUtils.Null NULL
    Singleton used as a `null` placeholder where `null` has another meaning.

    For example, in a `HashMap` the `HashMap.get(Object)` method returns `null` if the `Map` contains `null` or if there is no matching key. The `null` placeholder can be used to distinguish between these two cases.

    Another example is `Hashtable`, where `null` cannot be stored.

    This instance is Serializable.

- ## Constructor Details

  - ### ObjectUtils

    @Deprecated public ObjectUtils()
    Deprecated.
    TODO Make private in 4.0.
    `ObjectUtils` instances should NOT be constructed in standard programming. Instead, the static methods on the class should be used, such as `ObjectUtils.defaultIfNull("a","b");`.

    This constructor is public to permit tools that require a JavaBean instance to operate.

- ## Method Details

  - ### allNotNull

    public static boolean allNotNull(Object... values)
    Tests if all values in the array are not `nulls`.

    If any value is `null` or the array is `null` then `false` is returned. If all elements in array are not `null` or the array is empty (contains no elements) `true` is returned.

         ObjectUtils.allNotNull(*)             = true
         ObjectUtils.allNotNull(*, *)          = true
         ObjectUtils.allNotNull(null)          = false
         ObjectUtils.allNotNull(null, null)    = false
         ObjectUtils.allNotNull(null, *)       = false
         ObjectUtils.allNotNull(*, null)       = false
         ObjectUtils.allNotNull(*, *, null, *) = false

    Parameters:
      `values` - the values to test, may be `null` or empty
    Returns:
      `false` if there is at least one `null` value in the array or the array is `null`, `true` if all values in the array are not `null`s or array contains no elements.
    Since:
      3.5

  - ### allNull

    public static boolean allNull(Object... values)
    Tests if all values in the given array are `null`.

    If all the values are `null` or the array is `null` or empty, then `true` is returned, otherwise `false` is returned.

         ObjectUtils.allNull(*)                = false
         ObjectUtils.allNull(*, null)          = false
         ObjectUtils.allNull(null, *)          = false
         ObjectUtils.allNull(null, null, *, *) = false
         ObjectUtils.allNull(null)             = true
         ObjectUtils.allNull(null, null)       = true

    Parameters:
      `values` - the values to test, may be `null` or empty
    Returns:
      `true` if all values in the array are `null`s, `false` if there is at least one non-null value in the array.
    Since:
      3.11

  - ### anyNotNull

    public static boolean anyNotNull(Object... values)
    Tests if any value in the given array is not `null`.

    If all the values are `null` or the array is `null` or empty then `false` is returned. Otherwise `true` is returned.

         ObjectUtils.anyNotNull(*)                = true
         ObjectUtils.anyNotNull(*, null)          = true
         ObjectUtils.anyNotNull(null, *)          = true
         ObjectUtils.anyNotNull(null, null, *, *) = true
         ObjectUtils.anyNotNull(null)             = false
         ObjectUtils.anyNotNull(null, null)       = false

    Parameters:
      `values` - the values to test, may be `null` or empty
    Returns:
      `true` if there is at least one non-null value in the array, `false` if all values in the array are `null`s. If the array is `null` or empty `false` is also returned.
    Since:
      3.5

  - ### anyNull

    public static boolean anyNull(Object... values)
    Tests if any value in the given array is `null`.

    If any of the values are `null` or the array is `null`, then `true` is returned, otherwise `false` is returned.

         ObjectUtils.anyNull(*)             = false
         ObjectUtils.anyNull(*, *)          = false
         ObjectUtils.anyNull(null)          = true
         ObjectUtils.anyNull(null, null)    = true
         ObjectUtils.anyNull(null, *)       = true
         ObjectUtils.anyNull(*, null)       = true
         ObjectUtils.anyNull(*, *, null, *) = true

    Parameters:
      `values` - the values to test, may be `null` or empty
    Returns:
      `true` if there is at least one `null` value in the array, `false` if all the values are non-null. If the array is `null` or empty, `true` is also returned.
    Since:
      3.11

  - ### clone

    public static <T> T clone(T obj)
    Clones an object.
    Type Parameters:
      `T` - the type of the object
    Parameters:
      `obj` - the object to clone, null returns null
    Returns:
      the clone if the object implements `Cloneable` otherwise `null`
    Throws:
      `CloneFailedException` - if the object is cloneable and the clone operation fails
    Since:
      3.0

  - ### cloneIfPossible

    public static <T> T cloneIfPossible(T obj)
    Clones an object if possible.

    This method is similar to `clone(Object)`, but will return the provided instance as the return value instead of `null` if the instance is not cloneable. This is more convenient if the caller uses different implementations (e.g. of a service) and some of the implementations do not allow concurrent processing or have state. In such cases the implementation can simply provide a proper clone implementation and the caller's code does not have to change.

    Type Parameters:
      `T` - the type of the object
    Parameters:
      `obj` - the object to clone, null returns null
    Returns:
      the clone if the object implements `Cloneable` otherwise the object itself
    Throws:
      `CloneFailedException` - if the object is cloneable and the clone operation fails
    Since:
      3.0

  - ### compare

    public static <T extends Comparable<? super T>> int compare(T c1, T c2)
    Null safe comparison of Comparables. `null` is assumed to be less than a non-`null` value.

    TODO Move to ComparableUtils.

    Type Parameters:
      `T` - type of the values processed by this method
    Parameters:
      `c1` - the first comparable, may be null
      `c2` - the second comparable, may be null
    Returns:
      a negative value if c1 < c2, zero if c1 = c2 and a positive value if c1 > c2

  - ### compare

    public static <T extends Comparable<? super T>> int compare(T c1, T c2, boolean nullGreater)
    Null safe comparison of Comparables.

    TODO Move to ComparableUtils.

    Type Parameters:
      `T` - type of the values processed by this method
    Parameters:
      `c1` - the first comparable, may be null
      `c2` - the second comparable, may be null
      `nullGreater` - if true `null` is considered greater than a non-`null` value or if false `null` is considered less than a Non-`null` value
    Returns:
      a negative value if c1 < c2, zero if c1 = c2 and a positive value if c1 > c2
    See Also:
      - `Comparator.compare(Object, Object)`

  - ### CONST

    public static boolean CONST(boolean v)
    Returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

             public final static boolean MAGIC_FLAG = ObjectUtils.CONST(true);

    This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.
    Parameters:
      `v` - the boolean value to return
    Returns:
      the boolean v, unchanged
    Since:
      3.2

  - ### CONST

    public static byte CONST(byte v)
    Returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

             public final static byte MAGIC_BYTE = ObjectUtils.CONST((byte) 127);

    This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.
    Parameters:
      `v` - the byte value to return
    Returns:
      the byte v, unchanged
    Since:
      3.2

  - ### CONST

    public static char CONST(char v)
    Returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

             public final static char MAGIC_CHAR = ObjectUtils.CONST('a');

    This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.
    Parameters:
      `v` - the char value to return
    Returns:
      the char v, unchanged
    Since:
      3.2

  - ### CONST

    public static double CONST(double v)
    Returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

             public final static double MAGIC_DOUBLE = ObjectUtils.CONST(1.0);

    This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.
    Parameters:
      `v` - the double value to return
    Returns:
      the double v, unchanged
    Since:
      3.2

  - ### CONST

    public static float CONST(float v)
    Returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

             public final static float MAGIC_FLOAT = ObjectUtils.CONST(1.0f);

    This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.
    Parameters:
      `v` - the float value to return
    Returns:
      the float v, unchanged
    Since:
      3.2

  - ### CONST

    public static int CONST(int v)
    Returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

             public final static int MAGIC_INT = ObjectUtils.CONST(123);

    This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.
    Parameters:
      `v` - the int value to return
    Returns:
      the int v, unchanged
    Since:
      3.2

  - ### CONST

    public static long CONST(long v)
    Returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

             public final static long MAGIC_LONG = ObjectUtils.CONST(123L);

    This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.
    Parameters:
      `v` - the long value to return
    Returns:
      the long v, unchanged
    Since:
      3.2

  - ### CONST

    public static short CONST(short v)
    Returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

             public final static short MAGIC_SHORT = ObjectUtils.CONST((short) 123);

    This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.
    Parameters:
      `v` - the short value to return
    Returns:
      the short v, unchanged
    Since:
      3.2

  - ### CONST

    public static <T> T CONST(T v)
    Returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

             public final static String MAGIC_STRING = ObjectUtils.CONST("abc");

    This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.
    Type Parameters:
      `T` - the Object type
    Parameters:
      `v` - the genericized Object value to return (typically a String).
    Returns:
      the genericized Object v, unchanged (typically a String).
    Since:
      3.2

  - ### CONST_BYTE

    public static byte CONST_BYTE(int v)
    Returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

             public final static byte MAGIC_BYTE = ObjectUtils.CONST_BYTE(127);

    This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.
    Parameters:
      `v` - the byte literal (as an int) value to return
    Returns:
      the byte v, unchanged
    Throws:
      `IllegalArgumentException` - if the value passed to v is larger than a byte, that is, smaller than -128 or larger than 127.
    Since:
      3.2

  - ### CONST_SHORT

    public static short CONST_SHORT(int v)
    Returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

             public final static short MAGIC_SHORT = ObjectUtils.CONST_SHORT(127);

    This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.
    Parameters:
      `v` - the short literal (as an int) value to return
    Returns:
      the byte v, unchanged
    Throws:
      `IllegalArgumentException` - if the value passed to v is larger than a short, that is, smaller than -32768 or larger than 32767.
    Since:
      3.2

  - ### defaultIfNull

    public static <T> T defaultIfNull(T object, T defaultValue)
    Returns a default value if the object passed is `null`.

         ObjectUtils.defaultIfNull(null, null)      = null
         ObjectUtils.defaultIfNull(null, "")        = ""
         ObjectUtils.defaultIfNull(null, "zz")      = "zz"
         ObjectUtils.defaultIfNull("abc", *)        = "abc"
         ObjectUtils.defaultIfNull(Boolean.TRUE, *) = Boolean.TRUE

    Type Parameters:
      `T` - the type of the object
    Parameters:
      `object` - the `Object` to test, may be `null`
      `defaultValue` - the default value to return, may be `null`
    Returns:
      `object` if it is not `null`, defaultValue otherwise TODO Rename to getIfNull in 4.0

  - ### equals

    @Deprecated public static boolean equals(Object object1, Object object2)
    Deprecated.
    this method has been replaced by `java.util.Objects.equals(Object, Object)` in Java 7 and will be removed from future releases.
    Compares two objects for equality, where either one or both objects may be `null`.

         ObjectUtils.equals(null, null)                  = true
         ObjectUtils.equals(null, "")                    = false
         ObjectUtils.equals("", null)                    = false
         ObjectUtils.equals("", "")                      = true
         ObjectUtils.equals(Boolean.TRUE, null)          = false
         ObjectUtils.equals(Boolean.TRUE, "true")        = false
         ObjectUtils.equals(Boolean.TRUE, Boolean.TRUE)  = true
         ObjectUtils.equals(Boolean.TRUE, Boolean.FALSE) = false

    Parameters:
      `object1` - the first object, may be `null`
      `object2` - the second object, may be `null`
    Returns:
      `true` if the values of both objects are the same

  - ### firstNonNull

    @SafeVarargs public static <T> T firstNonNull(T... values)
    Returns the first value in the array which is not `null`. If all the values are `null` or the array is `null` or empty then `null` is returned.

         ObjectUtils.firstNonNull(null, null)      = null
         ObjectUtils.firstNonNull(null, "")        = ""
         ObjectUtils.firstNonNull(null, null, "")  = ""
         ObjectUtils.firstNonNull(null, "zz")      = "zz"
         ObjectUtils.firstNonNull("abc", *)        = "abc"
         ObjectUtils.firstNonNull(null, "xyz", *)  = "xyz"
         ObjectUtils.firstNonNull(Boolean.TRUE, *) = Boolean.TRUE
         ObjectUtils.firstNonNull()                = null

    Type Parameters:
      `T` - the component type of the array
    Parameters:
      `values` - the values to test, may be `null` or empty
    Returns:
      the first value from `values` which is not `null`, or `null` if there are no non-null values
    Since:
      3.0

  - ### getClass

    public static <T> Class<T> getClass(T object)
    Delegates to `Object.getClass()` using generics.
    Type Parameters:
      `T` - The argument type or null.
    Parameters:
      `object` - The argument.
    Returns:
      The argument's Class or null.
    Since:
      3.13.0

  - ### getFirstNonNull

    @SafeVarargs public static <T> T getFirstNonNull(Supplier<T>... suppliers)
    Executes the given suppliers in order and returns the first return value where a value other than `null` is returned. Once a non-`null` value is obtained, all following suppliers are not executed anymore. If all the return values are `null` or no suppliers are provided then `null` is returned.

         ObjectUtils.firstNonNullLazy(null, () -> null) = null
         ObjectUtils.firstNonNullLazy(() -> null, () -> "") = ""
         ObjectUtils.firstNonNullLazy(() -> "", () -> throw new IllegalStateException()) = ""
         ObjectUtils.firstNonNullLazy(() -> null, () -> "zz) = "zz"
         ObjectUtils.firstNonNullLazy() = null

    Type Parameters:
      `T` - the type of the return values
    Parameters:
      `suppliers` - the suppliers returning the values to test. `null` values are ignored. Suppliers may return `null` or a value of type `T`
    Returns:
      the first return value from `suppliers` which is not `null`, or `null` if there are no non-null values
    Since:
      3.10

  - ### getIfNull

    public static <T> T getIfNull(T object, Supplier<T> defaultSupplier)
    Returns the given `object` is it is non-null, otherwise returns the Supplier's `Supplier.get()` value.

    The caller responsible for thread-safety and exception handling of default value supplier.

         ObjectUtils.getIfNull(null, () -> null)     = null
         ObjectUtils.getIfNull(null, null)              = null
         ObjectUtils.getIfNull(null, () -> "")       = ""
         ObjectUtils.getIfNull(null, () -> "zz")     = "zz"
         ObjectUtils.getIfNull("abc", *)                = "abc"
         ObjectUtils.getIfNull(Boolean.TRUE, *)         = Boolean.TRUE

    Type Parameters:
      `T` - the type of the object
    Parameters:
      `object` - the `Object` to test, may be `null`
      `defaultSupplier` - the default value to return, may be `null`
    Returns:
      `object` if it is not `null`, `defaultValueSupplier.get()` otherwise
    Since:
      3.10

  - ### hashCode

    @Deprecated public static int hashCode(Object obj)
    Deprecated.
    this method has been replaced by `java.util.Objects.hashCode(Object)` in Java 7 and will be removed in future releases
    Gets the hash code of an object returning zero when the object is `null`.

         ObjectUtils.hashCode(null)   = 0
         ObjectUtils.hashCode(obj)    = obj.hashCode()

    Parameters:
      `obj` - the object to obtain the hash code of, may be `null`
    Returns:
      the hash code of the object, or zero if null
    Since:
      2.1

  - ### hashCodeHex

    public static String hashCodeHex(Object object)
    Returns the hexadecimal hash code for the given object per `Objects.hashCode(Object)`.

    Short hand for `Integer.toHexString(Objects.hashCode(object))`.

    Parameters:
      `object` - object for which the hashCode is to be calculated
    Returns:
      Hash code in hexadecimal format.
    Since:
      3.13.0

  - ### hashCodeMulti

    @Deprecated public static int hashCodeMulti(Object... objects)
    Deprecated.
    this method has been replaced by `java.util.Objects.hash(Object...)` in Java 7 and will be removed in future releases.
    Gets the hash code for multiple objects.

    This allows a hash code to be rapidly calculated for a number of objects. The hash code for a single object is the not same as `hashCode(Object)`. The hash code for multiple objects is the same as that calculated by an `ArrayList` containing the specified objects.

         ObjectUtils.hashCodeMulti()                 = 1
         ObjectUtils.hashCodeMulti((Object[]) null)  = 1
         ObjectUtils.hashCodeMulti(a)                = 31 + a.hashCode()
         ObjectUtils.hashCodeMulti(a,b)              = (31 + a.hashCode()) * 31 + b.hashCode()
         ObjectUtils.hashCodeMulti(a,b,c)            = ((31 + a.hashCode()) * 31 + b.hashCode()) * 31 + c.hashCode()

    Parameters:
      `objects` - the objects to obtain the hash code of, may be `null`
    Returns:
      the hash code of the objects, or zero if null
    Since:
      3.0

  - ### identityHashCodeHex

    public static String identityHashCodeHex(Object object)
    Returns the hexadecimal hash code for the given object per `System.identityHashCode(Object)`.

    Short hand for `Integer.toHexString(System.identityHashCode(object))`.

    Parameters:
      `object` - object for which the hashCode is to be calculated
    Returns:
      Hash code in hexadecimal format.
    Since:
      3.13.0

  - ### identityToString

    public static void identityToString(Appendable appendable, Object object) throws IOException
    Appends the toString that would be produced by `Object` if a class did not override toString itself. `null` will throw a NullPointerException for either of the two parameters.

         ObjectUtils.identityToString(appendable, "")            = appendable.append("java.lang.String@1e23")
         ObjectUtils.identityToString(appendable, Boolean.TRUE)  = appendable.append("java.lang.Boolean@7fa")
         ObjectUtils.identityToString(appendable, Boolean.TRUE)  = appendable.append("java.lang.Boolean@7fa")

    Parameters:
      `appendable` - the appendable to append to
      `object` - the object to create a toString for
    Throws:
      `IOException` - if an I/O error occurs.
    Since:
      3.2

  - ### identityToString

    public static String identityToString(Object object)
    Gets the toString that would be produced by `Object` if a class did not override toString itself. `null` will return `null`.

         ObjectUtils.identityToString(null)         = null
         ObjectUtils.identityToString("")           = "java.lang.String@1e23"
         ObjectUtils.identityToString(Boolean.TRUE) = "java.lang.Boolean@7fa"

    Parameters:
      `object` - the object to create a toString for, may be `null`
    Returns:
      the default toString text, or `null` if `null` passed in

  - ### identityToString

    @Deprecated public static void identityToString(StrBuilder builder, Object object)
    Deprecated.
    as of 3.6, because StrBuilder was moved to commons-text, use one of the other `identityToString` methods instead
    Appends the toString that would be produced by `Object` if a class did not override toString itself. `null` will throw a NullPointerException for either of the two parameters.

         ObjectUtils.identityToString(builder, "")            = builder.append("java.lang.String@1e23")
         ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa")
         ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa")

    Parameters:
      `builder` - the builder to append to
      `object` - the object to create a toString for
    Since:
      3.2

  - ### identityToString

    public static void identityToString(StringBuffer buffer, Object object)
    Appends the toString that would be produced by `Object` if a class did not override toString itself. `null` will throw a NullPointerException for either of the two parameters.

         ObjectUtils.identityToString(buf, "")            = buf.append("java.lang.String@1e23")
         ObjectUtils.identityToString(buf, Boolean.TRUE)  = buf.append("java.lang.Boolean@7fa")
         ObjectUtils.identityToString(buf, Boolean.TRUE)  = buf.append("java.lang.Boolean@7fa")

    Parameters:
      `buffer` - the buffer to append to
      `object` - the object to create a toString for
    Since:
      2.4

  - ### identityToString

    public static void identityToString(StringBuilder builder, Object object)
    Appends the toString that would be produced by `Object` if a class did not override toString itself. `null` will throw a NullPointerException for either of the two parameters.

         ObjectUtils.identityToString(builder, "")            = builder.append("java.lang.String@1e23")
         ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa")
         ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa")

    Parameters:
      `builder` - the builder to append to
      `object` - the object to create a toString for
    Since:
      3.2

  - ### isArray

    public static boolean isArray(Object object)
    Tests whether the given object is an Object array or a primitive array in a null-safe manner.

    A `null` `object` Object will return `false`.

         ObjectUtils.isArray(null)             = false
         ObjectUtils.isArray("")               = false
         ObjectUtils.isArray("ab")             = false
         ObjectUtils.isArray(new int[]{})      = true
         ObjectUtils.isArray(new int[]{1,2,3}) = true
         ObjectUtils.isArray(1234)             = false

    Parameters:
      `object` - the object to check, may be `null`
    Returns:
      `true` if the object is an `array`, `false` otherwise
    Since:
      3.13.0

  - ### isEmpty

    public static boolean isEmpty(Object object)
    Tests if an Object is empty or null. The following types are supported:
    - `CharSequence`: Considered empty if its length is zero.
    - `Array`: Considered empty if its length is zero.
    - `Collection`: Considered empty if it has zero elements.
    - `Map`: Considered empty if it has zero key-value mappings.
    - `Optional`: Considered empty if `Optional.isPresent()` returns false, regardless of the "emptiness" of the contents.

         ObjectUtils.isEmpty(null)             = true
         ObjectUtils.isEmpty("")               = true
         ObjectUtils.isEmpty("ab")             = false
         ObjectUtils.isEmpty(new int[]{})      = true
         ObjectUtils.isEmpty(new int[]{1,2,3}) = false
         ObjectUtils.isEmpty(1234)             = false
         ObjectUtils.isEmpty(1234)             = false
         ObjectUtils.isEmpty(Optional.of(""))  = false
         ObjectUtils.isEmpty(Optional.empty()) = true

    Parameters:
      `object` - the `Object` to test, may be `null`
    Returns:
      `true` if the object has a supported type and is empty or null, `false` otherwise
    Since:
      3.9

  - ### isNotEmpty

    public static boolean isNotEmpty(Object object)
    Tests if an Object is not empty and not null. The following types are supported:
    - `CharSequence`: Considered empty if its length is zero.
    - `Array`: Considered empty if its length is zero.
    - `Collection`: Considered empty if it has zero elements.
    - `Map`: Considered empty if it has zero key-value mappings.
    - `Optional`: Considered empty if `Optional.isPresent()` returns false, regardless of the "emptiness" of the contents.

         ObjectUtils.isNotEmpty(null)             = false
         ObjectUtils.isNotEmpty("")               = false
         ObjectUtils.isNotEmpty("ab")             = true
         ObjectUtils.isNotEmpty(new int[]{})      = false
         ObjectUtils.isNotEmpty(new int[]{1,2,3}) = true
         ObjectUtils.isNotEmpty(1234)             = true
         ObjectUtils.isNotEmpty(Optional.of(""))  = true
         ObjectUtils.isNotEmpty(Optional.empty()) = false

    Parameters:
      `object` - the `Object` to test, may be `null`
    Returns:
      `true` if the object has an unsupported type or is not empty and not null, `false` otherwise
    Since:
      3.9

  - ### max

    @SafeVarargs public static <T extends Comparable<? super T>> T max(T... values)
    Null safe comparison of Comparables.

    TODO Move to ComparableUtils.

    Type Parameters:
      `T` - type of the values processed by this method
    Parameters:
      `values` - the set of comparable values, may be null
    Returns:
      - If any objects are non-null and unequal, the greater object.
      - If all objects are non-null and equal, the first.
      - If any of the comparables are null, the greater of the non-null objects.
      - If all the comparables are null, null is returned.

  - ### median

    @SafeVarargs public static <T> T median(Comparator<T> comparator, T... items)
    Find the "best guess" middle value among comparables. If there is an even number of total values, the lower of the two middle values will be returned.
    Type Parameters:
      `T` - type of values processed by this method
    Parameters:
      `comparator` - to use for comparisons
      `items` - to compare
    Returns:
      T at middle position
    Throws:
      `NullPointerException` - if items or comparator is `null`
      `IllegalArgumentException` - if items is empty or contains `null` values
    Since:
      3.0.1

  - ### median

    @SafeVarargs public static <T extends Comparable<? super T>> T median(T... items)
    Find the "best guess" middle value among comparables. If there is an even number of total values, the lower of the two middle values will be returned.
    Type Parameters:
      `T` - type of values processed by this method
    Parameters:
      `items` - to compare
    Returns:
      T at middle position
    Throws:
      `NullPointerException` - if items is `null`
      `IllegalArgumentException` - if items is empty or contains `null` values
    Since:
      3.0.1

  - ### min

    @SafeVarargs public static <T extends Comparable<? super T>> T min(T... values)
    Null safe comparison of Comparables.

    TODO Move to ComparableUtils.

    Type Parameters:
      `T` - type of the values processed by this method
    Parameters:
      `values` - the set of comparable values, may be null
    Returns:
      - If any objects are non-null and unequal, the lesser object.
      - If all objects are non-null and equal, the first.
      - If any of the comparables are null, the lesser of the non-null objects.
      - If all the comparables are null, null is returned.

  - ### mode

    @SafeVarargs public static <T> T mode(T... items)
    Find the most frequently occurring item.
    Type Parameters:
      `T` - type of values processed by this method
    Parameters:
      `items` - to check
    Returns:
      most populous T, `null` if non-unique or no items supplied
    Since:
      3.0.1

  - ### notEqual

    public static boolean notEqual(Object object1, Object object2)
    Compares two objects for inequality, where either one or both objects may be `null`.

         ObjectUtils.notEqual(null, null)                  = false
         ObjectUtils.notEqual(null, "")                    = true
         ObjectUtils.notEqual("", null)                    = true
         ObjectUtils.notEqual("", "")                      = false
         ObjectUtils.notEqual(Boolean.TRUE, null)          = true
         ObjectUtils.notEqual(Boolean.TRUE, "true")        = true
         ObjectUtils.notEqual(Boolean.TRUE, Boolean.TRUE)  = false
         ObjectUtils.notEqual(Boolean.TRUE, Boolean.FALSE) = true

    Parameters:
      `object1` - the first object, may be `null`
      `object2` - the second object, may be `null`
    Returns:
      `false` if the values of both objects are the same

  - ### requireNonEmpty

    public static <T> T requireNonEmpty(T obj)
    Checks that the specified object reference is not `null` or empty per `isEmpty(Object)`. Use this method for validation, for example:

    >      public Foo(Bar bar) {
    >          this.bar = Objects.requireNonEmpty(bar);
    >      }

    Type Parameters:
      `T` - the type of the reference.
    Parameters:
      `obj` - the object reference to check for nullity.
    Returns:
      `obj` if not `null`.
    Throws:
      `NullPointerException` - if `obj` is `null`.
      `IllegalArgumentException` - if `obj` is empty per `isEmpty(Object)`.
    Since:
      3.12.0
    See Also:
      - `isEmpty(Object)`

  - ### requireNonEmpty

    public static <T> T requireNonEmpty(T obj, String message)
    Checks that the specified object reference is not `null` or empty per `isEmpty(Object)`. Use this method for validation, for example:

    >      public Foo(Bar bar) {
    >          this.bar = Objects.requireNonEmpty(bar, "bar");
    >      }

    Type Parameters:
      `T` - the type of the reference.
    Parameters:
      `obj` - the object reference to check for nullity.
      `message` - the exception message.
    Returns:
      `obj` if not `null`.
    Throws:
      `NullPointerException` - if `obj` is `null`.
      `IllegalArgumentException` - if `obj` is empty per `isEmpty(Object)`.
    Since:
      3.12.0
    See Also:
      - `isEmpty(Object)`

  - ### toString

    @Deprecated public static String toString(Object obj)
    Deprecated.
    this method has been replaced by `java.util.Objects.toString(Object)` in Java 7 and will be removed in future releases. Note however that said method will return "null" for null references, while this method returns an empty String. To preserve behavior use `java.util.Objects.toString(myObject, "")`
    Gets the `toString` of an `Object` returning an empty string ("") if `null` input.

         ObjectUtils.toString(null)         = ""
         ObjectUtils.toString("")           = ""
         ObjectUtils.toString("bat")        = "bat"
         ObjectUtils.toString(Boolean.TRUE) = "true"

    Parameters:
      `obj` - the Object to `toString`, may be null
    Returns:
      the passed in Object's toString, or `""` if `null` input
    Since:
      2.0
    See Also:
      - `Objects.toString(Object)`
      - `Objects.toString(Object, String)`
      - `StringUtils.defaultString(String)`
      - `String.valueOf(Object)`

  - ### toString

    @Deprecated public static String toString(Object obj, String nullStr)
    Deprecated.
    this method has been replaced by `java.util.Objects.toString(Object, String)` in Java 7 and will be removed in future releases.
    Gets the `toString` of an `Object` returning a specified text if `null` input.

         ObjectUtils.toString(null, null)           = null
         ObjectUtils.toString(null, "null")         = "null"
         ObjectUtils.toString("", "null")           = ""
         ObjectUtils.toString("bat", "null")        = "bat"
         ObjectUtils.toString(Boolean.TRUE, "null") = "true"

    Parameters:
      `obj` - the Object to `toString`, may be null
      `nullStr` - the String to return if `null` input, may be null
    Returns:
      the passed in Object's toString, or `nullStr` if `null` input
    Since:
      2.0
    See Also:
      - `Objects.toString(Object)`
      - `Objects.toString(Object, String)`
      - `StringUtils.defaultString(String,String)`
      - `String.valueOf(Object)`

  - ### toString

    public static String toString(Supplier<Object> obj, Supplier<String> supplier)
    Gets the `toString` of an `Supplier`'s `Supplier.get()` returning a specified text if `null` input.

         ObjectUtils.toString(() -> obj, () -> expensive())

         ObjectUtils.toString(() -> null, () -> expensive())         = result of expensive()
         ObjectUtils.toString(() -> null, () -> expensive())         = result of expensive()
         ObjectUtils.toString(() -> "", () -> expensive())           = ""
         ObjectUtils.toString(() -> "bat", () -> expensive())        = "bat"
         ObjectUtils.toString(() -> Boolean.TRUE, () -> expensive()) = "true"

    Parameters:
      `obj` - the Object to `toString`, may be null
      `supplier` - the Supplier of String used on `null` input, may be null
    Returns:
      the passed in Object's toString, or `nullStr` if `null` input
    Since:
      3.14.0

  - ### toString

    public static <T> String toString(T obj, Supplier<String> supplier)
    Gets the `toString` of an `Object` returning a specified text if `null` input.

         ObjectUtils.toString(obj, () -> expensive())

         ObjectUtils.toString(null, () -> expensive())         = result of expensive()
         ObjectUtils.toString(null, () -> expensive())         = result of expensive()
         ObjectUtils.toString("", () -> expensive())           = ""
         ObjectUtils.toString("bat", () -> expensive())        = "bat"
         ObjectUtils.toString(Boolean.TRUE, () -> expensive()) = "true"

    Type Parameters:
      `T` - the obj type (used to provide better source compatibility in 3.14.0).
    Parameters:
      `obj` - the Object to `toString`, may be null
      `supplier` - the Supplier of String used on `null` input, may be null
    Returns:
      the passed in Object's toString, or `nullStr` if `null` input
    Since:
      3.11

  - ### wait

    public static void wait(Object obj, Duration duration) throws InterruptedException
    Calls `Object.wait(long, int)` for the given Duration.
    Parameters:
      `obj` - The receiver of the wait call.
      `duration` - How long to wait.
    Throws:
      `IllegalArgumentException` - if the timeout duration is negative.
      `IllegalMonitorStateException` - if the current thread is not the owner of the `obj`'s monitor.
      `InterruptedException` - if any thread interrupted the current thread before or while the current thread was waiting for a notification. The interrupted status of the current thread is cleared when this exception is thrown.
    Since:
      3.12.0
    See Also:
      - `Object.wait(long, int)`