Annotation Interface ParametricNullness
@Retention(RUNTIME)
@Target({FIELD,METHOD,PARAMETER})
@TypeQualifierNickname
@Nonnull(when=UNKNOWN)
@interface ParametricNullness
Annotates a "top-level" type-variable usage that takes its nullness from the type argument
supplied by the user of the class. For example,
Multiset.Entry.getElement()
returns
@ParametricNullness E
, which means:
getElement
on aMultiset.Entry<@NonNull String>
returns@NonNull String
.getElement
on aMultiset.Entry<@Nullable String>
returns@Nullable String
.
- methods whose return type is a type variable but which can never return
null
, typically because the type forbids nullable type arguments: For example,ImmutableList.get
returnsE
, but that value is nevernull
. (Accordingly,ImmutableList
is declared to forbidImmutableList<@Nullable String>
.) - methods whose return type is a type variable but which can return
null
regardless of the type argument supplied by the user of the class: For example,ImmutableMap.get
returns@Nullable E
because the method can returnnull
even on anImmutableMap<K, @NonNull String>
.
Consumers of this annotation include:
- Kotlin, for which it makes the type-variable usage (a) a Kotlin platform type when the type
argument is non-nullable and (b) nullable when the type argument is nullable. We use this
to "undo"
ElementTypesAreNonnullByDefault
. It is the best we can do for Kotlin under our current constraints. - NullAway, which will treat it
identically to
Nullable
as of version 0.9.9. To treat it that way before then, you can set-XepOpt:NullAway:CustomNullableAnnotations=com.google.common.base.ParametricNullness,...,com.google.common.util.concurrent.ParametricNullness
, where the...
contains the names of all the otherParametricNullness
annotations in Guava. Or you might prefer to omit Guava from yourAnnotatedPackages
list. - J2ObjC
NullPointerTester
, at least in the Android backport (where the type-use annotationsNullPointerTester
would need are not available) and in case of JDK-8202469
This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need it.