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

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 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(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 Details

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

### 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 invalid input: '<' 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 invalid input: '<' 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