Package org.jspecify.annotations

package org.jspecify.annotations

JSpecify annotations. See jspecify.org for general information.

Important warning

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.

Nullness

The primary annotations of interest are NullMarked and Nullable. Together they provide declarative, use-site nullness for Java types. Less frequently, their negations may be useful: NullUnmarked and NonNull, respectively.

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.

Annotation Interfaces

Class	Description
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.
Nullable	Indicates that the annotated type usage (commonly a parameter type or return type) is considered to include null as a value.
NullMarked	Indicates that the annotated element and the code transitively enclosed within it are null-marked code: there, type usages are generally considered to exclude null as a value unless specified otherwise.
NullUnmarked	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.