Top Description Constructors Methods
java.util

public final Class Objects

extends Object
Class Inheritance
Imports
jdk.internal.util.Preconditions, jdk.internal.vm.annotation.ForceInline, java.util.function.Supplier
This class consists of 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

Constructor Summary

AccessConstructor and Description
private
Objects()

Method Summary

Modifier and TypeMethod and Description
public static int

Returns:

fromIndex if the sub-range within bounds of the range
checkFromIndexSize(int
the lower-bound (inclusive) of the sub-interval
fromIndex, int
the size of the sub-range
size, int
the upper-bound (exclusive) of the range
length)

Checks if the sub-range from fromIndex (inclusive) to fromIndex + size (exclusive) is within the bounds of range from 0 (inclusive) to length (exclusive).

public static long

Returns:

fromIndex if the sub-range within bounds of the range
checkFromIndexSize(long
the lower-bound (inclusive) of the sub-interval
fromIndex, long
the size of the sub-range
size, long
the upper-bound (exclusive) of the range
length)

Checks if the sub-range from fromIndex (inclusive) to fromIndex + size (exclusive) is within the bounds of range from 0 (inclusive) to length (exclusive).

public static int

Returns:

fromIndex if the sub-range within bounds of the range
checkFromToIndex(int
the lower-bound (inclusive) of the sub-range
fromIndex, int
the upper-bound (exclusive) of the sub-range
toIndex, int
the upper-bound (exclusive) the range
length)

Checks if the sub-range from fromIndex (inclusive) to toIndex (exclusive) is within the bounds of range from 0 (inclusive) to length (exclusive).

public static long

Returns:

fromIndex if the sub-range within bounds of the range
checkFromToIndex(long
the lower-bound (inclusive) of the sub-range
fromIndex, long
the upper-bound (exclusive) of the sub-range
toIndex, long
the upper-bound (exclusive) the range
length)

Checks if the sub-range from fromIndex (inclusive) to toIndex (exclusive) is within the bounds of range from 0 (inclusive) to length (exclusive).

public static int

Returns:

index if it is within bounds of the range
checkIndex(int
the index
index, int
the upper-bound (exclusive) of the range
length)

Checks if the index is within the bounds of the range from 0 (inclusive) to length (exclusive).

public static long

Returns:

index if it is within bounds of the range
checkIndex(long
the index
index, long
the upper-bound (exclusive) of the range
length)

Checks if the index is within the bounds of the range from 0 (inclusive) to length (exclusive).

public static <
the type of the objects being compared
T> int

Returns:

0 if the arguments are identical and c.compare(a, b) otherwise
compare(T
an object
a, T
an object to be compared with a
b, Comparator<? super T>
the Comparator to compare the first two arguments
c)

Returns 0 if the arguments are identical and c.compare(a, b) otherwise.

public static boolean

Returns:

true if the arguments are deeply equal to each other and false otherwise
deepEquals(Object
an object
a, Object
an object to be compared with a for deep equality
b)

Returns true if the arguments are deeply equal to each other and false otherwise.

public static boolean

Returns:

true if the arguments are equal to each other and false otherwise
equals(Object
an object
a, Object
an object to be compared with a for equality
b)

Returns true if the arguments are equal to each other and false otherwise.

public static int

Returns:

a hash code for a sequence of input values
hash(Object...
the values to be hashed
values)

Returns a hash code for a sequence of input values.

public static int

Returns:

the hash code of a non-null argument and 0 for a null argument
hashCode(Object
an object
o)

Returns the hash code of a non-null argument and 0 for a null argument.

public static boolean

Returns:

true if the provided reference is null; false otherwise
isNull(Object
a reference to be checked against null
obj)

Returns true if the provided reference is null; false otherwise.

public static boolean

Returns:

true if the provided reference is non-null; false otherwise
nonNull(Object
a reference to be checked against null
obj)

Returns true if the provided reference is non-null; false otherwise.

