org.eclipse.jdt.annotation

Class Checks

java.lang.Object

org.eclipse.jdt.annotation.Checks

public class Checks
extends java.lang.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 assert keyword.

• 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 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

Constructors

Constructor and Description
Checks()

Method Summary

Modifier and Type	Method and Description
static <T,U> U	applyIfNonNull(T value, @NonNull java.util.function.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 java.util.function.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 java.util.function.Function<? super T,? extends U> function, @NonNull java.util.function.Supplier<? extends U> fallbackSupplier) Apply the given function if and only if the given value is not null.
static <T> T	asNullable(@NonNull java.util.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 java.lang.Iterable<T> values) Checks whether any element in the provided values is null.
static <T> void	assertNonNullElements(@NonNull java.lang.Iterable<T> values, java.lang.String message) Checks whether any of the provided values is null.
static <T> void	assertNonNullWithMessage(java.lang.String message, T... values) Checks whether any of the provided values is null.
static boolean	containsNull(@NonNull java.lang.Iterable<?> values) Answer whether an element in the provided values is null.
static <T> void	ifNonNull(T value, @NonNull java.util.function.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 java.lang.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 java.util.function.Supplier<? extends T> fallbackSupplier) Answer the given value as a non-null value.
static <C extends java.util.Collection<?>> C	requireNonEmpty(C value) Answer the given value, guaranteeing it to be neither null nor an empty collection.
static <C extends java.util.Collection<?>> C	requireNonEmpty(C value, java.lang.String message) Answer the given value, guaranteeing it to be neither null nor an empty collection.
static @NonNull java.lang.String	requireNonEmpty(@Nullable java.lang.String value) Answer the given value, guaranteeing it to be neither null nor an empty string.
static @NonNull java.lang.String	requireNonEmpty(@Nullable java.lang.String value, java.lang.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 java.lang.String message) Answer the given value as a non-null value.
static boolean	unboxElse(@Nullable java.lang.Boolean boxedValue, boolean fallbackValue) Unbox the given 'boxedValue' if and only if it is not null.
static byte	unboxElse(@Nullable java.lang.Byte boxedValue, byte fallbackValue) Unbox the given 'boxedValue' if and only if it is not null.
static char	unboxElse(@Nullable java.lang.Character boxedValue, char fallbackValue) Unbox the given 'boxedValue' if and only if it is not null.
static double	unboxElse(@Nullable java.lang.Double boxedValue, double fallbackValue) Unbox the given 'boxedValue' if and only if it is not null.
static float	unboxElse(@Nullable java.lang.Float boxedValue, float fallbackValue) Unbox the given 'boxedValue' if and only if it is not null.
static int	unboxElse(@Nullable java.lang.Integer boxedValue, int fallbackValue) Unbox the given 'boxedValue' if and only if it is not null.
static long	unboxElse(@Nullable java.lang.Long boxedValue, long fallbackValue) Unbox the given 'boxedValue' if and only if it is not null.
static short	unboxElse(@Nullable java.lang.Short boxedValue, short fallbackValue) Unbox the given 'boxedValue' if and only if it is not null.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Checks

public Checks()

Method Detail

assertNonNull

@SafeVarargs
public static <T> void assertNonNull(T... values)

Checks whether any of the provided values is null.

Parameters:

values - arbitrary values to be checked

Throws:

java.lang.NullPointerException - if a null was found among values.

assertNonNullWithMessage

@SafeVarargs
public static <T> void assertNonNullWithMessage(java.lang.String message,
                                                             T... values)

Checks whether any of the provided values is null.

Parameters:

message - explanatory message to be used when throwing NullPointerException.

values - arbitrary values to be checked

Throws:

java.lang.NullPointerException - if a null was found among values.

assertNonNullElements

public static <T> void assertNonNullElements(@NonNull java.lang.Iterable<T> values)

Checks whether any element in the provided values is null.

Parameters:

values - an Iterable of arbitrary values to be checked

Throws:

java.lang.NullPointerException - if a null was found among the elements in values.

assertNonNullElements

public static <T> void assertNonNullElements(@NonNull java.lang.Iterable<T> values,
                                             java.lang.String message)

Checks whether any of the provided values is null.

Parameters:

values - an iterable of arbitrary values to be checked

message - explanatory message to be used when throwing NullPointerException.

Throws:

java.lang.NullPointerException - if a null was found among the elements in values.

requireNonNull

public static <T> T requireNonNull(T value)

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

Parameters:

value - an arbitrary value, maybe null.

Returns:

the original passed value, guaranteed not to be null.

Throws:

java.lang.NullPointerException - if the given value was null.

requireNonNull

public static <T> T requireNonNull(T value,
                                   @NonNull java.lang.String message)

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

Parameters:

value - an arbitrary value, maybe null.

message - explanatory message to be used when throwing NullPointerException.

Returns:

the original passed value, guaranteed not to be null.

Throws:

