Class Objects
static utility methods for operating
on objects, or checking certain conditions before operation. These utilities
include null-safe or null-tolerant methods for computing the
hash code of an object, returning a string for an object, comparing two
objects, and checking if indexes or sub-range values are out of bounds.- Since:
- 1.7
-
Method Summary
Modifier and TypeMethodDescriptionstatic intcheckFromIndexSize(int fromIndex, int size, int length) Checks if the sub-range fromfromIndex(inclusive) tofromIndex + size(exclusive) is within the bounds of range from0(inclusive) tolength(exclusive).static longcheckFromIndexSize(long fromIndex, long size, long length) Checks if the sub-range fromfromIndex(inclusive) tofromIndex + size(exclusive) is within the bounds of range from0(inclusive) tolength(exclusive).static intcheckFromToIndex(int fromIndex, int toIndex, int length) Checks if the sub-range fromfromIndex(inclusive) totoIndex(exclusive) is within the bounds of range from0(inclusive) tolength(exclusive).static longcheckFromToIndex(long fromIndex, long toIndex, long length) Checks if the sub-range fromfromIndex(inclusive) totoIndex(exclusive) is within the bounds of range from0(inclusive) tolength(exclusive).static intcheckIndex(int index, int length) Checks if theindexis within the bounds of the range from0(inclusive) tolength(exclusive).static longcheckIndex(long index, long length) Checks if theindexis within the bounds of the range from0(inclusive) tolength(exclusive).static <T> intcompare(T a, T b, Comparator<? super T> c) Returns 0 if the arguments are identical andc.compare(a, b)otherwise.static booleandeepEquals(Object a, Object b) Returnstrueif the arguments are deeply equal to each other andfalseotherwise.static booleanReturnstrueif the arguments are equal to each other andfalseotherwise.static intReturns a hash code for a sequence of input values.static intReturns the hash code of a non-nullargument and 0 for anullargument.static booleanReturnstrueif the provided reference isnull;falseotherwise.static booleanReturnstrueif the provided reference is non-null;falseotherwise.static <T> TrequireNonNull(T obj) Checks that the specified object reference is notnull.static <T> TrequireNonNull(T obj, String message) Checks that the specified object reference is notnulland throws a customizedNullPointerExceptionif it is.static <T> TrequireNonNull(T obj, Supplier<String> messageSupplier) Checks that the specified object reference is notnulland throws a customizedNullPointerExceptionif it is.static <T> TrequireNonNullElse(T obj, T defaultObj) Returns the first argument if it is non-nulland otherwise the second argument if it is non-null.static <T> TrequireNonNullElseGet(T obj, Supplier<? extends T> supplier) Returns the first argument if it is non-nulland otherwise the value fromsupplier.get()if it is non-null.static StringReturns a string equivalent to the string returned byObject.toStringif that method andhashCodeare not overridden.static StringReturns the result of callingtoStringfor a non-nullargument and"null"for anullargument.static StringReturns the result of callingtoStringon the first argument if the first argument is notnulland the second argument otherwise.
-
Method Details
-
equals
Returnstrueif the arguments are equal to each other andfalseotherwise. Consequently, if both arguments arenull,trueis returned. Otherwise, if the first argument is notnull, equality is determined by calling theequalsmethod of the first argument with the second argument of this method. Otherwise,falseis returned.- Parameters:
a- an objectb- an object to be compared withafor equality- Returns:
trueif the arguments are equal to each other andfalseotherwise- See Also:
-
deepEquals
Returnstrueif the arguments are deeply equal to each other andfalseotherwise. Twonullvalues are deeply equal. If both arguments are arrays, the algorithm inArrays.deepEqualsis used to determine equality. Otherwise, equality is determined by using theequalsmethod of the first argument.- Parameters:
a- an objectb- an object to be compared withafor deep equality- Returns:
trueif the arguments are deeply equal to each other andfalseotherwise- See Also:
-
hashCode
Returns the hash code of a non-nullargument and 0 for anullargument.- Parameters:
o- an object- Returns:
- the hash code of a non-
nullargument and 0 for anullargument - See Also:
-
hash
Returns a hash code for a sequence of input values. The hash code is generated as if all the input values were placed into an array, and that array were hashed by callingArrays.hashCode(Object[]).This method is useful for implementing
Object.hashCode()on objects containing multiple fields. For example, if an object that has three fields,x,y, andz, one could write:
Warning: When a single object reference is supplied, the returned value does not equal the hash code of that object reference. This value can be computed by calling@Override public int hashCode() { return Objects.hash(x, y, z); }hashCode(Object).- Parameters:
values- the values to be hashed- Returns:
- a hash code for a sequence of input values
- See Also:
-
toString
-
toString
Returns the result of callingtoStringon the first argument if the first argument is notnulland the second argument otherwise.- Parameters:
o- an objectnullDefault- string to return if the first argument isnull- Returns:
- the result of calling
toStringon the first argument if the first argument is notnulland the second argument otherwise - See Also:
-
toIdentityString
Returns a string equivalent to the string returned byObject.toStringif that method andhashCodeare not overridden.- Implementation Requirements:
- The method returns a string equivalent to:
o.getClass().getName() + "@" + Integer.toHexString(System.identityHashCode(o)) - Implementation Note:
- This method constructs a string for an object without calling any overridable methods of the object.
- Parameters:
o- an object- Returns:
- a string equivalent to the string returned by
Object.toStringif that method andhashCodeare not overridden - Throws:
NullPointerException- if the argument is null- Since:
- 19
- See Also:
-
compare
Returns 0 if the arguments are identical andc.compare(a, b)otherwise. Consequently, if both arguments arenull0 is returned.Note that if one of the arguments is
null, aNullPointerExceptionmay or may not be thrown depending on what ordering policy, if any, theComparatorchooses to have fornullvalues.- Type Parameters:
T- the type of the objects being compared- Parameters:
a- an objectb- an object to be compared withac- theComparatorto compare the first two arguments- Returns:
- 0 if the arguments are identical and
c.compare(a, b)otherwise - See Also:
-
requireNonNull
public static <T> T requireNonNull(T obj) Checks that the specified object reference is notnull. This method is designed primarily for doing parameter validation in methods and constructors, as demonstrated below:public Foo(Bar bar) { this.bar = Objects.requireNonNull(bar); }- Type Parameters:
T- the type of the reference- Parameters:
obj- the object reference to check for nullity- Returns:
objif notnull- Throws:
NullPointerException- ifobjisnull
-
requireNonNull
Checks that the specified object reference is notnulland throws a customizedNullPointerExceptionif it is. This method is designed primarily for doing parameter validation in methods and constructors with multiple parameters, as demonstrated below:public Foo(Bar bar, Baz baz) { this.bar = Objects.requireNonNull(bar, "bar must not be null"); this.baz = Objects.requireNonNull(baz, "baz must not be null"); }- Type Parameters:
T- the type of the reference- Parameters:
obj- the object reference to check for nullitymessage- detail message to be used in the event that aNullPointerExceptionis thrown- Returns:
objif notnull- Throws:
NullPointerException- ifobjisnull
-
isNull
Returnstrueif the provided reference isnull;falseotherwise.- API Note:
- This method exists to be used as a
Predicate,filter(Objects::isNull) - Parameters:
obj- a reference to be checked againstnull- Returns:
trueif the provided reference isnull;falseotherwise- Since:
- 1.8
- See Also:
-
nonNull
Returnstrueif the provided reference is non-null;falseotherwise.- API Note:
- This method exists to be used as a
Predicate,filter(Objects::nonNull) - Parameters:
obj- a reference to be checked againstnull- Returns:
trueif the provided reference is non-null;falseotherwise- Since:
- 1.8
- See Also:
-
requireNonNullElse
public static <T> T requireNonNullElse(T obj, T defaultObj) Returns the first argument if it is non-nulland otherwise the second argument if it is non-null.- Type Parameters:
T- the type of the reference- Parameters:
obj- an objectdefaultObj- a non-nullobject to return if the first argument isnull- Returns:
- the first argument if it is non-
nulland otherwise the second argument if it is non-null - Throws:
NullPointerException- if bothobjis null anddefaultObjisnull- Since:
- 9
-
requireNonNullElseGet
Returns the first argument if it is non-nulland otherwise the value fromsupplier.get()if it is non-null.- Type Parameters:
T- the type of the first argument and return type- Parameters:
obj- an objectsupplier- of a non-nullobject to return if the first argument isnull- Returns:
- the first argument if it is non-
nulland otherwise the value fromsupplier.get()if it is non-null - Throws:
NullPointerException- if bothobjis null and either thesupplierisnullor thesupplier.get()value isnull- Since:
- 9
-
requireNonNull
Checks that the specified object reference is notnulland throws a customizedNullPointerExceptionif it is.Unlike the method
requireNonNull(Object, String), this method allows creation of the message to be deferred until after the null check is made. While this may confer a performance advantage in the non-null case, when deciding to call this method care should be taken that the costs of creating the message supplier are less than the cost of just creating the string message directly.- Type Parameters:
T- the type of the reference- Parameters:
obj- the object reference to check for nullitymessageSupplier- supplier of the detail message to be used in the event that aNullPointerExceptionis thrown- Returns:
objif notnull- Throws:
NullPointerException- ifobjisnull- Since:
- 1.8
-
checkIndex
public static int checkIndex(int index, int length) Checks if theindexis within the bounds of the range from0(inclusive) tolength(exclusive).The
indexis defined to be out of bounds if any of the following inequalities is true:index < 0index >= lengthlength < 0, which is implied from the former inequalities
- Parameters:
index- the indexlength- the upper-bound (exclusive) of the range- Returns:
indexif it is within bounds of the range- Throws:
IndexOutOfBoundsException- if theindexis out of bounds- Since:
- 9
-
checkFromToIndex
public static int checkFromToIndex(int fromIndex, int toIndex, int length) Checks if the sub-range fromfromIndex(inclusive) totoIndex(exclusive) is within the bounds of range from0(inclusive) tolength(exclusive).The sub-range is defined to be out of bounds if any of the following inequalities is true:
fromIndex < 0fromIndex > toIndextoIndex > lengthlength < 0, which is implied from the former inequalities
- Parameters:
fromIndex- the lower-bound (inclusive) of the sub-rangetoIndex- the upper-bound (exclusive) of the sub-rangelength- the upper-bound (exclusive) the range- Returns:
fromIndexif the sub-range within bounds of the range- Throws:
IndexOutOfBoundsException- if the sub-range is out of bounds- Since:
- 9
-
checkFromIndexSize
public static int checkFromIndexSize(int fromIndex, int size, int length) Checks if the sub-range fromfromIndex(inclusive) tofromIndex + size(exclusive) is within the bounds of range from0(inclusive) tolength(exclusive).The sub-range is defined to be out of bounds if any of the following inequalities is true:
fromIndex < 0size < 0fromIndex + size > length, taking into account integer overflowlength < 0, which is implied from the former inequalities
- Parameters:
fromIndex- the lower-bound (inclusive) of the sub-intervalsize- the size of the sub-rangelength- the upper-bound (exclusive) of the range- Returns:
fromIndexif the sub-range within bounds of the range- Throws:
IndexOutOfBoundsException- if the sub-range is out of bounds- Since:
- 9
-
checkIndex
public static long checkIndex(long index, long length) Checks if theindexis within the bounds of the range from0(inclusive) tolength(exclusive).The
indexis defined to be out of bounds if any of the following inequalities is true:index < 0index >= lengthlength < 0, which is implied from the former inequalities
- Parameters:
index- the indexlength- the upper-bound (exclusive) of the range- Returns:
indexif it is within bounds of the range- Throws:
IndexOutOfBoundsException- if theindexis out of bounds- Since:
- 16
-
checkFromToIndex
public static long checkFromToIndex(long fromIndex, long toIndex, long length) Checks if the sub-range fromfromIndex(inclusive) totoIndex(exclusive) is within the bounds of range from0(inclusive) tolength(exclusive).The sub-range is defined to be out of bounds if any of the following inequalities is true:
fromIndex < 0fromIndex > toIndextoIndex > lengthlength < 0, which is implied from the former inequalities
- Parameters:
fromIndex- the lower-bound (inclusive) of the sub-rangetoIndex- the upper-bound (exclusive) of the sub-rangelength- the upper-bound (exclusive) the range- Returns:
fromIndexif the sub-range within bounds of the range- Throws:
IndexOutOfBoundsException- if the sub-range is out of bounds- Since:
- 16
-
checkFromIndexSize
public static long checkFromIndexSize(long fromIndex, long size, long length) Checks if the sub-range fromfromIndex(inclusive) tofromIndex + size(exclusive) is within the bounds of range from0(inclusive) tolength(exclusive).The sub-range is defined to be out of bounds if any of the following inequalities is true:
fromIndex < 0size < 0fromIndex + size > length, taking into account integer overflowlength < 0, which is implied from the former inequalities
- Parameters:
fromIndex- the lower-bound (inclusive) of the sub-intervalsize- the size of the sub-rangelength- the upper-bound (exclusive) of the range- Returns:
fromIndexif the sub-range within bounds of the range- Throws:
IndexOutOfBoundsException- if the sub-range is out of bounds- Since:
- 16
-