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

  @Deprecated
  public static boolean equals(Object object1,
                          Object object2)

  Deprecated. this method has been replaced by java.util.Objects.equals(Object, Object) in Java 7 and will be removed from future releases.

  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

  @Deprecated
  public static int hashCode(Object obj)

  Deprecated. this method has been replaced by java.util.Objects.hashCode(Object) in Java 7 and will be removed in future releases

  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

• toString

  public String toString()

  Overrides:

  toString in class Object

• hashCodeMulti

  @Deprecated
  public static int hashCodeMulti(Object... objects)

  Deprecated. this method has been replaced by java.util.Objects.hash(Object...) in Java 7 an will be removed in future releases.

  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(Appendable appendable,
                      Object object)
                               throws IOException

  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(appendable, "")            = appendable.append("java.lang.String@1e23"
   ObjectUtils.identityToString(appendable, Boolean.TRUE)  = appendable.append("java.lang.Boolean@7fa"
   ObjectUtils.identityToString(appendable, Boolean.TRUE)  = appendable.append("java.lang.Boolean@7fa")
   

  Parameters:

  appendable - the appendable to append to

  object - the object to create a toString for

  Throws:

  IOException

  Since:

  3.2

• identityToString

  public static void identityToString(StrBuilder builder,
                      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(builder, "")            = builder.append("java.lang.String@1e23"
   ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa"
   ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa")
   

  Parameters:

  builder - the builder to append to

  object - the object to create a toString for

  Since:

  3.2

• 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

• identityToString

  public static void identityToString(StringBuilder builder,
                      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(builder, "")            = builder.append("java.lang.String@1e23"
   ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa"
   ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa")
   

  Parameters:

  builder - the builder to append to

  object - the object to create a toString for

  Since:

  3.2

• toString

  @Deprecated
  public static String toString(Object obj)

  Deprecated. this method has been replaced by java.util.Objects.toString(Object) in Java 7 and will be removed in future releases. Note however that said method will return "null" for null references, while this method returns and empty String. To preserve behavior use java.util.Objects.toString(myObject, "")

  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 "" if null input

  Since:

  2.0

  See Also:

  StringUtils.defaultString(String), String.valueOf(Object)

• toString

  @Deprecated
  public static String toString(Object obj,
                           String nullStr)

  Deprecated. this method has been replaced by java.util.Objects.toString(Object, String) in Java 7 and will be removed in future releases.

  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

• CONST

  public static boolean CONST(boolean v)

  This method returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

       public final static boolean MAGIC_FLAG = ObjectUtils.CONST(true);
   

  This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.

  Parameters:

  v - the boolean value to return

  Returns:

  the boolean v, unchanged

  Since:

  3.2

• CONST

  public static byte CONST(byte v)

  This method returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

       public final static byte MAGIC_BYTE = ObjectUtils.CONST((byte) 127);
   

  This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.

  Parameters:

  v - the byte value to return

  Returns:

  the byte v, unchanged

  Since:

  3.2

• CONST_BYTE

  public static byte CONST_BYTE(int v)
                         throws IllegalArgumentException

  This method returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

       public final static byte MAGIC_BYTE = ObjectUtils.CONST_BYTE(127);
   

  This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.

  Parameters:

  v - the byte literal (as an int) value to return

  Returns:

  the byte v, unchanged

  Throws:

  IllegalArgumentException - if the value passed to v is larger than a byte, that is, smaller than -128 or larger than 127.

  Since:

  3.2

• CONST

  public static char CONST(char v)

  This method returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

       public final static char MAGIC_CHAR = ObjectUtils.CONST('a');
   

  This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.

  Parameters:

  v - the char value to return

  Returns:

  the char v, unchanged

  Since:

  3.2

• CONST

  public static short CONST(short v)

  This method returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

       public final static short MAGIC_SHORT = ObjectUtils.CONST((short) 123);
   

  This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.

  Parameters:

  v - the short value to return

  Returns:

  the short v, unchanged

  Since:

  3.2

• CONST_SHORT

  public static short CONST_SHORT(int v)
                           throws IllegalArgumentException

  This method returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

       public final static short MAGIC_SHORT = ObjectUtils.CONST_SHORT(127);
   

  This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.

  Parameters:

  v - the short literal (as an int) value to return

  Returns:

  the byte v, unchanged

  Throws:

  IllegalArgumentException - if the value passed to v is larger than a short, that is, smaller than -32768 or larger than 32767.

  Since:

  3.2

• CONST

  public static int CONST(int v)

  This method returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

       public final static int MAGIC_INT = ObjectUtils.CONST(123);
   

  This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.

  Parameters:

  v - the int value to return

  Returns:

  the int v, unchanged

  Since:

  3.2

• CONST

  public static long CONST(long v)

  This method returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

       public final static long MAGIC_LONG = ObjectUtils.CONST(123L);
   

  This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.

  Parameters:

  v - the long value to return

  Returns:

  the long v, unchanged

  Since:

  3.2

• CONST

  public static float CONST(float v)

  This method returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

       public final static float MAGIC_FLOAT = ObjectUtils.CONST(1.0f);
   

  This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.

  Parameters:

  v - the float value to return

  Returns:

  the float v, unchanged

  Since:

  3.2

• CONST

  public static double CONST(double v)

  This method returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

       public final static double MAGIC_DOUBLE = ObjectUtils.CONST(1.0);
   

  This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.

  Parameters:

  v - the double value to return

  Returns:

  the double v, unchanged

  Since:

  3.2

• CONST

  public static <T> T CONST(T v)

  This method returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

       public final static String MAGIC_STRING = ObjectUtils.CONST("abc");
   

  This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.

  Type Parameters:

  T - the Object type

  Parameters:

  v - the genericized Object value to return (typically a String).

  Returns:

  the genericized Object v, unchanged (typically a String).

  Since:

  3.2