Package org.apache.commons.lang

## Class ObjectUtils

- java.lang.Object
- - org.apache.commons.lang.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 behaviour in more detail.

  #ThreadSafe#

  Since:
    1.0
  Version:
    $Id: ObjectUtils.java 1057434 2011-01-11 01:27:37Z niallp $

- - ### 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 ObjectUtils.Null` | `NULL` | Singleton used as a `null` placeholder where `null` has another meaning.

  - ### Constructor Summary

    Constructors
    Constructor | 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 | Description
    --- | --- | ---
    `static StringBuffer` | `appendIdentityToString​(StringBuffer buffer, Object object)` | Deprecated. The design of this method is bad - see LANG-360.
    `static Object` | `clone​(Object o)` | Clone an object.
    `static Object` | `cloneIfPossible​(Object o)` | Clone an object if possible.
    `static int` | `compare​(Comparable c1, Comparable c2)` | Null safe comparison of Comparables.
    `static int` | `compare​(Comparable c1, Comparable c2, boolean nullGreater)` | Null safe comparison of Comparables.
    `static Object` | `defaultIfNull​(Object object, Object defaultValue)` | Returns a default value if the object passed is `null`.
    `static boolean` | `equals​(Object object1, Object object2)` | Compares two objects for equality, where either one or both objects may be `null`.
    `static int` | `hashCode​(Object obj)` | Gets the hash code of an object returning zero when the object is `null`.
    `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 Object` | `max​(Comparable c1, Comparable c2)` | Null safe comparison of Comparables.
    `static Object` | `min​(Comparable c1, Comparable c2)` | Null safe comparison of Comparables.
    `static boolean` | `notEqual​(Object object1, Object object2)` | Compares two objects for inequality, where either one or both objects may be `null`.
    `static String` | `toString​(Object obj)` | Gets the `toString` of an `Object` returning an empty string ("") if `null` input.
    `static String` | `toString​(Object obj, String nullStr)` | Gets the `toString` of an `Object` returning a specified text if `null` input.

    - ### 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(java.lang.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 class should be used as `ObjectUtils.defaultIfNull("a","b");`.

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

  - ### Method Detail

    - #### defaultIfNull

          public static Object defaultIfNull​(Object object,
                                             Object 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

      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

    - #### equals

          public static boolean equals​(Object object1,
                                       Object object2)

      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

    - #### 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
      Since:
        2.6

    - #### hashCode

          public static int hashCode​(Object obj)

      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

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

          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

    - #### appendIdentityToString

          public static StringBuffer appendIdentityToString​(StringBuffer buffer,
                                                            Object object)

      Deprecated.
      The design of this method is bad - see LANG-360. Instead, use identityToString(StringBuffer, Object).

      Appends the toString that would be produced by `Object` if a class did not override toString itself. `null` will return `null`.

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

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

    - #### toString

          public static String toString​(Object obj)

      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 nullStr if `null` input
      Since:
        2.0
      See Also:
        `StringUtils.defaultString(String)`, `String.valueOf(Object)`

    - #### toString

          public static String toString​(Object obj,
                                        String nullStr)

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

    - #### min

          public static Object min​(Comparable c1,
                                   Comparable c2)

      Null safe comparison of Comparables.
      Parameters:
        `c1` - the first comparable, may be null
        `c2` - the second comparable, may be null
      Returns:
        - If both objects are non-null and unequal, the lesser object.
        - If both objects are non-null and equal, c1.
        - If one of the comparables is null, the non-null object.
        - If both the comparables are null, null is returned.

    - #### max

          public static Object max​(Comparable c1,
                                   Comparable c2)

      Null safe comparison of Comparables.
      Parameters:
        `c1` - the first comparable, may be null
        `c2` - the second comparable, may be null
      Returns:
        - If both objects are non-null and unequal, the greater object.
        - If both objects are non-null and equal, c1.
        - If one of the comparables is null, the non-null object.
        - If both the comparables are null, null is returned.

    - #### compare

          public static int compare​(Comparable c1,
                                    Comparable c2)

      Null safe comparison of Comparables. `null` is assumed to be less than a non-`null` value.
      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
      Since:
        2.6

    - #### compare

          public static int compare​(Comparable c1,
                                    Comparable c2,
                                    boolean nullGreater)

      Null safe comparison of Comparables.
      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
      Since:
        2.6
      See Also:
        `Comparator.compare(Object, Object)`

    - #### clone

          public static Object clone​(Object o)

      Clone an object.
      Parameters:
        `o` - the object to clone
      Returns:
        the clone if the object implements `Cloneable` otherwise `null`
      Throws:
        `CloneFailedException` - if the object is cloneable and the clone operation fails
      Since:
        2.6

    - #### cloneIfPossible

          public static Object cloneIfPossible​(Object o)

      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.
      Parameters:
        `o` - the object to clone
      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:
        2.6