Class Checks
- java.lang.Object
-
- org.eclipse.jdt.annotation.Checks
-
public class Checks extends Object
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
assertkeyword.- One or more values are checked for
null. - If any value is
null, an exception is thrown. - The method has no other effect (except for potential side effects in an Iterator).
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.
- One or more values are checked for
null. - If any value is
null, an exception is thrown. - Otherwise a guaranteed non-null value is returned.
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 theunboxElse(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)andapplyIfNonNullElseGet(Object, Function, Supplier)feed unsafe values into a given functional expression in a null-safe way.
- Since:
- 2.1
- One or more values are checked for
-
-
Constructor Summary
Constructors Constructor Description Checks()
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static <T,U>
@Nullable UapplyIfNonNull(@Nullable T value, @NonNull Function<? super T,? extends U> function)Apply the given function if and only if the given value is notnull.static <T,U>
UapplyIfNonNullElse(@Nullable T value, @NonNull Function<? super T,? extends U> function, U fallbackValue)Apply the given function if and only if the given value is notnull.static <T,U>
UapplyIfNonNullElseGet(@Nullable 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 notnull.static <T> @Nullable TasNullable(@NonNull Optional<T> optional)Answer the value of anOptional, ornullif it has no value.static <T> voidassertNonNull(T @NonNull ... values)Checks whether any of the provided values isnull.static <T> voidassertNonNullElements(@NonNull Iterable<T> values)Checks whether any element in the provided values isnull.static <T> voidassertNonNullElements(@NonNull Iterable<T> values, String message)Checks whether any of the provided values isnull.static <T> voidassertNonNullWithMessage(String message, T @NonNull ... values)Checks whether any of the provided values isnull.static booleancontainsNull(@NonNull Iterable<?> values)Answer whether an element in the provided values isnull.static <T> voidifNonNull(@Nullable T value, @NonNull Consumer<? super T> consumer)Invoke the given consumer if and only if the given value is notnull.static <T> booleanisAnyNull(T @NonNull ... values)Answer whether any of the given values isnull.static booleanisNull(@NonNull Object value)Answer whether the given value isnull.static <T> @NonNull TnonNullElse(@Nullable T value, @NonNull T fallbackValue)Answer the given value as a non-null value.static <T> @NonNull TnonNullElseGet(@Nullable T value, @NonNull Supplier<? extends @NonNull T> fallbackSupplier)Answer the given value as a non-null value.static <C extends Collection<?>>
@NonNull CrequireNonEmpty(@Nullable C value)Answer the given value, guaranteeing it to be neithernullnor an empty collection.static <C extends Collection<?>>
@NonNull CrequireNonEmpty(@Nullable C value, String message)Answer the given value, guaranteeing it to be neithernullnor an empty collection.static @NonNull StringrequireNonEmpty(@Nullable String value)Answer the given value, guaranteeing it to be neithernullnor an empty string.static @NonNull StringrequireNonEmpty(@Nullable String value, String message)Answer the given value, guaranteeing it to be neithernullnor an empty string.static <T> @NonNull TrequireNonNull(@Nullable T value)Answer the given value as a non-null value.static <T> @NonNull TrequireNonNull(@Nullable T value, @NonNull String message)Answer the given value as a non-null value.static booleanunboxElse(@Nullable Boolean boxedValue, boolean fallbackValue)Unbox the given 'boxedValue' if and only if it is notnull.static byteunboxElse(@Nullable Byte boxedValue, byte fallbackValue)Unbox the given 'boxedValue' if and only if it is notnull.static charunboxElse(@Nullable Character boxedValue, char fallbackValue)Unbox the given 'boxedValue' if and only if it is notnull.static doubleunboxElse(@Nullable Double boxedValue, double fallbackValue)Unbox the given 'boxedValue' if and only if it is notnull.static floatunboxElse(@Nullable Float boxedValue, float fallbackValue)Unbox the given 'boxedValue' if and only if it is notnull.static intunboxElse(@Nullable Integer boxedValue, int fallbackValue)Unbox the given 'boxedValue' if and only if it is notnull.static longunboxElse(@Nullable Long boxedValue, long fallbackValue)Unbox the given 'boxedValue' if and only if it is notnull.static shortunboxElse(@Nullable Short boxedValue, short fallbackValue)Unbox the given 'boxedValue' if and only if it is notnull.
-
-
-
Method Detail
-
assertNonNull
@SafeVarargs public static <T> void assertNonNull(T @NonNull ... values)
Checks whether any of the provided values isnull.- Parameters:
values- arbitrary values to be checked- Throws:
NullPointerException- if anullwas found among values.
-
assertNonNullWithMessage
@SafeVarargs public static <T> void assertNonNullWithMessage(String message, T @NonNull ... values)
Checks whether any of the provided values isnull.- Parameters:
message- explanatory message to be used when throwingNullPointerException.values- arbitrary values to be checked- Throws:
NullPointerException- if anullwas found among values.
-
assertNonNullElements
public static <T> void assertNonNullElements(@NonNull Iterable<T> values)
Checks whether any element in the provided values isnull.- Parameters:
values- an Iterable of arbitrary values to be checked- Throws:
NullPointerException- if anullwas found among the elements in values.
-
assertNonNullElements
public static <T> void assertNonNullElements(@NonNull Iterable<T> values, String message)
Checks whether any of the provided values isnull.- Parameters:
values- an iterable of arbitrary values to be checkedmessage- explanatory message to be used when throwingNullPointerException.- Throws:
NullPointerException- if anullwas found among the elements in values.
-
requireNonNull
public static <T> @NonNull T requireNonNull(@Nullable T value)
Answer the given value as a non-null value. ThrowsNullPointerExceptionif the given value wasnull.- Parameters:
value- an arbitrary value, maybenull.- Returns:
- the original passed value, guaranteed not to be
null. - Throws:
NullPointerException- if the given value wasnull.
-
requireNonNull
public static <T> @NonNull T requireNonNull(@Nullable T value, @NonNull String message)
Answer the given value as a non-null value. ThrowsNullPointerExceptionif the given value wasnull.- Parameters:
value- an arbitrary value, maybenull.message- explanatory message to be used when throwingNullPointerException.- Returns:
- the original passed value, guaranteed not to be
null. - Throws:
NullPointerException- if the given value wasnull.
-
requireNonEmpty
public static @NonNull String requireNonEmpty(@Nullable String value)
Answer the given value, guaranteeing it to be neithernullnor an empty string.- Parameters:
value- value to be checked- Returns:
- the given value, guaranteed to be neither
nullnor and empty string. - Throws:
NullPointerException- if the given value wasnullIllegalArgumentException- if the given value was an empty string.
-
requireNonEmpty
public static @NonNull String requireNonEmpty(@Nullable String value, String message)
Answer the given value, guaranteeing it to be neithernullnor an empty string.- Parameters:
value- value to be checkedmessage- explanatory message to be used when throwing an exception.- Returns:
- the given value, guaranteed to be neither
nullnor an empty string. - Throws:
NullPointerException- if the given value wasnullIllegalArgumentException- if the given value was an empty string.
-
requireNonEmpty
public static <C extends Collection<?>> @NonNull C requireNonEmpty(@Nullable C value)
Answer the given value, guaranteeing it to be neithernullnor an empty collection. This method doesn't make any statement about whether or not elements in the collection can possibly benull.- Parameters:
value- value to be checked- Returns:
- the given value, guaranteed to be neither
nullnor an empty collection. - Throws:
NullPointerException- if the given value wasnullIllegalArgumentException- if the given value was an empty collection.
-
requireNonEmpty
public static <C extends Collection<?>> @NonNull C requireNonEmpty(@Nullable C value, String message)
Answer the given value, guaranteeing it to be neithernullnor an empty collection. This method doesn't make any statement about whether or not elements in the collection can possibly benull.- Parameters:
value- value to be checkedmessage- explanatory message to be used when throwing an exception.- Returns:
- the given value, guaranteed to be neither
nullnor an empty collection. - Throws:
NullPointerException- if the given value wasnullIllegalArgumentException- if the given value was an empty collection.
-
isNull
public static boolean isNull(@NonNull Object value)
Answer whether the given value isnull. 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- an object which analysis at the call-site considers as non-null- Returns:
- true if the argument is
null, else false.
-
isAnyNull
@SafeVarargs public static <T> boolean isAnyNull(T @NonNull ... values)
Answer whether any of the given values isnull. Depending on the nullness of concrete types forT, this method may or may not be redundant from the point of view of static analysis.- Parameters:
values- arbitrary values to be checked- Returns:
- true if the argument is
null, else false.
-
containsNull
public static boolean containsNull(@NonNull Iterable<?> values)
Answer whether an element in the provided values isnull. Depending on the nullness of the givenIterable's type argument, this method may or may not be redundant from the point of view of static analysis.- Parameters:
values- an iterable of arbitrary values- Returns:
- true if the argument contains the value
null, else false.
-
asNullable
public static <T> @Nullable T asNullable(@NonNull Optional<T> optional)
Answer the value of anOptional, ornullif it has no value.- Parameters:
optional- wrapper for an optional value- Returns:
- the value or
null.
-
nonNullElse
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 actuallynullthe alternative 'fallbackValue' is returned.- Parameters:
value- an arbitrary value, maybenull.fallbackValue- value to be returned when the value isnull.- Returns:
- the original passed value, guaranteed not to be
null, or the fallback value.
-
nonNullElseGet
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 actuallynullan alternative is computed by invoking the given 'fallbackSupplier'.- Parameters:
value- an arbitrary value, maybenull.fallbackSupplier- will compute the value to be returned when the 'value' isnull.- Returns:
- the original passed value, guaranteed not to be
null, or a fallback value provided by the 'fallbackSupplier'.
-
ifNonNull
public static <T> void ifNonNull(@Nullable T value, @NonNull Consumer<? super T> consumer)
Invoke the given consumer if and only if the given value is notnull. Otherwise do nothing.- Parameters:
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.
-
applyIfNonNull
public static <T,U> @Nullable U applyIfNonNull(@Nullable T value, @NonNull Function<? super T,? extends U> function)
Apply the given function if and only if the given value is notnull.- Parameters:
value- the value to be checked fornulland possibly passed into the function.function- the function to apply after checking the value fornull.- Returns:
- the result of applying 'function' with 'value',
or
nullif 'value' wasnull
-
applyIfNonNullElse
public static <T,U> U applyIfNonNullElse(@Nullable T value, @NonNull Function<? super T,? extends U> function, U fallbackValue)
Apply the given function if and only if the given value is notnull.- Parameters:
value- the value to be checked fornulland possibly passed into the function.function- the function to apply after checking the value fornull.fallbackValue- value to be returned when the 'value' isnull.- Returns:
- the result of applying 'function' with 'value',
or the 'fallbackValue' if 'value' was
null
-
applyIfNonNullElseGet
public static <T,U> U applyIfNonNullElseGet(@Nullable 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 notnull.- Parameters:
value- the value to be checked fornulland possibly passed into the function.function- the function to apply after checking the value fornull.- Returns:
- the result of applying 'function' with 'value',
or a value provided by invoking 'fallbackSupplier' if 'value' was
null
-
unboxElse
public static boolean unboxElse(@Nullable Boolean boxedValue, boolean fallbackValue)
Unbox the given 'boxedValue' if and only if it is notnull. Otherwise the given 'fallbackValue' is returned.- Parameters:
boxedValue- value, can benull.fallbackValue- the value to use if 'boxedValue' isnull- Returns:
- either the unboxed boolean corresponding to 'boxedValue' or
'fallbackValue' if 'boxedValue' was
null.
-
unboxElse
public static byte unboxElse(@Nullable Byte boxedValue, byte fallbackValue)
Unbox the given 'boxedValue' if and only if it is notnull. Otherwise the given 'fallbackValue' is returned.- Parameters:
boxedValue- value, can benull.fallbackValue- the value to use if 'boxedValue' isnull- Returns:
- either the unboxed byte corresponding to 'boxedValue' or
'fallbackValue' if 'boxedValue' was
null.
-
unboxElse
public static char unboxElse(@Nullable Character boxedValue, char fallbackValue)
Unbox the given 'boxedValue' if and only if it is notnull. Otherwise the given 'fallbackValue' is returned.- Parameters:
boxedValue- value, can benull.fallbackValue- the value to use if 'boxedValue' isnull- Returns:
- either the unboxed char corresponding to 'boxedValue' or
'fallbackValue' if 'boxedValue' was
null.
-
unboxElse
public static int unboxElse(@Nullable Integer boxedValue, int fallbackValue)
Unbox the given 'boxedValue' if and only if it is notnull. Otherwise the given 'fallbackValue' is returned.- Parameters:
boxedValue- value, can benull.fallbackValue- the value to use if 'boxedValue' isnull- Returns:
- either the unboxed int corresponding to 'boxedValue' or
'fallbackValue' if 'boxedValue' was
null.
-
unboxElse
public static long unboxElse(@Nullable Long boxedValue, long fallbackValue)
Unbox the given 'boxedValue' if and only if it is notnull. Otherwise the given 'fallbackValue' is returned.- Parameters:
boxedValue- value, can benull.fallbackValue- the value to use if 'boxedValue' isnull- Returns:
- either the unboxed long corresponding to 'boxedValue' or
'fallbackValue' if 'boxedValue' was
null.
-
unboxElse
public static short unboxElse(@Nullable Short boxedValue, short fallbackValue)
Unbox the given 'boxedValue' if and only if it is notnull. Otherwise the given 'fallbackValue' is returned.- Parameters:
boxedValue- value, can benull.fallbackValue- the value to use if 'boxedValue' isnull- Returns:
- either the unboxed short corresponding to 'boxedValue' or
'fallbackValue' if 'boxedValue' was
null.
-
unboxElse
public static float unboxElse(@Nullable Float boxedValue, float fallbackValue)
Unbox the given 'boxedValue' if and only if it is notnull. Otherwise the given 'fallbackValue' is returned.- Parameters:
boxedValue- value, can benull.fallbackValue- the value to use if 'boxedValue' isnull- Returns:
- either the unboxed float corresponding to 'boxedValue' or
'fallbackValue' if 'boxedValue' was
null.
-
unboxElse
public static double unboxElse(@Nullable Double boxedValue, double fallbackValue)
Unbox the given 'boxedValue' if and only if it is notnull. Otherwise the given 'fallbackValue' is returned.- Parameters:
boxedValue- value, can benull.fallbackValue- the value to use if 'boxedValue' isnull- Returns:
- either the unboxed double corresponding to 'boxedValue' or
'fallbackValue' if 'boxedValue' was
null.
-
-