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 behavior in more detail.
#ThreadSafe#
Nested Classes
static class
Class used as a null placeholder where null has another meaning.
Fields
Singleton used as a null placeholder where null has another meaning.
Constructors
static boolean
Tests if all values in the array are not nulls.
static boolean
Tests if all values in the given array are null.
static boolean
Tests if any value in the given array is not null.
static boolean
Tests if any value in the given array is null.
static <T> T
static <T> T
Clones an object if possible.
Null safe comparison of Comparables.
compare(T c1, T c2, boolean nullGreater)
Null safe comparison of Comparables.
static boolean
Returns the provided value unchanged.
static byte
Returns the provided value unchanged.
static char
Returns the provided value unchanged.
static double
Returns the provided value unchanged.
static float
Returns the provided value unchanged.
static int
Returns the provided value unchanged.
static long
Returns the provided value unchanged.
static short
Returns the provided value unchanged.
static <T> T
Returns the provided value unchanged.
static byte
Returns the provided value unchanged.
static short
Returns the provided value unchanged.
static <T> T
static boolean
static <T> T
Returns the first value in the array which is not null.
static <T> T
Executes the given suppliers in order and returns the first return value where a value other than null is returned.
static <T> T
Returns the given
object
is it is non-null, otherwise returns the Supplier's
Supplier.get()
value.
static <T> T
Returns a default value if the object passed is null.
static int
static int
static void
Appends the toString that would be produced by
Object
if a class did not override toString itself.
Gets the toString that would be produced by
Object
if a class did not override toString itself.
static void
Appends the toString that would be produced by
Object
if a class did not override toString itself.
static void
Appends the toString that would be produced by
Object
if a class did not override toString itself.
static void
static boolean
Tests whether the given object is an Object array or a primitive array in a null-safe manner.
static boolean
Tests if an Object is empty or null.
static boolean
Tests if an Object is not empty and not null.
Null safe comparison of Comparables.
static <T> T
Find the "best guess" middle value among comparables.
Find the "best guess" middle value among comparables.
Null safe comparison of Comparables.
static <T> T
Find the most frequently occurring item.
static boolean
Compares two objects for inequality, where either one or both objects may be null.
static <T> T
Checks that the specified object reference is not
null
or empty per
isEmpty(Object)
.
static <T> T
Checks that the specified object reference is not
null
or empty per
isEmpty(Object)
.
Gets the
toString()
of an
Object
or the empty string (
""
) if the input is
null
.
Gets the
toString
of an
Object
returning a specified text if
null
input.
static void
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitSingleton used as a
null
placeholder where
null
has another meaning.
For example, in a HashMap the HashMap.get(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.
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.
Tests if all values in the array are not
nulls
.
If any value is null or the array is null then false is returned. If all elements in array are not null or the array is empty (contains no elements) true is returned.
ObjectUtils.allNotNull(*) = true ObjectUtils.allNotNull(*, *) = true ObjectUtils.allNotNull(null) = false ObjectUtils.allNotNull(null, null) = false ObjectUtils.allNotNull(null, *) = false ObjectUtils.allNotNull(*, null) = false ObjectUtils.allNotNull(*, *, null, *) = false
values - the values to test, may be null or empty
false if there is at least one null value in the array or the array is null, true if all values in the array are not nulls or array contains no elements.
Tests if all values in the given array are
null
.
If all the values are null or the array is null or empty, then true is returned, otherwise false is returned.
ObjectUtils.allNull(*) = false ObjectUtils.allNull(*, null) = false ObjectUtils.allNull(null, *) = false ObjectUtils.allNull(null, null, *, *) = false ObjectUtils.allNull(null) = true ObjectUtils.allNull(null, null) = true
values - the values to test, may be null or empty
true if all values in the array are nulls, false if there is at least one non-null value in the array.
Tests if any value in the given array is not
null
.
If all the values are null or the array is null or empty then false is returned. Otherwise true is returned.
ObjectUtils.anyNotNull(*) = true ObjectUtils.anyNotNull(*, null) = true ObjectUtils.anyNotNull(null, *) = true ObjectUtils.anyNotNull(null, null, *, *) = true ObjectUtils.anyNotNull(null) = false ObjectUtils.anyNotNull(null, null) = false
values - the values to test, may be null or empty
true if there is at least one non-null value in the array, false if all values in the array are nulls. If the array is null or empty false is also returned.
Tests if any value in the given array is
null
.
If any of the values are null or the array is null, then true is returned, otherwise false is returned.
ObjectUtils.anyNull(*) = false ObjectUtils.anyNull(*, *) = false ObjectUtils.anyNull(null) = true ObjectUtils.anyNull(null, null) = true ObjectUtils.anyNull(null, *) = true ObjectUtils.anyNull(*, null) = true ObjectUtils.anyNull(*, *, null, *) = true
values - the values to test, may be null or empty
true if there is at least one null value in the array, false if all the values are non-null. If the array is null or empty, true is also returned.
Clones an object.
T - the type of the object
obj - the object to clone, null returns null
Cloneable otherwise null
CloneFailedException - if the object is cloneable and the clone operation fails
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.
T - the type of the object
obj - the object to clone, null returns null
Cloneable otherwise the object itself
CloneFailedException - if the object is cloneable and the clone operation fails
Null safe comparison of Comparables.
null
is assumed to be less than a non-
null
value.
TODO Move to ComparableUtils.
T - type of the values processed by this method
c1 - the first comparable, may be null
c2 - the second comparable, may be null
TODO Move to ComparableUtils.
T - type of the values processed by this method
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 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.
v - the boolean value to return
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.
v - the byte value to return
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.
v - the char value to return
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.
v - the double value to return
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.
v - the float value to return
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.
v - the int value to return
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.
v - the long value to return
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.
v - the short value to return
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.
T - the Object type
v - the genericized Object value to return (typically a String).
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.
v - the byte literal (as an int) value to return
IllegalArgumentException - if the value passed to v is larger than a byte, that is, smaller than -128 or larger than 127.
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.
v - the short literal (as an int) value to return
IllegalArgumentException - if the value passed to v is larger than a short, that is, smaller than -32768 or larger than 32767.
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
T - the type of the object
object - the Object to test, may be null
defaultValue - the default value to return, may be null
object if it is not null, defaultValue otherwise
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
object1 - the first object, may be null
object2 - the second object, may be null
true if the values of both objects are the same
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
T - the component type of the array
values - the values to test, may be null or empty
values which is not null, or null if there are no non-null values
T - The argument type or null.
object - The argument.
Executes the given suppliers in order and returns the first return value where a value other than
null
is returned. Once a non-
null
value is obtained, all following suppliers are not executed anymore. If all the return values are
null
or no suppliers are provided then
null
is returned.
ObjectUtils.firstNonNullLazy(null, () -> null) = null ObjectUtils.firstNonNullLazy(() -> null, () -> "") = "" ObjectUtils.firstNonNullLazy(() -> "", () -> throw new IllegalStateException()) = "" ObjectUtils.firstNonNullLazy(() -> null, () -> "zz) = "zz" ObjectUtils.firstNonNullLazy() = null
T - the type of the return values
suppliers - the suppliers returning the values to test. null values are ignored. Suppliers may return null or a value of type T
suppliers which is not null, or null if there are no non-null values
Returns the given
object
is it is non-null, otherwise returns the Supplier's
Supplier.get()
value.
The caller responsible for thread-safety and exception handling of default value supplier.
ObjectUtils.getIfNull(null, () -> null) = null
ObjectUtils.getIfNull(null, null) = null
ObjectUtils.getIfNull(null, () -> "") = ""
ObjectUtils.getIfNull(null, () -> "zz") = "zz"
ObjectUtils.getIfNull("abc", *) = "abc"
ObjectUtils.getIfNull(Boolean.TRUE, *) = Boolean.TRUE
T - the type of the object
object - the Object to test, may be null
defaultSupplier - the default value to return, may be null
object if it is not null, defaultValueSupplier.get() otherwise
Returns a default value if the object passed is
null
.
ObjectUtils.getIfNull(null, null) = null
ObjectUtils.getIfNull(null, "") = ""
ObjectUtils.getIfNull(null, "zz") = "zz"
ObjectUtils.getIfNull("abc", *) = "abc"
ObjectUtils.getIfNull(Boolean.TRUE, *) = Boolean.TRUE
T - the type of the object
object - the Object to test, may be null
defaultValue - the default value to return, may be null
object if it is not null, defaultValue otherwise
Gets the hash code of an object returning zero when the object is
null
.
ObjectUtils.hashCode(null) = 0 ObjectUtils.hashCode(obj) = obj.hashCode()
obj - the object to obtain the hash code of, may be null
Returns the hexadecimal hash code for the given object per
Objects.hashCode(Object)
.
Short hand for Integer.toHexString(Objects.hashCode(object)).
object - object for which the hashCode is to be calculated
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()
objects - the objects to obtain the hash code of, may be null
Returns the hexadecimal hash code for the given object per
System.identityHashCode(Object)
.
Short hand for Integer.toHexString(System.identityHashCode(object)).
object - object for which the hashCode is to be calculated
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")
appendable - the appendable to append to
object - the object to create a toString for
IOException - if an I/O error occurs.
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"
object - the object to create a toString for, may be null
null if null passed in
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")
builder - the builder to append to
object - the object to create a toString for
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")
buffer - the buffer to append to
object - the object to create a toString for
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")
builder - the builder to append to
object - the object to create a toString for
Tests whether the given object is an Object array or a primitive array in a null-safe manner.
A null object Object will return false.
ObjectUtils.isArray(null) = false
ObjectUtils.isArray("") = false
ObjectUtils.isArray("ab") = false
ObjectUtils.isArray(new int[]{}) = true
ObjectUtils.isArray(new int[]{1,2,3}) = true
ObjectUtils.isArray(1234) = false
object - the object to check, may be null
true if the object is an array, false otherwise
Tests if an Object is empty or null. The following types are supported:
CharSequence: Considered empty if its length is zero.Array: Considered empty if its length is zero.Collection: Considered empty if it has zero elements.Map: Considered empty if it has zero key-value mappings.Optional: Considered empty if Optional.isPresent() returns false, regardless of the "emptiness" of the contents. ObjectUtils.isEmpty(null) = true
ObjectUtils.isEmpty("") = true
ObjectUtils.isEmpty("ab") = false
ObjectUtils.isEmpty(new int[]{}) = true
ObjectUtils.isEmpty(new int[]{1,2,3}) = false
ObjectUtils.isEmpty(1234) = false
ObjectUtils.isEmpty(1234) = false
ObjectUtils.isEmpty(Optional.of("")) = false
ObjectUtils.isEmpty(Optional.empty()) = true
object - the Object to test, may be null
true if the object has a supported type and is empty or null, false otherwise
Tests if an Object is not empty and not null. The following types are supported:
CharSequence: Considered empty if its length is zero.Array: Considered empty if its length is zero.Collection: Considered empty if it has zero elements.Map: Considered empty if it has zero key-value mappings.Optional: Considered empty if Optional.isPresent() returns false, regardless of the "emptiness" of the contents. ObjectUtils.isNotEmpty(null) = false
ObjectUtils.isNotEmpty("") = false
ObjectUtils.isNotEmpty("ab") = true
ObjectUtils.isNotEmpty(new int[]{}) = false
ObjectUtils.isNotEmpty(new int[]{1,2,3}) = true
ObjectUtils.isNotEmpty(1234) = true
ObjectUtils.isNotEmpty(Optional.of("")) = true
ObjectUtils.isNotEmpty(Optional.empty()) = false
object - the Object to test, may be null
true if the object has an unsupported type or is not empty and not null, false otherwise
TODO Move to ComparableUtils.
T - type of the values processed by this method
values - the set of comparable values, may be null
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.
T - type of values processed by this method
comparator - to use for comparisons
items - to compare
NullPointerException - if items or comparator is null
IllegalArgumentException - if items is empty or contains null values
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.
T - type of values processed by this method
items - to compare
NullPointerException - if items is null
IllegalArgumentException - if items is empty or contains null values
TODO Move to ComparableUtils.
T - type of the values processed by this method
values - the set of comparable values, may be null
Find the most frequently occurring item.
T - type of values processed by this method
items - to check
null if non-unique or no items supplied
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
object1 - the first object, may be null
object2 - the second object, may be null
false if the values of both objects are the same
Checks that the specified object reference is not
null
or empty per
isEmpty(Object)
. Use this method for validation, for example:
public Foo(Bar bar) {
this.bar = Objects.requireNonEmpty(bar);
}
T - the type of the reference.
obj - the object reference to check for nullity.
obj if not null.
NullPointerException - if obj is null.
IllegalArgumentException - if obj is empty per isEmpty(Object).
Checks that the specified object reference is not
null
or empty per
isEmpty(Object)
. Use this method for validation, for example:
public Foo(Bar bar) {
this.bar = Objects.requireNonEmpty(bar, "bar");
}
T - the type of the reference.
obj - the object reference to check for nullity.
message - the exception message.
obj if not null.
NullPointerException - if obj is null.
IllegalArgumentException - if obj is empty per isEmpty(Object).
Gets the
toString()
of an
Object
or the empty string (
""
) if the input is
null
.
ObjectUtils.toString(null) = ""
ObjectUtils.toString("") = ""
ObjectUtils.toString("bat") = "bat"
ObjectUtils.toString(Boolean.TRUE) = "true"
obj - the Object to toString(), may be null.
toString(), or "" if the input is null.
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"
obj - the Object to toString, may be null
nullStr - the String to return if null input, may be null
nullStr if null input
Gets the
toString
of an
Supplier
's
Supplier.get()
returning a specified text if
null
input.
ObjectUtils.toString(() -> obj, () -> expensive())
ObjectUtils.toString(() -> null, () -> expensive()) = result of expensive() ObjectUtils.toString(() -> null, () -> expensive()) = result of expensive() ObjectUtils.toString(() -> "", () -> expensive()) = "" ObjectUtils.toString(() -> "bat", () -> expensive()) = "bat" ObjectUtils.toString(() -> Boolean.TRUE, () -> expensive()) = "true"
obj - the Object to toString, may be null
supplier - the Supplier of String used on null input, may be null
nullStr if null input
Gets the
toString
of an
Object
returning a specified text if
null
input.
ObjectUtils.toString(obj, () -> expensive())
ObjectUtils.toString(null, () -> expensive()) = result of expensive()
ObjectUtils.toString(null, () -> expensive()) = result of expensive()
ObjectUtils.toString("", () -> expensive()) = ""
ObjectUtils.toString("bat", () -> expensive()) = "bat"
ObjectUtils.toString(Boolean.TRUE, () -> expensive()) = "true"
T - the obj type (used to provide better source compatibility in 3.14.0).
obj - the Object to toString, may be null
supplier - the Supplier of String used on null input, may be null
nullStr if null input
obj - The receiver of the wait call.
duration - How long to wait.
IllegalArgumentException - if the timeout duration is negative.
IllegalMonitorStateException - if the current thread is not the owner of the obj's monitor.
InterruptedException - if any thread interrupted the current thread before or while the current thread was waiting for a notification. The interrupted status of the current thread is cleared when this exception is thrown.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4