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.
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.
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.