These annotations are under development, and any aspect of their naming, locations, or design is subject to change until the JSpecify 1.0 release. Moreover, supporting analysis tools will be tracking the changes on varying schedules. Releasing a library using these annotations in its API is strongly discouraged at this time.
What's here?This package will contain annotations supporting a variety of static analyses. For now it supports just nullness analysis.
NullnessThe primary annotations of interest are
Nullable. Together they provide declarative, use-site nullness for Java types. Less frequently, their negations may be useful:
For a comprehensive introduction to JSpecify, please see jspecify.org.
Note on tool behavior
Each of these annotations defines a single meaning shared by all compatible tools (and libraries). JSpecify documentation aims to provide unambiguous, tool-independent answers for how to properly annotate your APIs in all circumstances. However, tools are permitted to respond to the information you provide however they see fit (or not at all). JSpecify compatibility does not require that any particular finding must or must not be issued to the user, let alone its message or severity.
In fact, it's important to remember that declarative annotations are merely one source
of information an analyzer may consult in concluding an expression is safely non-null. Just like
one analyzer might determine that an
int expression can take on only positive values,
another might likewise determine that a declaratively nullable expression can take on only
non-null values. In both cases the declarative knowledge is correct, but the inferred
knowledge is both correct and more specific.
On the other end, the tools might even enforce nothing at all. In particular, your annotated code (or other code dependent on its annotated APIs) might be compiled and run without any appropriate tool even in use. Therefore adopting JSpecify annotations is not a replacement for explicitly checking arguments at runtime.
ClassDescriptionIndicates that the annotated type usage (commonly a parameter type or return type) is considered to include
nullas a value.Indicates that the annotated element and the code transitively enclosed within it are null-marked code: there, type usages are generally considered to exclude
nullas a value unless specified otherwise.Indicates that the annotated element and the code transitively enclosed within it is null-unmarked code: there, type usages generally have unspecified nullness unless explicitly annotated otherwise.