Package org.jspecify.annotations

package org.jspecify.annotations
JSpecify annotations. See jspecify.org for general information.

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.