Top Description Constructors Methods
org.eclipse.jdt.annotation

public Class Checks

extends Object
Class Inheritance
Imports
java.util.Collection, .Optional, java.util.function.Consumer, .Function, .Supplier
Utility functions intended for use with the null annotations defined in this package.

For maximum generality, all type parameters of methods in this class are not constraint to either non-null nor nullable. Users of these methods can freely choose these types.

Methods in this class come in three groups: Assertions, Requirements, as well as Queries, conversions and computations.

Assertions

All methods in this group start with the prefix "assert", and work similar to the assert keyword.

Requirements

All methods in this group start with the prefix "require". They encode domain knowledge of the developer and make this knowledge visible to static null analysis.

For Strings and Collections additional checks for empty may be included.

Typical usage includes the case of interfacing with legacy API, that is not specified using null annotations, but where corresponding guarantees are given informally: 

 interface LegacyThing {
 	/** @return the name of this thing, never <code>null</code>. */
 	String getName();
 }
 ...
 public void process(@NonNull LegacyThing t) {
	@NonNull String name = Checks.requireNonNull(t.getName(), "LegacyThing is supposed to have a name");
 	...
 }

Queries, conversions and computations

A commonality among methods in this group is the null-safety that can be verified by static null analysis, hence in a fully analyzed program none of these methods should throw an exception.

boolean queries
Methods isNull(Object), isAnyNull(Object...), containsNull(Iterable) simply answer whether a null value could be found in the argument(s).
conversions
Methods nonNullElse(Object, Object), nonNullElseGet(Object, Supplier), asNullable(Optional) and the unboxElse(Boolean, boolean) family of methods provide null-safe conversions, which can be checked by static analysis.
computations
Methods ifNonNull(Object, Consumer), applyIfNonNull(Object, Function), applyIfNonNullElse(Object, Function, Object) and applyIfNonNullElseGet(Object, Function, Supplier) feed unsafe values into a given functional expression in a null-safe way.
Since
2.1

Constructor Summary

AccessConstructor and Description
public
Checks()

Method Summary

Modifier and TypeMethod and Description
public static <T, U> @Nullable U

Returns:

the result of applying 'function' with 'value', or null if 'value' was null
applyIfNonNull(@Nullable T
the value to be checked for null and possibly passed into the function.
value, @NonNull Function<@NonNull ? super T, ? extends U>
the function to apply after checking the value for null.
function)

Apply the given function if and only if the given value is not null.

public static <T, U> U

Returns:

the result of applying 'function' with 'value', or the 'fallbackValue' if 'value' was null
applyIfNonNullElse(@Nullable T
the value to be checked for null and possibly passed into the function.
value, @NonNull Function<@NonNull ? super T, ? extends U>
the function to apply after checking the value for null.
function, U
value to be returned when the 'value' is null.
fallbackValue)

Apply the given function if and only if the given value is not null.

public static <T, U> U

Returns:

the result of applying 'function' with 'value', or a value provided by invoking 'fallbackSupplier' if 'value' was null
applyIfNonNullElseGet(@Nullable T
the value to be checked for null and possibly passed into the function.
value, @NonNull Function<@NonNull ? super T, ? extends U>
the function to apply after checking the value for null.
function, @NonNull Supplier<? extends U> fallbackSupplier)

Apply the given function if and only if the given value is not null.

public static <T> @Nullable T

Returns:

the value or null.
asNullable(@NonNull Optional<T>
wrapper for an optional value
optional)

Answer the value of an Optional, or null if it has no value.

public static <T> void
assertNonNull(@NonNull T...
arbitrary values to be checked
values)

Checks whether any of the provided values is null.

public static <T> void
assertNonNullElements(@NonNull Iterable<T>
an Iterable of arbitrary values to be checked
values)

Checks whether any element in the provided values is null.

public static <T> void
assertNonNullElements(@NonNull Iterable<T>
an iterable of arbitrary values to be checked
values, String
explanatory message to be used when throwing NullPointerException.
message)

Checks whether any of the provided values is null.

public static <T> void
assertNonNullWithMessage(String
explanatory message to be used when throwing NullPointerException.
message, @NonNull T...
arbitrary values to be checked
values)

Checks whether any of the provided values is null.

public static boolean

Returns:

true if the argument contains the value null, else false.
containsNull(@NonNull Iterable<?>
an iterable of arbitrary values
values)

Answer whether an element in the provided values is null.

