Annotation Interface NonNull

@Documented @Target(TYPE_USE) @Retention(RUNTIME) public @interface NonNull
Indicates that the annotated type usage (commonly a parameter type or return type) is considered to exclude null as a value; rarely needed within null-marked code.

This annotation serves two primary purposes:

  • To mark any sporadic non-null type usages inside a scope that is not ready to be fully NullMarked yet.
  • To perform a non-null projection of a type variable, explained below.

For a comprehensive introduction to JSpecify, please see jspecify.org.

Non-null projection

In the following example, MyOptional's type parameter T accepts only non-null type arguments, but MyList's type parameter E will accept either a non-null or nullable type argument. 

// All the below is null-marked code

class MyOptional<T> { … }

interface MyList<E extends @Nullable Object> {
  // Returns the first non-null element, if such element exists.
  MyOptional<E> firstNonNull() { … } // problem here!
}

MyList<@Nullable String> maybeNulls = …
MyList<String> nonNulls = …

Because MyOptional accepts only non-null type arguments, we need both maybeNulls.firstNonNull() and nonNulls.firstNonNull() to produce the same return type: MyOptional!<String!> (see notation). However, as specified above, they won't do that. In fact, there is a problem with the firstNonNull signature, since the type argument String? would not meet the requirements of MyOptional's type parameter.

The solution is to project the type argument to its non-null counterpart: 

// Returns the first non-null element, if such element exists.
MyOptional<@NonNull E> firstNonNull() { … } // problem fixed!

Here, @NonNull E selects the non-null form of the type argument, whether it was already non-null or not, which is just what we need in this scenario.

If E has a non-null upper bound, then the apparent projection @NonNull E is redundant but harmless.

Nullable projection serves the equivalent purpose in the opposite direction, and is far more commonly useful.

If a type variable has all its usages being projected in one direction or the other, it should be given a non-null upper bound, and any non-null projections can then be removed.

Where it is applicable

@NonNull is applicable in all the same locations as Nullable.