ObjectUtils (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.util

## Class ObjectUtils

- java.lang.Object
- - org.springframework.util.ObjectUtils

-     public abstract class ObjectUtils
      extends Object

  Miscellaneous object utility methods.

  Mainly for internal use within the framework; consider Jakarta's Commons Lang for a more comprehensive suite of object utilities.

  Thanks to Alex Ruiz for contributing several enhancements to this class!

  Since:
    19.03.2004
  Author:
    Juergen Hoeller, Keith Donald, Rod Johnson, Rob Harrop, Chris Beams
  See Also:
    `ObjectUtils`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ObjectUtils()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <A,O extends A> A[]` | `addObjectToArray(A[] array, O obj)` Append the given object to the given array, returning a new array consisting of the input array contents plus the given object.
    `static <E extends Enum<?>> E` | `caseInsensitiveValueOf(E[] enumValues, String constant)` Case insensitive alternative to `Enum.valueOf(Class, String)`.
    `static boolean` | `containsConstant(Enum<?>[] enumValues, String constant)` Check whether the given array of enum constants contains a constant with the given name, ignoring case when determining a match.
    `static boolean` | `containsConstant(Enum<?>[] enumValues, String constant, boolean caseSensitive)` Check whether the given array of enum constants contains a constant with the given name.
    `static boolean` | `containsElement(Object[] array, Object element)` Check whether the given array contains the given element.
    `static String` | `getDisplayString(Object obj)` Return a content-based String representation if `obj` is not `null`; otherwise returns an empty String.
    `static String` | `getIdentityHexString(Object obj)` Return a hex String form of an object's identity hash code.
    `static int` | `hashCode(boolean bool)` Return the same value as `{@link Boolean#hashCode()}`.
    `static int` | `hashCode(double dbl)` Return the same value as `{@link Double#hashCode()}`.
    `static int` | `hashCode(float flt)` Return the same value as `{@link Float#hashCode()}`.
    `static int` | `hashCode(long lng)` Return the same value as `{@link Long#hashCode()}`.
    `static String` | `identityToString(Object obj)` Return a String representation of an object's overall identity.
    `static boolean` | `isArray(Object obj)` Determine whether the given object is an array: either an Object array or a primitive array.
    `static boolean` | `isCheckedException(Throwable ex)` Return whether the given throwable is a checked exception: that is, neither a RuntimeException nor an Error.
    `static boolean` | `isCompatibleWithThrowsClause(Throwable ex, Class[] declaredExceptions)` Check whether the given exception is compatible with the exceptions declared in a throws clause.
    `static boolean` | `isEmpty(Object[] array)` Determine whether the given array is empty: i.e.
    `static String` | `nullSafeClassName(Object obj)` Determine the class name for the given object.
    `static boolean` | `nullSafeEquals(Object o1, Object o2)` Determine if the given objects are equal, returning `true` if both are `null` or `false` if only one is `null`.
    `static int` | `nullSafeHashCode(boolean[] array)` Return a hash code based on the contents of the specified array.
    `static int` | `nullSafeHashCode(byte[] array)` Return a hash code based on the contents of the specified array.
    `static int` | `nullSafeHashCode(char[] array)` Return a hash code based on the contents of the specified array.
    `static int` | `nullSafeHashCode(double[] array)` Return a hash code based on the contents of the specified array.
    `static int` | `nullSafeHashCode(float[] array)` Return a hash code based on the contents of the specified array.
    `static int` | `nullSafeHashCode(int[] array)` Return a hash code based on the contents of the specified array.
    `static int` | `nullSafeHashCode(long[] array)` Return a hash code based on the contents of the specified array.
    `static int` | `nullSafeHashCode(Object obj)` Return as hash code for the given object; typically the value of `{@link Object#hashCode()}`.
    `static int` | `nullSafeHashCode(Object[] array)` Return a hash code based on the contents of the specified array.
    `static int` | `nullSafeHashCode(short[] array)` Return a hash code based on the contents of the specified array.
    `static String` | `nullSafeToString(boolean[] array)` Return a String representation of the contents of the specified array.
    `static String` | `nullSafeToString(byte[] array)` Return a String representation of the contents of the specified array.
    `static String` | `nullSafeToString(char[] array)` Return a String representation of the contents of the specified array.
    `static String` | `nullSafeToString(double[] array)` Return a String representation of the contents of the specified array.
    `static String` | `nullSafeToString(float[] array)` Return a String representation of the contents of the specified array.
    `static String` | `nullSafeToString(int[] array)` Return a String representation of the contents of the specified array.
    `static String` | `nullSafeToString(long[] array)` Return a String representation of the contents of the specified array.
    `static String` | `nullSafeToString(Object obj)` Return a String representation of the specified Object.
    `static String` | `nullSafeToString(Object[] array)` Return a String representation of the contents of the specified array.
    `static String` | `nullSafeToString(short[] array)` Return a String representation of the contents of the specified array.
    `static Object[]` | `toObjectArray(Object source)` Convert the given array (which may be a primitive array) to an object array (if necessary of primitive wrapper objects).

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

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

- - ### Constructor Detail

    - #### ObjectUtils

          public ObjectUtils()

  - ### Method Detail

    - #### isCheckedException

          public static boolean isCheckedException(Throwable ex)

      Return whether the given throwable is a checked exception: that is, neither a RuntimeException nor an Error.
      Parameters:
        `ex` - the throwable to check
      Returns:
        whether the throwable is a checked exception
      See Also:
        `Exception`, `RuntimeException`, `Error`

    - #### isCompatibleWithThrowsClause

          public static boolean isCompatibleWithThrowsClause(Throwable ex,
                                             Class[] declaredExceptions)

      Check whether the given exception is compatible with the exceptions declared in a throws clause.
      Parameters:
        `ex` - the exception to checked
        `declaredExceptions` - the exceptions declared in the throws clause
      Returns:
        whether the given exception is compatible

    - #### isArray

          public static boolean isArray(Object obj)

      Determine whether the given object is an array: either an Object array or a primitive array.
      Parameters:
        `obj` - the object to check

    - #### isEmpty

          public static boolean isEmpty(Object[] array)

      Determine whether the given array is empty: i.e. `null` or of zero length.
      Parameters:
        `array` - the array to check

    - #### containsElement

          public static boolean containsElement(Object[] array,
                                Object element)

      Check whether the given array contains the given element.
      Parameters:
        `array` - the array to check (may be `null`, in which case the return value will always be `false`)
        `element` - the element to check for
      Returns:
        whether the element has been found in the given array

    - #### containsConstant

          public static boolean containsConstant(Enum<?>[] enumValues,
                                 String constant)

      Check whether the given array of enum constants contains a constant with the given name, ignoring case when determining a match.
      Parameters:
        `enumValues` - the enum values to check, typically the product of a call to MyEnum.values()
        `constant` - the constant name to find (must not be null or empty string)
      Returns:
        whether the constant has been found in the given array

    - #### containsConstant

          public static boolean containsConstant(Enum<?>[] enumValues,
                                 String constant,
                                 boolean caseSensitive)

      Check whether the given array of enum constants contains a constant with the given name.
      Parameters:
        `enumValues` - the enum values to check, typically the product of a call to MyEnum.values()
        `constant` - the constant name to find (must not be null or empty string)
        `caseSensitive` - whether case is significant in determining a match
      Returns:
        whether the constant has been found in the given array

    - #### caseInsensitiveValueOf

          public static <E extends Enum<?>> E caseInsensitiveValueOf(E[] enumValues,
                                                     String constant)

      Case insensitive alternative to `Enum.valueOf(Class, String)`.
      Type Parameters:
        `E` - the concrete Enum type
      Parameters:
        `enumValues` - the array of all Enum constants in question, usually per Enum.values()
        `constant` - the constant to get the enum value of
      Throws:
        `IllegalArgumentException` - if the given constant is not found in the given array of enum values. Use `containsConstant(Enum[], String)` as a guard to avoid this exception.

    - #### addObjectToArray

          public static <A,O extends A> A[] addObjectToArray(A[] array,
                                             O obj)

      Append the given object to the given array, returning a new array consisting of the input array contents plus the given object.
      Parameters:
        `array` - the array to append to (can be `null`)
        `obj` - the object to append
      Returns:
        the new array (of the same component type; never `null`)

    - #### toObjectArray

          public static Object[] toObjectArray(Object source)

      Convert the given array (which may be a primitive array) to an object array (if necessary of primitive wrapper objects).

      A `null` source value will be converted to an empty Object array.

      Parameters:
        `source` - the (potentially primitive) array
      Returns:
        the corresponding object array (never `null`)
      Throws:
        `IllegalArgumentException` - if the parameter is not an array

    - #### nullSafeEquals

          public static boolean nullSafeEquals(Object o1,
                               Object o2)

      Determine if the given objects are equal, returning `true` if both are `null` or `false` if only one is `null`.

      Compares arrays with `Arrays.equals`, performing an equality check based on the array elements rather than the array reference.

      Parameters:
        `o1` - first Object to compare
        `o2` - second Object to compare
      Returns:
        whether the given objects are equal
      See Also:
        `Arrays.equals(long[], long[])`

    - #### nullSafeHashCode

          public static int nullSafeHashCode(Object obj)

      Return as hash code for the given object; typically the value of `{@link Object#hashCode()}`. If the object is an array, this method will delegate to any of the `nullSafeHashCode` methods for arrays in this class. If the object is `null`, this method returns 0.
      See Also:
        `nullSafeHashCode(Object[])`, `nullSafeHashCode(boolean[])`, `nullSafeHashCode(byte[])`, `nullSafeHashCode(char[])`, `nullSafeHashCode(double[])`, `nullSafeHashCode(float[])`, `nullSafeHashCode(int[])`, `nullSafeHashCode(long[])`, `nullSafeHashCode(short[])`

    - #### nullSafeHashCode

          public static int nullSafeHashCode(Object[] array)

      Return a hash code based on the contents of the specified array. If `array` is `null`, this method returns 0.

    - #### nullSafeHashCode

          public static int nullSafeHashCode(boolean[] array)

      Return a hash code based on the contents of the specified array. If `array` is `null`, this method returns 0.

    - #### nullSafeHashCode

          public static int nullSafeHashCode(byte[] array)

      Return a hash code based on the contents of the specified array. If `array` is `null`, this method returns 0.

    - #### nullSafeHashCode

          public static int nullSafeHashCode(char[] array)

      Return a hash code based on the contents of the specified array. If `array` is `null`, this method returns 0.

    - #### nullSafeHashCode

          public static int nullSafeHashCode(double[] array)

      Return a hash code based on the contents of the specified array. If `array` is `null`, this method returns 0.

    - #### nullSafeHashCode

          public static int nullSafeHashCode(float[] array)

      Return a hash code based on the contents of the specified array. If `array` is `null`, this method returns 0.

    - #### nullSafeHashCode

          public static int nullSafeHashCode(int[] array)

      Return a hash code based on the contents of the specified array. If `array` is `null`, this method returns 0.

    - #### nullSafeHashCode

          public static int nullSafeHashCode(long[] array)

      Return a hash code based on the contents of the specified array. If `array` is `null`, this method returns 0.

    - #### nullSafeHashCode

          public static int nullSafeHashCode(short[] array)

      Return a hash code based on the contents of the specified array. If `array` is `null`, this method returns 0.

    - #### hashCode

          public static int hashCode(boolean bool)

      Return the same value as `{@link Boolean#hashCode()}`.
      See Also:
        `Boolean.hashCode()`

    - #### hashCode

          public static int hashCode(double dbl)

      Return the same value as `{@link Double#hashCode()}`.
      See Also:
        `Double.hashCode()`

    - #### hashCode

          public static int hashCode(float flt)

      Return the same value as `{@link Float#hashCode()}`.
      See Also:
        `Float.hashCode()`

    - #### hashCode

          public static int hashCode(long lng)

      Return the same value as `{@link Long#hashCode()}`.
      See Also:
        `Long.hashCode()`

    - #### identityToString

          public static String identityToString(Object obj)

      Return a String representation of an object's overall identity.
      Parameters:
        `obj` - the object (may be `null`)
      Returns:
        the object's identity as String representation, or an empty String if the object was `null`

    - #### getIdentityHexString

          public static String getIdentityHexString(Object obj)

      Return a hex String form of an object's identity hash code.
      Parameters:
        `obj` - the object
      Returns:
        the object's identity code in hex notation

    - #### getDisplayString

          public static String getDisplayString(Object obj)

      Return a content-based String representation if `obj` is not `null`; otherwise returns an empty String.

      Differs from `nullSafeToString(Object)` in that it returns an empty String rather than "null" for a `null` value.

      Parameters:
        `obj` - the object to build a display String for
      Returns:
        a display String representation of `obj`
      See Also:
        `nullSafeToString(Object)`

    - #### nullSafeClassName

          public static String nullSafeClassName(Object obj)

      Determine the class name for the given object.

      Returns `"null"` if `obj` is `null`.

      Parameters:
        `obj` - the object to introspect (may be `null`)
      Returns:
        the corresponding class name

    - #### nullSafeToString

          public static String nullSafeToString(Object obj)

      Return a String representation of the specified Object.

      Builds a String representation of the contents in case of an array. Returns `"null"` if `obj` is `null`.

      Parameters:
        `obj` - the object to build a String representation for
      Returns:
        a String representation of `obj`

    - #### nullSafeToString

          public static String nullSafeToString(Object[] array)

      Return a String representation of the contents of the specified array.

      The String representation consists of a list of the array's elements, enclosed in curly braces (`"{}"`). Adjacent elements are separated by the characters `", "` (a comma followed by a space). Returns `"null"` if `array` is `null`.

      Parameters:
        `array` - the array to build a String representation for
      Returns:
        a String representation of `array`

    - #### nullSafeToString

          public static String nullSafeToString(boolean[] array)

      Return a String representation of the contents of the specified array.

      The String representation consists of a list of the array's elements, enclosed in curly braces (`"{}"`). Adjacent elements are separated by the characters `", "` (a comma followed by a space). Returns `"null"` if `array` is `null`.

      Parameters:
        `array` - the array to build a String representation for
      Returns:
        a String representation of `array`

    - #### nullSafeToString

          public static String nullSafeToString(byte[] array)

      Return a String representation of the contents of the specified array.

      The String representation consists of a list of the array's elements, enclosed in curly braces (`"{}"`). Adjacent elements are separated by the characters `", "` (a comma followed by a space). Returns `"null"` if `array` is `null`.

      Parameters:
        `array` - the array to build a String representation for
      Returns:
        a String representation of `array`

    - #### nullSafeToString

          public static String nullSafeToString(char[] array)

      Return a String representation of the contents of the specified array.

      The String representation consists of a list of the array's elements, enclosed in curly braces (`"{}"`). Adjacent elements are separated by the characters `", "` (a comma followed by a space). Returns `"null"` if `array` is `null`.

      Parameters:
        `array` - the array to build a String representation for
      Returns:
        a String representation of `array`

    - #### nullSafeToString

          public static String nullSafeToString(double[] array)

      Return a String representation of the contents of the specified array.

      The String representation consists of a list of the array's elements, enclosed in curly braces (`"{}"`). Adjacent elements are separated by the characters `", "` (a comma followed by a space). Returns `"null"` if `array` is `null`.

      Parameters:
        `array` - the array to build a String representation for
      Returns:
        a String representation of `array`

    - #### nullSafeToString

          public static String nullSafeToString(float[] array)

      Return a String representation of the contents of the specified array.

      The String representation consists of a list of the array's elements, enclosed in curly braces (`"{}"`). Adjacent elements are separated by the characters `", "` (a comma followed by a space). Returns `"null"` if `array` is `null`.

      Parameters:
        `array` - the array to build a String representation for
      Returns:
        a String representation of `array`

    - #### nullSafeToString

          public static String nullSafeToString(int[] array)

      Return a String representation of the contents of the specified array.

      The String representation consists of a list of the array's elements, enclosed in curly braces (`"{}"`). Adjacent elements are separated by the characters `", "` (a comma followed by a space). Returns `"null"` if `array` is `null`.

      Parameters:
        `array` - the array to build a String representation for
      Returns:
        a String representation of `array`

    - #### nullSafeToString

          public static String nullSafeToString(long[] array)

      Return a String representation of the contents of the specified array.

      The String representation consists of a list of the array's elements, enclosed in curly braces (`"{}"`). Adjacent elements are separated by the characters `", "` (a comma followed by a space). Returns `"null"` if `array` is `null`.

      Parameters:
        `array` - the array to build a String representation for
      Returns:
        a String representation of `array`

    - #### nullSafeToString

          public static String nullSafeToString(short[] array)

      Return a String representation of the contents of the specified array.

      The String representation consists of a list of the array's elements, enclosed in curly braces (`"{}"`). Adjacent elements are separated by the characters `", "` (a comma followed by a space). Returns `"null"` if `array` is `null`.

      Parameters:
        `array` - the array to build a String representation for
      Returns:
        a String representation of `array`