public static <T> void
ifNonNull(@Nullable T
the value to be checked for null and possibly passed into the consumer.
value, @NonNull Consumer<@NonNull ? super T>
the consumer to invoke after checking the value for null.
consumer)

Invoke the given consumer if and only if the given value is not null.

public static <T> boolean

Returns:

true if the argument is null, else false.
isAnyNull(@NonNull T...
arbitrary values to be checked
values)

Answer whether any of the given values is null.

public static boolean

Returns:

true if the argument is null, else false.
isNull(@NonNull Object
an object which analysis at the call-site considers as non-null
value)

Answer whether the given value is null.

public static <T> @NonNull T

Returns:

the original passed value, guaranteed not to be null, or the fallback value.
nonNullElse(@Nullable T
an arbitrary value, maybe null.
value, @NonNull T
value to be returned when the value is null.
fallbackValue)

Answer the given value as a non-null value.

public static <T> @NonNull T

Returns:

the original passed value, guaranteed not to be null, or a fallback value provided by the 'fallbackSupplier'.
nonNullElseGet(@Nullable T
an arbitrary value, maybe null.
value, @NonNull Supplier<? extends @NonNull T>
will compute the value to be returned when the 'value' is null.
fallbackSupplier)

Answer the given value as a non-null value.

public static @NonNull String

Returns:

the given value, guaranteed to be neither null nor and empty string.
requireNonEmpty(@Nullable String
value to be checked
value)

Answer the given value, guaranteeing it to be neither null nor an empty string.

public static @NonNull String

Returns:

the given value, guaranteed to be neither null nor an empty string.
requireNonEmpty(@Nullable String
value to be checked
value, String
explanatory message to be used when throwing an exception.
message)

Answer the given value, guaranteeing it to be neither null nor an empty string.

public static <C extends Collection<?>> @NonNull C

Returns:

the given value, guaranteed to be neither null nor an empty collection.
requireNonEmpty(@Nullable C
value to be checked
value)

Answer the given value, guaranteeing it to be neither null nor an empty collection.

public static <C extends Collection<?>> @NonNull C

Returns:

the given value, guaranteed to be neither null nor an empty collection.
requireNonEmpty(@Nullable C
value to be checked
value, String
explanatory message to be used when throwing an exception.
message)

Answer the given value, guaranteeing it to be neither null nor an empty collection.

public static <T> @NonNull T

Returns:

the original passed value, guaranteed not to be null.
requireNonNull(@Nullable T
an arbitrary value, maybe null.
value)

Answer the given value as a non-null value.

public static <T> @NonNull T

Returns:

the original passed value, guaranteed not to be null.
requireNonNull(@Nullable T
an arbitrary value, maybe null.
value, @NonNull String
explanatory message to be used when throwing NullPointerException.
message)

Answer the given value as a non-null value.

public static boolean

Returns:

either the unboxed boolean corresponding to 'boxedValue' or 'fallbackValue' if 'boxedValue' was null.
unboxElse(@Nullable Boolean
value, can be null.
boxedValue, boolean
the value to use if 'boxedValue' is null
fallbackValue)

Unbox the given 'boxedValue' if and only if it is not null.

public static byte

Returns:

either the unboxed byte corresponding to 'boxedValue' or 'fallbackValue' if 'boxedValue' was null.
unboxElse(@Nullable Byte
value, can be null.
boxedValue, byte
the value to use if 'boxedValue' is null
fallbackValue)

Unbox the given 'boxedValue' if and only if it is not null.

public static char

Returns:

either the unboxed char corresponding to 'boxedValue' or 'fallbackValue' if 'boxedValue' was null.
unboxElse(@Nullable Character
value, can be null.
boxedValue, char
the value to use if 'boxedValue' is null
fallbackValue)

Unbox the given 'boxedValue' if and only if it is not null.

public static int

Returns:

either the unboxed int corresponding to 'boxedValue' or 'fallbackValue' if 'boxedValue' was null.
unboxElse(@Nullable Integer
value, can be null.
boxedValue, int
the value to use if 'boxedValue' is null
fallbackValue)

Unbox the given 'boxedValue' if and only if it is not null.

public static long

Returns:

either the unboxed long corresponding to 'boxedValue' or 'fallbackValue' if 'boxedValue' was null.
unboxElse(@Nullable Long
value, can be null.
boxedValue, long
the value to use if 'boxedValue' is null
fallbackValue)

Unbox the given 'boxedValue' if and only if it is not null.

public static short

Returns:

