org.apache.commons.lang3
Class ObjectUtils

java.lang.Object
  extended by 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 1153350 2011-08-03 05:29:21Z bayard $

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 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
<T> T
defaultIfNull(T object, T 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 int hashCodeMulti(Object... objects)
          Gets the hash code for multiple objects.
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... 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 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 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

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

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
 

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

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

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

hashCodeMulti

public static int hashCodeMulti(Object... objects)

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

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... values)

Null safe comparison of Comparables.

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.

max

public static <T extends Comparable<? super T>> T max(T... values)

Null safe comparison of Comparables.

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.

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.

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.

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)

median

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

median

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

mode

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

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


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