Package org.jspecify.annotations

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

What's here?

This package contains annotations supporting nullness analysis; in the future it might cover other kinds of static analysis as well.

Nullness

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

Note on tool behavior

The presence of these annotations in your code has well-defined semantic meaning, but no direct consequences. It is up to your adopted tools and libraries to voluntarily read and act on the information they provide.

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 context.
    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 in null-marked context: 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 are in null-unmarked context: there, type usages generally have unspecified nullness unless explicitly annotated otherwise.