either the unboxed short corresponding to 'boxedValue' or 'fallbackValue' if 'boxedValue' was null.
unboxElse(@Nullable Short
value, can be null.
boxedValue, short
the value to use if 'boxedValue' is null
fallbackValue)

Unbox the given 'boxedValue' if and only if it is not null.

public static float

Returns:

either the unboxed float corresponding to 'boxedValue' or 'fallbackValue' if 'boxedValue' was null.
unboxElse(@Nullable Float
value, can be null.
boxedValue, float
the value to use if 'boxedValue' is null
fallbackValue)

Unbox the given 'boxedValue' if and only if it is not null.

public static double

Returns:

either the unboxed double corresponding to 'boxedValue' or 'fallbackValue' if 'boxedValue' was null.
unboxElse(@Nullable Double
value, can be null.
boxedValue, double
the value to use if 'boxedValue' is null
fallbackValue)

Unbox the given 'boxedValue' if and only if it is not null.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Constructor Detail

Checksback to summary
public Checks()

Method Detail

applyIfNonNullback to summary
public static <T, U> @Nullable U applyIfNonNull(@Nullable T value, @NonNull Function<@NonNull ? super T, ? extends U> function)

Apply the given function if and only if the given value is not null.

Parameters
value:@Nullable T

the value to be checked for null and possibly passed into the function.

function:@NonNull Function<@NonNull ? super T, ? extends U>

the function to apply after checking the value for null.

Returns:@Nullable U

the result of applying 'function' with 'value', or null if 'value' was null

applyIfNonNullElseback to summary
public static <T, U> U applyIfNonNullElse(@Nullable T value, @NonNull Function<@NonNull ? super T, ? extends U> function, U fallbackValue)

Apply the given function if and only if the given value is not null.

Parameters
value:@Nullable T

the value to be checked for null and possibly passed into the function.

function:@NonNull Function<@NonNull ? super T, ? extends U>

the function to apply after checking the value for null.

fallbackValue:U

value to be returned when the 'value' is null.

Returns:U

the result of applying 'function' with 'value', or the 'fallbackValue' if 'value' was null

applyIfNonNullElseGetback to summary
public static <T, U> U applyIfNonNullElseGet(@Nullable T value, @NonNull Function<@NonNull ? super T, ? extends U> function, @NonNull Supplier<? extends U> fallbackSupplier)

Apply the given function if and only if the given value is not null.

Parameters
value:@Nullable T

the value to be checked for null and possibly passed into the function.

function:@NonNull Function<@NonNull ? super T, ? extends U>

the function to apply after checking the value for null.

Returns:U

the result of applying 'function' with 'value', or a value provided by invoking 'fallbackSupplier' if 'value' was null

asNullableback to summary
public static <T> @Nullable T asNullable(@NonNull Optional<T> optional)

Answer the value of an Optional, or null if it has no value.

Parameters
optional:@NonNull Optional<T>

wrapper for an optional value

Returns:@Nullable T

the value or null.

assertNonNullback to summary
public static <T> void assertNonNull(@NonNull T... values)

Checks whether any of the provided values is null.

Parameters
values:@NonNull T[]

arbitrary values to be checked

Annotations
@SafeVarargs
Exceptions
NullPointerException:
if a null was found among values.
assertNonNullElementsback to summary
public static <T> void assertNonNullElements(@NonNull Iterable<T> values)

Checks whether any element in the provided values is null.

Parameters
values:@NonNull Iterable<T>

an Iterable of arbitrary values to be checked

Exceptions
NullPointerException:
if a null was found among the elements in values.
assertNonNullElementsback to summary
public static <T> void assertNonNullElements(@NonNull Iterable<T> values, String message)

Checks whether any of the provided values is null.

Parameters
values:@NonNull Iterable<T>

an iterable of arbitrary values to be checked

message:String

explanatory message to be used when throwing NullPointerException.

Exceptions
NullPointerException:
if a null was found among the elements in values.
assertNonNullWithMessageback to summary
public static <T> void assertNonNullWithMessage(String message, @NonNull T... values)

Checks whether any of the provided values is null.

Parameters
message:String

explanatory message to be used when throwing NullPointerException.

values:@NonNull T[]

arbitrary values to be checked

Annotations
@SafeVarargs
Exceptions
NullPointerException:
if a null was found among values.
containsNullback to summary
public static boolean containsNull(@NonNull Iterable<?> values)

Answer whether an element in the provided values is null. Depending on the nullness of the given Iterable's type argument, this method may or may not be redundant from the point of view of static analysis.

Parameters
values:@NonNull Iterable<?>

