Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 behaviour in more detail.

#ThreadSafe#

Since:
  1.0
Version:
  $Id: ObjectUtils.java 960138 2010-07-03 00:30:46Z joehni $
Author:
  Apache Software Foundation, Nissim Karpenstein, Janek Bogucki, Daniel L. Rall, Gary Gregory, Mario Winterer, David J. M. Karlsen

Nested Class Summary
`static class` | `ObjectUtils.Null` Class used as a null placeholder where `null` has another meaning.

Field Summary
`static ObjectUtils.Null` | `NULL` Singleton used as a `null` placeholder where `null` has another meaning.

Constructor Summary
`ObjectUtils()` `ObjectUtils` instances should NOT be constructed in standard programming.

Method Summary
`static
`<T> T`
` | `clone(T o)` Clone an object.
`static
`<T> T`
` | `cloneIfPossible(T o)` Clone an object if possible.
`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
`<T> T`
` | `firstNonNull(T... values)` Returns the first value in the array which is not `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
`<T extends Comparable<? super T>> T`
` | `max(T c1, T c2)` Null safe comparison of Comparables.
`static
`<T extends Comparable<? super T>> T`
` | `min(T c1, T c2)` Null safe comparison of Comparables.
`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

### firstNonNull

    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

  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

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

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

### 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 <T extends Comparable<? super T>> T min(T c1,
                                                          T 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 <T extends Comparable<? super T>> T max(T c1,
                                                          T 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.

### clone

    public static <T> T clone(T o)

  Clone an object.

  Type Parameters:
    `T` - the type of the 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:
    3.0

### cloneIfPossible

    public static <T> T cloneIfPossible(T 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.

  Type Parameters:
    `T` - the type of the object
  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:
    3.0

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2010 The Apache Software Foundation. All Rights Reserved.