Get Started

The Checker Framework distribution includes many useful checkers that help developers to detect, and more importantly to prevent, errors in their Java programs. The checkers are easy to use and are invoked as arguments to javac.

Using the checkers, developers can express important information about their variables, such as whether a variable may be null, whether a value is intended to be side-effected, or whether a String is interned. As a result, the checkers can detect null pointer exceptions, incorrect mutations, errors in equality testing, among other problems.

This tutorial will teach you how to install and start using the checkers. For more details, see the Checker Framework Manual. The manual discusses how to use the checkers and each checker in greater detail.

Requirements

Running the Checkers requires JDK 6 to be installed. You can get JDK 6 from Sun or elsewhere. If you are using Apple Mac OS X, you can either use Apple's implementation or SoyLatte.

Installation

  1. Download a copy of Checkers jar and the jsr308-javac script file in the same directory. Preferably you would put them in one of your PATH directories.
  2. Verify that you installed the correct version.
      $ jsr308-javac -version
      javac 1.7.0-jsr308-0.8.1
  3. You're ready to start using the checkers !

Running the Checkers

The Checker Framework distribution includes many checkers. This tutorial describes using the Nullness Checker, a checker for detecting nullness errors.

To run a checker on a source file, use the following command (where jsr308-javac is the JSR 308 compiler):
jsr308-javac -processor [processor name] source-files ...

  1. Let's consider this very simple Java class. One local variable is annotated as NonNull, indicating that ref must be a reference to a non-null object. Save the file as GetStarted.
    import checkers.nullness.quals.*;
    
    public class GetStarted {
        void sample() {
            @NonNull Object ref = new Object();
        }
    }
      
  2. Run the nullness checker on the class.
    jsr308-javac -processor checkers.nullness.NullnessChecker GetStarted.java
    The compilation should end without any errors.

  3. Let's introduce an error now. Modify ref assignment to:
      @NonNull Object ref = null;
  4. Rerun the nullness checker again, like before. This run should emit the following error:
    GetStarted.java:5: incompatible types.
    found   : @Nullable 
    required: @NonNull Object
    		@NonNull Object ref = null;
    		                      ^
    1 error
        
      
The type qualifier (e.g. NonNull) are permitted anywhere that would write a type, including generics and casts.
    @Interned String intern() { ... }             // return value
    int compareTo(@NonNull String other) { ... }  // parameter

    @NonNull List<@Interned String> messages;     // generics: non-null list of interned Strings

Last updated: October 31, 2008.

Back to the Type annotations (JSR 308) webpage.