public static <
the type of the reference
T> T

Returns:

obj if not null
requireNonNull(T
the object reference to check for nullity
obj)

Checks that the specified object reference is not null.

public static <
the type of the reference
T> T

Returns:

obj if not null
requireNonNull(T
the object reference to check for nullity
obj, String
detail message to be used in the event that a NullPointerException is thrown
message)

Checks that the specified object reference is not null and throws a customized NullPointerException if it is.

public static <
the type of the reference
T> T

Returns:

obj if not null
requireNonNull(T
the object reference to check for nullity
obj, Supplier<String>
supplier of the detail message to be used in the event that a NullPointerException is thrown
messageSupplier)

Checks that the specified object reference is not null and throws a customized NullPointerException if it is.

public static <
the type of the reference
T> T

Returns:

the first argument if it is non-null and otherwise the second argument if it is non-null
requireNonNullElse(T
an object
obj, T
a non-null object to return if the first argument is null
defaultObj)

Returns the first argument if it is non-null and otherwise the second argument if it is non-null.

public static <
the type of the first argument and return type
T> T

Returns:

the first argument if it is non-null and otherwise the value from supplier.get() if it is non-null
requireNonNullElseGet(T
an object
obj, Supplier<? extends T>
of a non-null object to return if the first argument is null
supplier)

Returns the first argument if it is non-null and otherwise the value from supplier.get() if it is non-null.

public static String

Returns:

a string equivalent to the string returned by Object.toString if that method and hashCode are not overridden
toIdentityString(Object
an object
o)

Returns a string equivalent to the string returned by Object.toString if that method and hashCode are not overridden.

public static String

Returns:

the result of calling toString for a non-null argument and "null" for a null argument
toString(Object
an object
o)

Returns the result of calling toString for a non-null argument and "null" for a null argument.

public static String

Returns:

the result of calling toString on the first argument if the first argument is not null and the second argument otherwise
toString(Object
an object
o, String
string to return if the first argument is null
nullDefault)

Returns the result of calling toString on the first argument if the first argument is not null and the second argument otherwise.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Constructor Detail

Objectsback to summary
private Objects()

Method Detail

checkFromIndexSizeback to summary
public static int checkFromIndexSize(int fromIndex, int size, int length)

