public class Checks extends Object
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.
All methods in this group start with the prefix "assert", and work similar to the assert
keyword.
null
.null
, an exception is thrown.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.
null
.null
, an exception is thrown.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"); ... }
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.
isNull(Object)
, isAnyNull(Object...)
, containsNull(Iterable)
simply
answer whether a null value could be found in the argument(s).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.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.
Constructor and Description |
---|
Checks() |
Modifier and Type | Method and Description |
---|---|
static <T,U> U |
applyIfNonNull(T value,
@NonNull Function<? super T,? extends U> function)
Apply the given function if and only if the given value is not
null . |
static <T,U> U |
applyIfNonNullElse(T value,
@NonNull Function<? super T,? extends U> function,
U fallbackValue)
Apply the given function if and only if the given value is not
null . |
static <T,U> U |
applyIfNonNullElseGet(T value,
@NonNull Function<? super T,? extends U> function,
@NonNull Supplier<? extends U> fallbackSupplier)
Apply the given function if and only if the given value is not
null . |
static <T> T |
asNullable(@NonNull Optional<T> optional)
Answer the value of an
Optional , or null if it has no value. |
static <T> void |
assertNonNull(T... values)
Checks whether any of the provided values is
null . |
static <T> void |
assertNonNullElements(@NonNull Iterable<T> values)
Checks whether any element in the provided values is
null . |
static <T> void |
assertNonNullElements(@NonNull Iterable<T> values,
String message)
Checks whether any of the provided values is
null . |
static <T> void |
assertNonNullWithMessage(String message,
T... values)
Checks whether any of the provided values is
null . |
static boolean |
containsNull(@NonNull Iterable<?> values)
Answer whether an element in the provided values is
null . |
static <T> void |
ifNonNull(T value,
@NonNull Consumer<? super T> consumer)
Invoke the given consumer if and only if the given value is not
null . |
static <T> boolean |
isAnyNull(T... values)
Answer whether any of the given values is
null . |
static boolean |
isNull(@NonNull Object value)
Answer whether the given value is
null . |
static <T> T |
nonNullElse(T value,
T fallbackValue)
Answer the given value as a non-null value.
|
static <T> T |
nonNullElseGet(T value,
@NonNull Supplier<? extends T> fallbackSupplier)
Answer the given value as a non-null value.
|
static <C extends Collection<?>> |
requireNonEmpty(C value)
Answer the given value, guaranteeing it to be neither
null nor
an empty collection. |
static <C extends Collection<?>> |
requireNonEmpty(C value,
String message)
Answer the given value, guaranteeing it to be neither
null nor
an empty collection. |
static @NonNull String |
requireNonEmpty(@Nullable String value)
Answer the given value, guaranteeing it to be neither
null nor
an empty string. |
static @NonNull String |
requireNonEmpty(@Nullable String value,
String message)
Answer the given value, guaranteeing it to be neither
null nor
an empty string. |
static <T> T |
requireNonNull(T value)
Answer the given value as a non-null value.
|
static <T> T |
requireNonNull(T value,
@NonNull String message)
Answer the given value as a non-null value.
|
static boolean |
unboxElse(@Nullable Boolean boxedValue,
boolean fallbackValue)
Unbox the given 'boxedValue' if and only if it is not
null . |
static byte |
unboxElse(@Nullable Byte boxedValue,
byte fallbackValue)
Unbox the given 'boxedValue' if and only if it is not
null . |
static char |
unboxElse(@Nullable Character boxedValue,
char fallbackValue)
Unbox the given 'boxedValue' if and only if it is not
null . |
static double |
unboxElse(@Nullable Double boxedValue,
double fallbackValue)
Unbox the given 'boxedValue' if and only if it is not
null . |
static float |
unboxElse(@Nullable Float boxedValue,
float fallbackValue)
Unbox the given 'boxedValue' if and only if it is not
null . |
static int |
unboxElse(@Nullable Integer boxedValue,
int fallbackValue)
Unbox the given 'boxedValue' if and only if it is not
null . |
static long |
unboxElse(@Nullable Long boxedValue,
long fallbackValue)
Unbox the given 'boxedValue' if and only if it is not
null . |
static short |
unboxElse(@Nullable Short boxedValue,
short fallbackValue)
Unbox the given 'boxedValue' if and only if it is not
null . |
@SafeVarargs public static <T> void assertNonNull(T... values)
null
.values
- arbitrary values to be checkedNullPointerException
- if a null
was found among values.@SafeVarargs public static <T> void assertNonNullWithMessage(String message, T... values)
null
.message
- explanatory message to be used when throwing NullPointerException
.values
- arbitrary values to be checkedNullPointerException
- if a null
was found among values.public static <T> void assertNonNullElements(@NonNull Iterable<T> values)
null
.values
- an Iterable of arbitrary values to be checkedNullPointerException
- if a null
was found among the elements in values.public static <T> void assertNonNullElements(@NonNull Iterable<T> values, String message)
null
.values
- an iterable of arbitrary values to be checkedmessage
- explanatory message to be used when throwing NullPointerException
.NullPointerException
- if a null
was found among the elements in values.public static <T> T requireNonNull(T value)
NullPointerException
if the given value was null
.value
- an arbitrary value, maybe null
.null
.NullPointerException
- if the given value was null
.public static <T> T requireNonNull(T value, @NonNull String message)
NullPointerException
if the given value was null
.value
- an arbitrary value, maybe null
.message
- explanatory message to be used when throwing NullPointerException
.null
.NullPointerException
- if the given value was null
.public static @NonNull String requireNonEmpty(@Nullable String value)
null
nor
an empty string.value
- value to be checkednull
nor
and empty string.NullPointerException
- if the given value was null
IllegalArgumentException
- if the given value was an empty string.public static @NonNull String requireNonEmpty(@Nullable String value, String message)
null
nor
an empty string.value
- value to be checkedmessage
- explanatory message to be used when throwing an exception.null
nor
an empty string.NullPointerException
- if the given value was null
IllegalArgumentException
- if the given value was an empty string.public static <C extends Collection<?>> C requireNonEmpty(C value)
null
nor
an empty collection. This method doesn't make any statement about whether
or not elements in the collection can possibly be null
.value
- value to be checkednull
nor
an empty collection.NullPointerException
- if the given value was null
IllegalArgumentException
- if the given value was an empty collection.public static <C extends Collection<?>> C requireNonEmpty(C value, String message)
null
nor
an empty collection. This method doesn't make any statement about whether
or not elements in the collection can possibly be null
.value
- value to be checkedmessage
- explanatory message to be used when throwing an exception.null
nor
an empty collection.NullPointerException
- if the given value was null
IllegalArgumentException
- if the given value was an empty collection.public static boolean isNull(@NonNull Object value)
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.value
- an object which analysis at the call-site considers as non-nullnull
, else false.@SafeVarargs public static <T> boolean isAnyNull(T... values)
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.values
- arbitrary values to be checkednull
, else false.public static boolean containsNull(@NonNull Iterable<?> values)
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.values
- an iterable of arbitrary valuesnull
, else false.public static <T> T asNullable(@NonNull Optional<T> optional)
Optional
, or null
if it has no value.optional
- wrapper for an optional valuenull
.public static <T> T nonNullElse(T value, T fallbackValue)
null
the alternative 'fallbackValue' is returned.value
- an arbitrary value, maybe null
.fallbackValue
- value to be returned when the value is null
.null
, or the fallback value.public static <T> T nonNullElseGet(T value, @NonNull Supplier<? extends T> fallbackSupplier)
null
an alternative is computed by
invoking the given 'fallbackSupplier'.value
- an arbitrary value, maybe null
.fallbackSupplier
- will compute the value to be returned when the 'value' is null
.null
,
or a fallback value provided by the 'fallbackSupplier'.public static <T> void ifNonNull(T value, @NonNull Consumer<? super T> consumer)
null
.
Otherwise do nothing.value
- the value to be checked for null and possibly passed into the consumer.consumer
- the consumer to invoke after checking the value for null.public static <T,U> U applyIfNonNull(T value, @NonNull Function<? super T,? extends U> function)
null
.value
- the value to be checked for null
and possibly passed into the function.function
- the function to apply after checking the value for null
.null
if 'value' was null
public static <T,U> U applyIfNonNullElse(T value, @NonNull Function<? super T,? extends U> function, U fallbackValue)
null
.value
- the value to be checked for null
and possibly passed into the function.function
- the function to apply after checking the value for null
.fallbackValue
- value to be returned when the 'value' is null
.null
public static <T,U> U applyIfNonNullElseGet(T value, @NonNull Function<? super T,? extends U> function, @NonNull Supplier<? extends U> fallbackSupplier)
null
.value
- the value to be checked for null
and possibly passed into the function.function
- the function to apply after checking the value for null
.null
public static boolean unboxElse(@Nullable Boolean boxedValue, boolean fallbackValue)
null
.
Otherwise the given 'fallbackValue' is returned.boxedValue
- value, can be null
.fallbackValue
- the value to use if 'boxedValue' is null
null
.public static byte unboxElse(@Nullable Byte boxedValue, byte fallbackValue)
null
.
Otherwise the given 'fallbackValue' is returned.boxedValue
- value, can be null
.fallbackValue
- the value to use if 'boxedValue' is null
null
.public static char unboxElse(@Nullable Character boxedValue, char fallbackValue)
null
.
Otherwise the given 'fallbackValue' is returned.boxedValue
- value, can be null
.fallbackValue
- the value to use if 'boxedValue' is null
null
.public static int unboxElse(@Nullable Integer boxedValue, int fallbackValue)
null
.
Otherwise the given 'fallbackValue' is returned.boxedValue
- value, can be null
.fallbackValue
- the value to use if 'boxedValue' is null
null
.public static long unboxElse(@Nullable Long boxedValue, long fallbackValue)
null
.
Otherwise the given 'fallbackValue' is returned.boxedValue
- value, can be null
.fallbackValue
- the value to use if 'boxedValue' is null
null
.public static short unboxElse(@Nullable Short boxedValue, short fallbackValue)
null
.
Otherwise the given 'fallbackValue' is returned.boxedValue
- value, can be null
.fallbackValue
- the value to use if 'boxedValue' is null
null
.public static float unboxElse(@Nullable Float boxedValue, float fallbackValue)
null
.
Otherwise the given 'fallbackValue' is returned.boxedValue
- value, can be null
.fallbackValue
- the value to use if 'boxedValue' is null
null
.public static double unboxElse(@Nullable Double boxedValue, double fallbackValue)
null
.
Otherwise the given 'fallbackValue' is returned.boxedValue
- value, can be null
.fallbackValue
- the value to use if 'boxedValue' is null
null
.
Copyright (c) 2000, 2017 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.