org.eclipse.jdt.annotation

## 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 `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

All Methods Static Methods Concrete Methods
`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<?>> C` `requireNonEmpty(C value)` Answer the given value, guaranteeing it to be neither `null` nor an empty collection.
`static <C extends Collection<?>> C` `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`.

### 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:
  `NullPointerException` - if a `null` was found among values.

#### assertNonNullWithMessage

    @SafeVarargs
    public static <T> void assertNonNullWithMessage(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:
  `NullPointerException` - if a `null` was found among values.

#### assertNonNullElements

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

Checks whether any element in the provided values is `null`.

Parameters:
  `values` - an Iterable of arbitrary values to be checked
Throws:
  `NullPointerException` - if a `null` was 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 is `null`.

Parameters:
  `values` - an iterable of arbitrary values to be checked
  `message` - explanatory message to be used when throwing `NullPointerException`.
Throws:
  `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:
  `NullPointerException` - if the given value was `null`.

#### requireNonNull

    public static <T> T requireNonNull(T value,
                                       @NonNull 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:
  `NullPointerException` - if the given value was `null`.

#### requireNonEmpty

    public static @NonNull String requireNonEmpty(@Nullable 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:
  `NullPointerException` - if the given value was `null`
  `IllegalArgumentException` - 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 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:
  `NullPointerException` - if the given value was `null`
  `IllegalArgumentException` - if the given value was an empty string.

#### requireNonEmpty

    public static <C extends 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:
  `NullPointerException` - if the given value was `null`
  `IllegalArgumentException` - if the given value was an empty collection.

#### requireNonEmpty

    public static <C extends Collection<?>> C requireNonEmpty(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` - 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:
  `NullPointerException` - if the given value was `null`
  `IllegalArgumentException` - if the given value was an empty collection.

#### isNull

    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` - 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 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 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 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 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 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 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 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`.

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 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 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 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 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 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 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 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 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`.