java.lang.NullPointerException - if the given value was null.

requireNonEmpty

public static @NonNull java.lang.String requireNonEmpty(@Nullable java.lang.String value)

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

Parameters:

value - value to be checked

Returns:

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

Throws:

java.lang.NullPointerException - if the given value was null

java.lang.IllegalArgumentException - if the given value was an empty string.

requireNonEmpty

public static @NonNull java.lang.String requireNonEmpty(@Nullable java.lang.String value,
                                                        java.lang.String message)

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

Parameters:

value - value to be checked

message - explanatory message to be used when throwing an exception.

Returns:

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

Throws:

java.lang.NullPointerException - if the given value was null

java.lang.IllegalArgumentException - if the given value was an empty string.

requireNonEmpty

public static <C extends java.util.Collection<?>> C requireNonEmpty(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 - value to be checked

Returns:

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

Throws:

java.lang.NullPointerException - if the given value was null

java.lang.IllegalArgumentException - if the given value was an empty collection.

requireNonEmpty

public static <C extends java.util.Collection<?>> C requireNonEmpty(C value,
                                                                    java.lang.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 - value to be checked

message - explanatory message to be used when throwing an exception.

Returns:

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

Throws:

java.lang.NullPointerException - if the given value was null

java.lang.IllegalArgumentException - if the given value was an empty collection.

isNull

public static boolean isNull(@NonNull java.lang.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 - 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... 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 - arbitrary values to be checked

Returns:

true if the argument is null, else false.

containsNull

public static boolean containsNull(@NonNull java.lang.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 - an iterable of arbitrary values

Returns:

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

asNullable

public static <T> T asNullable(@NonNull java.util.Optional<T> optional)

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

Parameters:

optional - wrapper for an optional value

Returns:

the value or null.

nonNullElse

public static <T> T nonNullElse(T value,
                                T fallbackValue)

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

Parameters:

value - an arbitrary value, maybe null.

fallbackValue - value to be returned when the value is null.

Returns:

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

nonNullElseGet

public static <T> T nonNullElseGet(T value,
                                   @NonNull java.util.function.Supplier<? extends 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 - an arbitrary value, maybe null.

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

Returns:

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

ifNonNull

public static <T> void ifNonNull(T value,
                                 @NonNull java.util.function.Consumer<? super T> consumer)

Invoke the given consumer if and only if the given value is not null. 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> U applyIfNonNull(T value,
                                     @NonNull java.util.function.Function<? super T,? extends U> function)

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

Parameters:

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.

Returns:

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

applyIfNonNullElse

public static <T,U> U applyIfNonNullElse(T value,
                                         @NonNull java.util.function.Function<? super T,? extends U> function,
                                         U fallbackValue)

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

Parameters:

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.

Returns:

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

applyIfNonNullElseGet

public static <T,U> U applyIfNonNullElseGet(T value,
                                            @NonNull java.util.function.Function<? super T,? extends U> function,
                                            @NonNull java.util.function.Supplier<? extends U> fallbackSupplier)

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

Parameters:

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.

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 java.lang.Boolean boxedValue,
                                boolean fallbackValue)

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

Parameters:

boxedValue - value, can be null.

fallbackValue - the value to use if 'boxedValue' is null

Returns:

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

unboxElse

public static byte unboxElse(@Nullable java.lang.Byte boxedValue,
                             byte fallbackValue)

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

Parameters:

boxedValue - value, can be null.

fallbackValue - the value to use if 'boxedValue' is null

Returns:

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

unboxElse

public static char unboxElse(@Nullable java.lang.Character boxedValue,
                             char fallbackValue)

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

Parameters:

boxedValue - value, can be null.

fallbackValue - the value to use if 'boxedValue' is null

Returns:

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

unboxElse

public static int unboxElse(@Nullable java.lang.Integer boxedValue,
                            int fallbackValue)

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

Parameters:

boxedValue - value, can be null.

fallbackValue - the value to use if 'boxedValue' is null

Returns:

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

unboxElse

public static long unboxElse(@Nullable java.lang.Long boxedValue,
                             long fallbackValue)

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

Parameters:

boxedValue - value, can be null.

fallbackValue - the value to use if 'boxedValue' is null

Returns:

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

unboxElse

public static short unboxElse(@Nullable java.lang.Short boxedValue,
                              short fallbackValue)

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

Parameters:

boxedValue - value, can be null.

fallbackValue - the value to use if 'boxedValue' is null

Returns:

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

unboxElse

public static float unboxElse(@Nullable java.lang.Float boxedValue,
                              float fallbackValue)

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

Parameters:

boxedValue - value, can be null.

fallbackValue - the value to use if 'boxedValue' is null

Returns:

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

unboxElse

public static double unboxElse(@Nullable java.lang.Double boxedValue,
                               double fallbackValue)

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

Parameters:

boxedValue - value, can be null.

fallbackValue - the value to use if 'boxedValue' is null

Returns:

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