Checker Framework Tutorial

This section of the tutorial is only for those who are interested in writing their own type-checkers. Please feel free to skip this section.

Although the Checker Framework ships with many checkers, you may wish to write your own checker because there are other run-time problems you wish to prevent. If you do not wish to write a new type-checker, feel free to skip this section of the tutorial.

1. An Encryption Checker

As an example, suppose that you wish to only allow encrypted information to be sent over the internet. To do so, you can write an Encryption Checker.

You need to do some setup to prepare Eclipse.

2. Write the type annotation definitions

For this example, the annotation definitions have already been written for you and appear in files Encrypted.java and PossiblyUnencrypted.java.

3. Run the Encryption Checker

The @Encrypted annotations have already been written in file EncryptionDemo.java. The default for types without annotations is @PossiblyUnencrypted.

Invoke the compiler with the Subtyping Checker. Right Click on the src package, select Checker Framework->Run Built-in Checker->Subtyping Checker. You should see the following errors:

incompatible types in assignment.
                /*@Encrypted*/ int encryptInt = (character + OFFSET) % Character.MAX_VALUE ;
  found   : @PossiblyUnencrypted int
  required: @Encrypted int      EncryptionDemo.java     /encryption-checker/src/encrypted
incompatible types in argument.
                sendOverInternet(password);
  found   : @PossiblyUnencrypted String
  required: @Encrypted String   EncryptionDemo.java     /encryption-checker/src/encrypted

4. Suppress the First Error

The first error needs to be suppressed, because the string on the left is considered "encrypted" in this encryption scheme. All @SuppressWarnings should have a comment explaining why suppressing the warning is the correct action. See the correction below.

@SuppressWarnings("encrypted")  // this is the encryption algorithm
private /*@Encrypted*/ char encryptCharacter(char character) {

5. Re-run the Encryption Checker

You will see the following error:

incompatible types in argument.
        sendOverInternet(password);
  found   : @PossiblyUnencrypted String
  required: @Encrypted String

This is a real error, because the programmer is trying to send a password over the Internet without encrypting it first.

6. Correct the Second Error

The password should be encrypted before it is sent over the Internet. The correction is below.

void sendPassword() {
    String password = getUserPassword();
    sendOverInternet(encrypt(password));
}

7. Re-run the Encryption Checker

There should be no errors.

8. Learn more about writing your own checker

For further explanations, see the Checker Framework manual, chapter How to create a new checker.