NonNull type annotation and checker

This document describes the @NonNull type annotation, and a checker for it.

The @NonNull type annotation indicates that a variable should never have a null value. The plugin issues a warning whenever a variable with a @NonNull type may become null. This example shows two ways this might happen: by being assigned null directly, or by being assigned the value of a possibly-null variable.

  @NonNull Object nnobj;  // never null
           Object   obj;  // might be null
  nnobj = null;  // checker will warn that nnobj will become null
  nnobj = obj;   // checker will warn that nnobj may become null

Parameter passing and return values are checked analogously to assignments.

Suppose that the plugin issues no warnings for a given program. Then running that program will never yield a null pointer exception as a result of dereferencing a variable whose type is annotated with @NonNull. This guarantee enables a programmer to prevent errors from occurring when his program is run.

The plugin itself is built on the checkers framework and is implemented in the checkers.nonnull package.

The @NonNull annotation described in this document is similar, but not identical, to the @NotNull annotation of IntelliJ IDEA, the @NonNull annotation of FindBugs, and annotations proposed by JSR 305.

Example use

Tiny examples

To try the @NonNull plugin on a source file that uses the @NonNull qualifier, use the following command (where javac is the JSR 308 compiler):


  javac -typeprocessor checkers.nonnull.NonnullChecker examples/NonNullExample.java 

Compilation should complete successfully. To show an example of the checker warning about incorrect usage of annotations (and therefore the possibility of a null pointer exception at run time), use the following command:


  javac -typeprocessor checkers.nonnull.NonnullChecker examples/NonNullExampleWithWarnings.java 

The compiler should issue three warnings regarding violation of the semantics of @NonNull in the NonNullExampleWithWarnings.java file.

Annotated library

You can also run the nonnull checker on the annotation scene library, a larger library that has been fully annotated with @NonNull. To run the nonnull checker on the annotation scene library, first download the scene library suite (which includes build dependencies for the scene library as well as its source code) and extract it into your checkers installation. The checker can then be run on the annotation scene library with Apache Ant using the following commands:


  cd $CHECKERS
  ant -f scene-lib-test.xml

where $CHECKERS is the location of the checkers installation.

You can view the annotated source code, which contains @NonNull annoations, in the checkers/scene-lib-test/src/annotations/ directory.