Checker Framework quick start guide

This document gives some important information for getting started with pluggable type-checking. More resources are given at the end.

A pluggable type-checker, or “checker” for short, prevents certain run-time errors. For example, it can prove that your code never suffers a NullPointerException. Choose which checker you want to run from the list of checkers.

To install the Checker Framework, download and unzip the Checker Framework distribution: checker-framework-2.1.7.zip.
Or, the Checker Framework Live Demo webpage lets you try the Checker Framework without installing it.

To run a checker, supply the -processor command-line argument:

  $CHECKERFRAMEWORK/bin/checker/javac -processor nullness MyFile1.java MyFile2.java

You write annotations in your code. Then, the checker verifies two facts: (1) the annotations you wrote are correct (they are consistent with your source code), and (2) your program will not suffer certain exceptions or errors at run time.

Java has two types of annotations: type annotations and declaration annotations.

• A type annotation, also known as a type qualifier, creates a new type. The qualified type represents a different set of values. For example, the ordinary Java type String includes "hello", "", null, and other values. The @NonNull String type includes "hello" and "", but does not include null.
  You write a type annotation right before a use of a type (on the same line), as in:

    @NonNull String s;
    List<@Positive Integer> l;
    class Folder<F extends @Existing File> { ... }
  

• A declaration annotation gives information about a method or a variable (as opposed to information about the method's return type or the variable's type).
  Write a declaration annotation on a different line than the declaration it annotates. For example, to indicate that a method has no side effects:

    @SideEffectFree
    public String toString() { ... }
  

For the most part, you only need to write annotations on method signatures and fields. Most annotations within method bodies are inferred for you automatically. Furthermore, each checker applies certain defaults to further reduce your annotation burden; for example, using the Nullness Checker, you do not need to write @NonNull, only @Nullable which appears less often. See the manual for more tips about writing annotations.

To learn more, you can read:

• Checker Framework tutorial
• Nullness Checker tutorial (external site, setup information is out of date)
• Checker Framework frequently asked questions (FAQs)
• Checker Framework manual