Checks if the sub-range from fromIndex (inclusive) to fromIndex + size (exclusive) is within the bounds of range from 0 (inclusive) to length (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 overflow
  • length < 0, which is implied from the former inequalities
Parameters
fromIndex:int

the lower-bound (inclusive) of the sub-interval

size:int

the size of the sub-range

length:int

the upper-bound (exclusive) of the range

Returns:int

fromIndex if the sub-range within bounds of the range

Exceptions
IndexOutOfBoundsException:
if the sub-range is out of bounds
Since
9
checkFromIndexSizeback to summary
public static long checkFromIndexSize(long fromIndex, long size, long length)

Checks if the sub-range from fromIndex (inclusive) to fromIndex + size (exclusive) is within the bounds of range from 0 (inclusive) to length (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 overflow
  • length < 0, which is implied from the former inequalities
Parameters
fromIndex:long

the lower-bound (inclusive) of the sub-interval

size:long

the size of the sub-range

length:long

the upper-bound (exclusive) of the range

Returns:long

fromIndex if the sub-range within bounds of the range

Exceptions
IndexOutOfBoundsException:
if the sub-range is out of bounds
Since
16
checkFromToIndexback to summary
public static int checkFromToIndex(int fromIndex, int toIndex, int length)

Checks if the sub-range from fromIndex (inclusive) to toIndex (exclusive) is within the bounds of range from 0 (inclusive) to length (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:int

the lower-bound (inclusive) of the sub-range

toIndex:int

the upper-bound (exclusive) of the sub-range

length:int

the upper-bound (exclusive) the range

Returns:int

fromIndex if the sub-range within bounds of the range

Exceptions
IndexOutOfBoundsException:
if the sub-range is out of bounds
Since
9
checkFromToIndexback to summary
public static long checkFromToIndex(long fromIndex, long toIndex, long length)

Checks if the sub-range from fromIndex (inclusive) to toIndex (exclusive) is within the bounds of range from 0 (inclusive) to length (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:long

the lower-bound (inclusive) of the sub-range

toIndex:long

the upper-bound (exclusive) of the sub-range

length:long

the upper-bound (exclusive) the range

Returns:long

fromIndex if the sub-range within bounds of the range

Exceptions
IndexOutOfBoundsException:
if the sub-range is out of bounds
Since
16
checkIndexback to summary
public static int checkIndex(int index, int length)

Checks if the index is within the bounds of the range from 0 (inclusive) to length (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:int

the index

length:int

the upper-bound (exclusive) of the range

Returns:int

index if it is within bounds of the range

Annotations
@ForceInline
Exceptions
IndexOutOfBoundsException:
if the index is out of bounds
Since
9
checkIndexback to summary
public static long checkIndex(long index, long length)

Checks if the index is within the bounds of the range from 0 (inclusive) to length (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:long

the index

length:long

the upper-bound (exclusive) of the range

Returns:long

index if it is within bounds of the range

Annotations
@ForceInline
Exceptions
IndexOutOfBoundsException:
if the index is out of bounds
Since
16
compareback to summary
public static <T> int compare(T a, T b, Comparator<? super T> c)

Returns 0 if the arguments are identical and c.compare(a, b) otherwise. Consequently, if both arguments are null 0 is returned.

Note that if one of the arguments is null, a NullPointerException may or may not be thrown depending on what ordering policy, if any, the Comparator chooses to have for null values.

Parameters
<T>
the type of the objects being compared
a:T

an object

b:T

an object to be compared with a

c:Comparator<? super T>

the Comparator to compare the first two arguments

Returns:int

0 if the arguments are identical and c.compare(a, b) otherwise

See Also
Comparable, Comparator
deepEqualsback to summary
public static boolean deepEquals(Object a, Object b)

Returns true if the arguments are deeply equal to each other and false otherwise. Two null values are deeply equal. If both arguments are arrays, the algorithm in Arrays.deepEquals is used to determine equality. Otherwise, equality is determined by using the equals method of the first argument.

Parameters
a:Object

an object

b:Object

an object to be compared with a for deep equality

Returns:boolean

true if the arguments are deeply equal to each other and false otherwise

See Also
Arrays#deepEquals(Object[], Object[]), Objects#equals(Object, Object)
equalsback to summary
public static boolean equals(Object a, Object b)

Returns true if the arguments are equal to each other and false otherwise. Consequently, if both arguments are null, true is returned. Otherwise, if the first argument is not null, equality is determined by calling the equals method of the first argument with the second argument of this method. Otherwise, false is returned.

Parameters
a:Object

an object

b:Object

an object to be compared with a for equality

Returns:boolean

true if the arguments are equal to each other and false otherwise

See Also
Object#equals(Object)
hashback to summary
public static int hash(Object... values)

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 calling Arrays#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, and z, one could write: 

@Override public int hashCode() {
    return Objects.hash(x, y, z);
}
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 hashCode(Object).
Parameters
values:Object[]

the values to be hashed

Returns:int

a hash code for a sequence of input values

See Also
Arrays#hashCode(Object[]), List#hashCode
hashCodeback to summary
public static int hashCode(Object o)

Returns the hash code of a non-null argument and 0 for a null argument.

Parameters
o:Object

an object

Returns:int

the hash code of a non-null argument and 0 for a null argument

See Also
Object#hashCode
isNullback to summary
public static boolean isNull(Object obj)

Returns true if the provided reference is null; false otherwise.

API Note

This method exists to be used as a java.util.function.Predicate, filter(Objects::isNull)

Parameters
obj:Object

a reference to be checked against null

Returns:boolean

true if the provided reference is null; false otherwise

Since
1.8
See Also
java.util.function.Predicate
nonNullback to summary
public static boolean nonNull(Object obj)

Returns true if the provided reference is non-null; false otherwise.

API Note

This method exists to be used as a java.util.function.Predicate, filter(Objects::nonNull)

Parameters
obj:Object

a reference to be checked against null

Returns:boolean

true if the provided reference is non-null; false otherwise

Since
1.8
See Also
java.util.function.Predicate
requireNonNullback to summary
public static <T> T requireNonNull(T obj)

Checks that the specified object reference is not null. 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);
}
Parameters
<T>
the type of the reference
obj:T

the object reference to check for nullity

Returns:T

obj if not null

Annotations
@ForceInline
Exceptions
NullPointerException:
if obj is null
requireNonNullback to summary
public static <T> T requireNonNull(T obj, String message)

Checks that the specified object reference is not null and throws a customized NullPointerException 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");
}
Parameters
<T>
the type of the reference
obj:T

the object reference to check for nullity

message:String

detail message to be used in the event that a NullPointerException is thrown

Returns:T

obj if not null

Annotations
@ForceInline
Exceptions
NullPointerException:
if obj is null
requireNonNullback to summary
public static <T> T requireNonNull(T obj, Supplier<String> messageSupplier)

Checks that the specified object reference is not null and throws a customized NullPointerException 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.

Parameters
<T>
the type of the reference
obj:T

the object reference to check for nullity

messageSupplier:Supplier<String>

supplier of the detail message to be used in the event that a NullPointerException is thrown

Returns:T

obj if not null

Exceptions
NullPointerException:
if obj is null
Since
1.8
requireNonNullElseback to summary
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.

Parameters
<T>
the type of the reference
obj:T

an object

defaultObj:T

a non-null object to return if the first argument is null

Returns:T

the first argument if it is non-null and otherwise the second argument if it is non-null

Exceptions
NullPointerException:
if both obj is null and defaultObj is null
Since
9
requireNonNullElseGetback to summary
public static <T> T requireNonNullElseGet(T obj, Supplier<? extends T> supplier)

Returns the first argument if it is non-null and otherwise the value from supplier.get() if it is non-null.

Parameters
<T>
the type of the first argument and return type
obj:T

an object

supplier:Supplier<? extends T>

of a non-null object to return if the first argument is null

Returns:T

the first argument if it is non-null and otherwise the value from supplier.get() if it is non-null

Exceptions
NullPointerException:
if both obj is null and either the supplier is null or the supplier.get() value is null
Since
9
toIdentityStringback to summary
public static String toIdentityString(Object o)

Returns a string equivalent to the string returned by Object.toString if that method and hashCode are not overridden.

Implementation Note

This method constructs a string for an object without calling any overridable methods of the object.

Implementation Specification

The method returns a string equivalent to:
o.getClass().getName() + "@" + Integer.toHexString(System.identityHashCode(o))

Parameters
o:Object

an object

Returns:String

a string equivalent to the string returned by Object.toString if that method and hashCode are not overridden

Exceptions
NullPointerException:
if the argument is null
Since
19
See Also
Object#toString, System#identityHashCode(Object)
toStringback to summary
public static String toString(Object o)

Returns the result of calling toString for a non-null argument and "null" for a null argument.

Parameters
o:Object

an object

Returns:String

the result of calling toString for a non-null argument and "null" for a null argument

See Also
Object#toString, String#valueOf(Object)
toStringback to summary
public static String toString(Object o, String nullDefault)

Returns the result of calling toString on the first argument if the first argument is not null and the second argument otherwise.

Parameters
o:Object

an object

nullDefault:String

string to return if the first argument is null

Returns:String

the result of calling toString on the first argument if the first argument is not null and the second argument otherwise

See Also
Objects#toString(Object)