an iterable of arbitrary values

Returns:boolean

true if the argument contains the value null, else false.

ifNonNullback to summary
public static <T> void ifNonNull(@Nullable T value, @NonNull Consumer<@NonNull ? super T> consumer)

Invoke the given consumer if and only if the given value is not null. Otherwise do nothing.

Parameters
value:@Nullable T

the value to be checked for null and possibly passed into the consumer.

consumer:@NonNull Consumer<@NonNull ? super T>

the consumer to invoke after checking the value for null.

isAnyNullback to summary
public static <T> boolean isAnyNull(@NonNull T... values)

Answer whether any of the given values is null. Depending on the nullness of concrete types for T, this method may or may not be redundant from the point of view of static analysis.

Parameters
values:@NonNull T[]

arbitrary values to be checked

Returns:boolean

true if the argument is null, else false.

Annotations
@SafeVarargs
isNullback to summary
public static boolean isNull(@NonNull Object value)

Answer whether the given value is null. Calling this method should express that a null check is performed which the compiler would normally deem unnecessary or redundant. By calling this method, these warnings will be avoided, and readers of that code will be informed that the check is redundant with respect to null analysis, and done only as a measure for extra safety.

Parameters
value:@NonNull Object

an object which analysis at the call-site considers as non-null

Returns:boolean

true if the argument is null, else false.

Annotations
@SuppressWarnings:null
nonNullElseback to summary
public static <T> @NonNull T nonNullElse(@Nullable T value, @NonNull T fallbackValue)

Answer the given value as a non-null value. If the value was actually null the alternative 'fallbackValue' is returned.

Parameters
value:@Nullable T

an arbitrary value, maybe null.

fallbackValue:@NonNull T

value to be returned when the value is null.

Returns:@NonNull T

the original passed value, guaranteed not to be null, or the fallback value.

nonNullElseGetback to summary
public static <T> @NonNull T nonNullElseGet(@Nullable T value, @NonNull Supplier<? extends @NonNull T> fallbackSupplier)

Answer the given value as a non-null value. If the value was actually null an alternative is computed by invoking the given 'fallbackSupplier'.

Parameters
value:@Nullable T

an arbitrary value, maybe null.

fallbackSupplier:@NonNull Supplier<? extends @NonNull T>

will compute the value to be returned when the 'value' is null.

Returns:@NonNull T

the original passed value, guaranteed not to be null, or a fallback value provided by the 'fallbackSupplier'.

requireNonEmptyback to summary
public static @NonNull String requireNonEmpty(@Nullable String value)

Answer the given value, guaranteeing it to be neither null nor an empty string.

Parameters
value:@Nullable String

value to be checked

Returns:@NonNull String

the given value, guaranteed to be neither null nor and empty string.

Exceptions
NullPointerException:
if the given value was null
IllegalArgumentException:
if the given value was an empty string.
requireNonEmptyback to summary
public static @NonNull String requireNonEmpty(@Nullable String value, String message)

Answer the given value, guaranteeing it to be neither null nor an empty string.

Parameters
value:@Nullable String

value to be checked

message:String

explanatory message to be used when throwing an exception.

Returns:@NonNull String

the given value, guaranteed to be neither null nor an empty string.

Exceptions
NullPointerException:
if the given value was null
IllegalArgumentException:
if the given value was an empty string.
requireNonEmptyback to summary
public static <C extends Collection<?>> @NonNull C requireNonEmpty(@Nullable C value)

Answer the given value, guaranteeing it to be neither null nor an empty collection. This method doesn't make any statement about whether or not elements in the collection can possibly be null.

Parameters
value:@Nullable C

value to be checked

Returns:@NonNull C

the given value, guaranteed to be neither null nor an empty collection.

Exceptions
NullPointerException:
if the given value was null
IllegalArgumentException:
if the given value was an empty collection.
requireNonEmptyback to summary
public static <C extends Collection<?>> @NonNull C requireNonEmpty(@Nullable C value, String message)

Answer the given value, guaranteeing it to be neither null nor an empty collection. This method doesn't make any statement about whether or not elements in the collection can possibly be null.

Parameters
value:@Nullable C

value to be checked

message:String

explanatory message to be used when throwing an exception.

Returns:@NonNull C

the given value, guaranteed to be neither null nor an empty collection.

Exceptions
NullPointerException:
if the given value was null
IllegalArgumentException:
if the given value was an empty collection.
requireNonNullback to summary
public static <T> @NonNull T requireNonNull(@Nullable T value)

