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 and Description
    --- | ---
    `static class` | `ObjectUtils.Null` Class used as a null placeholder where `null` has another meaning.

  - ### Field Summary

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

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ObjectUtils()` `ObjectUtils` instances should NOT be constructed in standard programming.

  - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static boolean` | `allNotNull(Object... values)` Checks if all values in the array are not `nulls`.
    `static boolean` | `allNull(Object... values)` Checks if all values in the given array are `null`.
    `static boolean` | `anyNotNull(Object... values)` Checks if any value in the given array is not `null`.
    `static boolean` | `anyNull(Object... values)` Checks if any value in the given array is `null`.
    `static <T> T` | `clone(T obj)` Clone an object.
    `static <T> T` | `cloneIfPossible(T obj)` Clone 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 byte` | `CONST_BYTE(int v)` This method returns the provided value unchanged.
    `static short` | `CONST_SHORT(int v)` This method returns the provided value unchanged.
    `static boolean` | `CONST(boolean v)` This method returns the provided value unchanged.
    `static byte` | `CONST(byte v)` This method returns the provided value unchanged.
    `static char` | `CONST(char v)` This method returns the provided value unchanged.
    `static double` | `CONST(double v)` This method returns the provided value unchanged.
    `static float` | `CONST(float v)` This method returns the provided value unchanged.
    `static int` | `CONST(int v)` This method returns the provided value unchanged.
    `static long` | `CONST(long v)` This method returns the provided value unchanged.
    `static short` | `CONST(short v)` This method returns the provided value unchanged.
    `static <T> T` | `CONST(T v)` This method 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 hex 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 hex 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(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 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 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. 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, "")`
    `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(Object 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 Detail

    - #### 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 Detail

    - #### ObjectUtils

          public ObjectUtils()

      `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 Detail

    - #### allNotNull

          public static boolean allNotNull(Object... values)

      Checks 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)

      Checks 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)

      Checks 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)

      Checks 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)

      Clone 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)

      Clone 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)

      This method 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)

      This method 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)

      This method 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)

      This method 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)

      This method 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)

      This method 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)

      This method 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)

      This method 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)

      This method 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)

      This method 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)

      This method 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 @{code 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 hex 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 hex 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:
        `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:
        `StringUtils.defaultString(String,String)`, `String.valueOf(Object)`

    - #### toString

          public static String toString(Object 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"

      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)`

Copyright © 2001–2023 The Apache Software Foundation. All rights reserved.