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 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).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).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).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).static int
checkIndex
(int index, int length) Checks if theindex
is within the bounds of the range from0
(inclusive) tolength
(exclusive).static long
checkIndex
(long index, long length) Checks if theindex
is within the bounds of the range from0
(inclusive) tolength
(exclusive).static <T> int
compare
(T a, T b, Comparator<? super T> c) Returns 0 if the arguments are identical andc.compare(a, b)
otherwise.static boolean
deepEquals
(Object a, Object b) Returnstrue
if the arguments are deeply equal to each other andfalse
otherwise.static boolean
Returnstrue
if the arguments are equal to each other andfalse
otherwise.static long
Return the size of the object in the heap.static int
Returns a hash code for a sequence of input values.static int
Returns the hash code of a non-null
argument and 0 for anull
argument.static boolean
hasIdentity
(Object obj) Preview.Returnstrue
if the specified object reference is an identity object, otherwisefalse
.static boolean
Returnstrue
if the provided reference isnull
;false
otherwise.static boolean
Returnstrue
if the provided reference is non-null
;false
otherwise.static <T> T
requireIdentity
(T obj) Preview.Checks that the specified object reference is an identity object.static <T> T
requireIdentity
(T obj, String message) Preview.Checks that the specified object reference is an identity object.static <T> T
requireIdentity
(T obj, Supplier<String> messageSupplier) Preview.Checks that the specified object reference is an identity object.static <T> T
requireNonNull
(T obj) Checks that the specified object reference is notnull
.static <T> T
requireNonNull
(T obj, String message) Checks that the specified object reference is notnull
and throws a customizedNullPointerException
if it is.static <T> T
requireNonNull
(T obj, Supplier<String> messageSupplier) Checks that the specified object reference is notnull
and throws a customizedNullPointerException
if it is.static <T> T
requireNonNullElse
(T obj, T defaultObj) Returns the first argument if it is non-null
and otherwise the second argument if it is non-null
.static <T> T
requireNonNullElseGet
(T obj, Supplier<? extends T> supplier) Returns the first argument if it is non-null
and otherwise the value fromsupplier.get()
if it is non-null
.static String
Returns a string equivalent to the string returned byObject.toString
if that method andhashCode
are not overridden.static String
Returns the result of callingtoString
for a non-null
argument and"null"
for anull
argument.static String
Returns the result of callingtoString
on the first argument if the first argument is notnull
and the second argument otherwise.
-
Method Details
-
equals
Returnstrue
if the arguments are equal to each other andfalse
otherwise. Consequently, if both arguments arenull
,true
is returned. Otherwise, if the first argument is notnull
, equality is determined by calling theequals
method of the first argument with the second argument of this method. Otherwise,false
is returned.- Parameters:
a
- an objectb
- an object to be compared witha
for equality- Returns:
true
if the arguments are equal to each other andfalse
otherwise- See Also:
-
deepEquals
Returnstrue
if the arguments are deeply equal to each other andfalse
otherwise. Twonull
values are deeply equal. If both arguments are arrays, the algorithm inArrays.deepEquals
is used to determine equality. Otherwise, equality is determined by using theequals
method of the first argument.- Parameters:
a
- an objectb
- an object to be compared witha
for deep equality- Returns:
true
if the arguments are deeply equal to each other andfalse
otherwise- See Also:
-
hashCode
Returns the hash code of a non-null
argument and 0 for anull
argument.- Parameters:
o
- an object- Returns:
- the hash code of a non-
null
argument and 0 for anull
argument - 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 callingtoString
on the first argument if the first argument is notnull
and the second argument otherwise.- Parameters:
o
- an objectnullDefault
- string to return if the first argument isnull
- Returns:
- the result of calling
toString
on the first argument if the first argument is notnull
and the second argument otherwise - See Also:
-
toIdentityString
Returns a string equivalent to the string returned byObject.toString
if that method andhashCode
are 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.toString
if that method andhashCode
are not overridden - Throws:
NullPointerException
- if the argument is null- Since:
- 19
- See Also:
-
hasIdentity
hasIdentity
is a preview API of the Java platform.Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.Returnstrue
if the specified object reference is an identity object, otherwisefalse
.- Parameters:
obj
- an object- Returns:
true
if the specified object reference is an identity object, otherwisefalse
- Throws:
NullPointerException
- ifobj
isnull
-
requireIdentity
public static <T> T requireIdentity(T obj) requireIdentity
is a preview API of the Java platform.Programs can only userequireIdentity
when preview features are enabled.Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.Checks that the specified object reference is an identity object.- Type Parameters:
T
- the type of the reference- Parameters:
obj
- the object reference to check for identity- Returns:
obj
ifobj
is an identity object- Throws:
NullPointerException
- ifobj
isnull
IdentityExceptionPREVIEW
- ifobj
is not an identity object- Since:
- Valhalla
-
requireIdentity
requireIdentity
is a preview API of the Java platform.Programs can only userequireIdentity
when preview features are enabled.Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.Checks that the specified object reference is an identity object.- Type Parameters:
T
- the type of the reference- Parameters:
obj
- the object reference to check for identitymessage
- detail message to be used in the event that anIdentityException
is thrown; may be null- Returns:
obj
ifobj
is an identity object- Throws:
NullPointerException
- ifobj
isnull
IdentityExceptionPREVIEW
- ifobj
is not an identity object- Since:
- Valhalla
-
requireIdentity
requireIdentity
is a preview API of the Java platform.Programs can only userequireIdentity
when preview features are enabled.Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.Checks that the specified object reference is an identity object.- Type Parameters:
T
- the type of the reference- Parameters:
obj
- the object reference to check for identitymessageSupplier
- supplier of the detail message to be used in the event that anIdentityException
is thrown; may be null- Returns:
obj
ifobj
is an identity object- Throws:
NullPointerException
- ifobj
isnull
IdentityExceptionPREVIEW
- ifobj
is not an identity object- Since:
- Valhalla
-
compare
Returns 0 if the arguments are identical andc.compare(a, b)
otherwise. Consequently, if both arguments arenull
0 is returned.Note that if one of the arguments is
null
, aNullPointerException
may or may not be thrown depending on what ordering policy, if any, theComparator
chooses to have fornull
values.- Type Parameters:
T
- the type of the objects being compared- Parameters:
a
- an objectb
- an object to be compared witha
c
- theComparator
to 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:
obj
if notnull
- Throws:
NullPointerException
- ifobj
isnull
-
requireNonNull
Checks that the specified object reference is notnull
and throws a customizedNullPointerException
if 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 aNullPointerException
is thrown- Returns:
obj
if notnull
- Throws:
NullPointerException
- ifobj
isnull
-
isNull
Returnstrue
if the provided reference isnull
;false
otherwise.- API Note:
- This method exists to be used as a
Predicate
,filter(Objects::isNull)
- Parameters:
obj
- a reference to be checked againstnull
- Returns:
true
if the provided reference isnull
;false
otherwise- Since:
- 1.8
- See Also:
-
nonNull
Returnstrue
if the provided reference is non-null
;false
otherwise.- API Note:
- This method exists to be used as a
Predicate
,filter(Objects::nonNull)
- Parameters:
obj
- a reference to be checked againstnull
- Returns:
true
if the provided reference is non-null
;false
otherwise- Since:
- 1.8
- See Also:
-
requireNonNullElse
public static <T> T requireNonNullElse(T obj, T defaultObj) Returns the first argument if it is non-null
and otherwise the second argument if it is non-null
.- Type Parameters:
T
- the type of the reference- Parameters:
obj
- an objectdefaultObj
- a non-null
object to return if the first argument isnull
- Returns:
- the first argument if it is non-
null
and otherwise the second argument if it is non-null
- Throws:
NullPointerException
- if bothobj
is null anddefaultObj
isnull
- Since:
- 9
-
requireNonNullElseGet
Returns the first argument if it is non-null
and 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-null
object to return if the first argument isnull
- Returns:
- the first argument if it is non-
null
and otherwise the value fromsupplier.get()
if it is non-null
- Throws:
NullPointerException
- if bothobj
is null and either thesupplier
isnull
or thesupplier.get()
value isnull
- Since:
- 9
-
requireNonNull
Checks that the specified object reference is notnull
and throws a customizedNullPointerException
if 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 aNullPointerException
is thrown- Returns:
obj
if notnull
- Throws:
NullPointerException
- ifobj
isnull
- Since:
- 1.8
-
checkIndex
public static int checkIndex(int index, int length) Checks if theindex
is within the bounds of the range from0
(inclusive) tolength
(exclusive).The
index
is defined to be out of bounds if any of the following inequalities is true:index < 0
index >= length
length < 0
, which is implied from the former inequalities
- Parameters:
index
- the indexlength
- the upper-bound (exclusive) of the range- Returns:
index
if it is within bounds of the range- Throws:
IndexOutOfBoundsException
- if theindex
is 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 < 0
fromIndex > toIndex
toIndex > length
length < 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:
fromIndex
if 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 < 0
size < 0
fromIndex + 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:
fromIndex
if the sub-range within bounds of the range- Throws:
IndexOutOfBoundsException
- if the sub-range is out of bounds- Since:
- 9
-
getObjectSize
Return the size of the object in the heap.- Parameters:
o
- an object- Returns:
- the objects's size
- Since:
- Valhalla
-
checkIndex
public static long checkIndex(long index, long length) Checks if theindex
is within the bounds of the range from0
(inclusive) tolength
(exclusive).The
index
is defined to be out of bounds if any of the following inequalities is true:index < 0
index >= length
length < 0
, which is implied from the former inequalities
- Parameters:
index
- the indexlength
- the upper-bound (exclusive) of the range- Returns:
index
if it is within bounds of the range- Throws:
IndexOutOfBoundsException
- if theindex
is 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 < 0
fromIndex > toIndex
toIndex > length
length < 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:
fromIndex
if 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 < 0
size < 0
fromIndex + 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:
fromIndex
if the sub-range within bounds of the range- Throws:
IndexOutOfBoundsException
- if the sub-range is out of bounds- Since:
- 16
-
hasIdentity
when preview features are enabled.