Annotation Interface Nullable
Nullable
claims null
value is perfectly valid
to return (for methods), pass to (parameters) or hold in (local variables and fields).
Apart from documentation purposes this annotation is intended to be used by static analysis tools
to validate against probable runtime errors or element contract violations.
By convention, this annotation applied only when the value should always be checked against null
because the developer could do nothing to prevent null from happening.
Otherwise, too eager Nullable
usage could lead to too many false positives from static analysis tools.
For example, Map.get(Object key)
should not be annotated Nullable
because
someone may have put not-null value in the map by this key and is expecting to find this value there ever since.
It could be annotated as UnknownNullability
or left unannotated.
On the other hand, the Reference.get()
should be annotated Nullable
because
it returns null
if object got collected which can happen at any time completely unexpectedly.
If a method overrides a superclass method, and the superclass method specifies the nullability on parameter
or return type, then the subclass method should specify the same nullability, either directly or indirectly
via NotNullByDefault
. The only exception is the covariant return type nullability: if the superclass
method is declared to return nullable value, then subclass may declare to return a not-null value.
The tools may issue a warning if the nullability for a subclass method contradicts from the specified nullability of a superclass method.
- See Also:
-
Optional Element Summary
Optional Elements
-
Element Details
-
value
- Returns:
- textual reason when the annotated value could be null, for documentation purposes.
- Default:
""
-