Answer the given value as a non-null value. Throws NullPointerException if the given value was null.

Parameters
value:@Nullable T

an arbitrary value, maybe null.

Returns:@NonNull T

the original passed value, guaranteed not to be null.

Exceptions
NullPointerException:
if the given value was null.
requireNonNullback to summary
public static <T> @NonNull T requireNonNull(@Nullable T value, @NonNull String message)

Answer the given value as a non-null value. Throws NullPointerException if the given value was null.

Parameters
value:@Nullable T

an arbitrary value, maybe null.

message:@NonNull String

explanatory message to be used when throwing NullPointerException.

Returns:@NonNull T

the original passed value, guaranteed not to be null.

Exceptions
NullPointerException:
if the given value was null.
unboxElseback to summary
public static boolean unboxElse(@Nullable Boolean boxedValue, boolean fallbackValue)

Unbox the given 'boxedValue' if and only if it is not null. Otherwise the given 'fallbackValue' is returned.

Parameters
boxedValue:@Nullable Boolean

value, can be null.

fallbackValue:boolean

the value to use if 'boxedValue' is null

Returns:boolean

either the unboxed boolean corresponding to 'boxedValue' or 'fallbackValue' if 'boxedValue' was null.

unboxElseback to summary
public static byte unboxElse(@Nullable Byte boxedValue, byte fallbackValue)

Unbox the given 'boxedValue' if and only if it is not null. Otherwise the given 'fallbackValue' is returned.

Parameters
boxedValue:@Nullable Byte

value, can be null.

fallbackValue:byte

the value to use if 'boxedValue' is null

Returns:byte

either the unboxed byte corresponding to 'boxedValue' or 'fallbackValue' if 'boxedValue' was null.

unboxElseback to summary
public static char unboxElse(@Nullable Character boxedValue, char fallbackValue)

Unbox the given 'boxedValue' if and only if it is not null. Otherwise the given 'fallbackValue' is returned.

Parameters
boxedValue:@Nullable Character

value, can be null.

fallbackValue:char

the value to use if 'boxedValue' is null

Returns:char

either the unboxed char corresponding to 'boxedValue' or 'fallbackValue' if 'boxedValue' was null.

unboxElseback to summary
public static int unboxElse(@Nullable Integer boxedValue, int fallbackValue)

Unbox the given 'boxedValue' if and only if it is not null. Otherwise the given 'fallbackValue' is returned.

Parameters
boxedValue:@Nullable Integer

value, can be null.

fallbackValue:int

the value to use if 'boxedValue' is null

Returns:int

either the unboxed int corresponding to 'boxedValue' or 'fallbackValue' if 'boxedValue' was null.

unboxElseback to summary
public static long unboxElse(@Nullable Long boxedValue, long fallbackValue)

Unbox the given 'boxedValue' if and only if it is not null. Otherwise the given 'fallbackValue' is returned.

Parameters
boxedValue:@Nullable Long

value, can be null.

fallbackValue:long

the value to use if 'boxedValue' is null

Returns:long

either the unboxed long corresponding to 'boxedValue' or 'fallbackValue' if 'boxedValue' was null.

unboxElseback to summary
public static short unboxElse(@Nullable Short boxedValue, short fallbackValue)

Unbox the given 'boxedValue' if and only if it is not null. Otherwise the given 'fallbackValue' is returned.

Parameters
boxedValue:@Nullable Short

value, can be null.

fallbackValue:short

the value to use if 'boxedValue' is null

Returns:short

either the unboxed short corresponding to 'boxedValue' or 'fallbackValue' if 'boxedValue' was null.

unboxElseback to summary
public static float unboxElse(@Nullable Float boxedValue, float fallbackValue)

Unbox the given 'boxedValue' if and only if it is not null. Otherwise the given 'fallbackValue' is returned.

Parameters
boxedValue:@Nullable Float

value, can be null.

fallbackValue:float

the value to use if 'boxedValue' is null

Returns:float

either the unboxed float corresponding to 'boxedValue' or 'fallbackValue' if 'boxedValue' was null.

unboxElseback to summary
public static double unboxElse(@Nullable Double boxedValue, double fallbackValue)

Unbox the given 'boxedValue' if and only if it is not null. Otherwise the given 'fallbackValue' is returned.

Parameters
boxedValue:@Nullable Double

value, can be null.

fallbackValue:double

the value to use if 'boxedValue' is null

Returns:double

either the unboxed double corresponding to 'boxedValue' or 'fallbackValue' if 'boxedValue' was null.