org.apache.commons.lang

Class 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.

Since: 1.0

Version: $Id: ObjectUtils.java 594336 2007-11-12 22:54:02Z bayard $

Author: Nissim Karpenstein Janek Bogucki Daniel L. Rall Stephen Colebourne Gary Gregory Mario Winterer David J. M. Karlsen

Nested Class Summary
static classObjectUtils.Null

Class used as a null placeholder where null has another meaning.

For example, in a HashMap the java.util.HashMap#get(java.lang.Object) method returns null if the Map contains null or if there is no matching key.

Field Summary
static ObjectUtils.NullNULL

Singleton used as a null placeholder where null has another meaning.

For example, in a HashMap the java.util.HashMap#get(java.lang.Object) method returns null if the Map contains null or if there is no matching key.

Constructor Summary
ObjectUtils()

ObjectUtils instances should NOT be constructed in standard programming.

Method Summary
static StringBufferappendIdentityToString(StringBuffer buffer, Object object)

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

static ObjectdefaultIfNull(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
 
static booleanequals(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
 
static inthashCode(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()
 
static StringidentityToString(Object object)

Gets the toString that would be produced by Object if a class did not override toString itself.

static voididentityToString(StringBuffer buffer, Object object)

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

static Objectmax(Comparable c1, Comparable c2)
Null safe comparison of Comparables.
static Objectmin(Comparable c1, Comparable c2)
Null safe comparison of Comparables.
static StringtoString(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"
 
static StringtoString(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"
 

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 java.util.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

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

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

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

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:

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:

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: defaultString 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: defaultString String#valueOf(Object)

Copyright © 2001-2010 - Apache Software Foundation