Package 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 Details

    • Checks

      public Checks()

  • Method Details

    • assertNonNull

      @SafeVarargs public static <T> void assertNonNull(T @NonNull ... 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 @NonNull ... 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> @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 - 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> @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 - 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<?>> @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 - 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<?>> @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 - 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 @NonNull ... 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> @Nullable 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> @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 - 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> @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 - 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(@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 - 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<@NonNull ? 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(@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 - 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(@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 - 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.