The Checker Framework Manual: Custom pluggable types for Java http://checkerframework.org/ Version 1.9.13 (1 Apr 2016) For the impatient: Section 1.3 (page 12) describes how to install and use pluggable type-checkers. Contents 1 Introduction 11 1.1 How to read this manual . 12 1.2 How it works: Pluggable types . 12 1.3 Installation . 12 1.4 Example use: detecting a null pointer bug . 13 2 Using a checker 14 2.1 Writing annotations . 14 2.2 Running a checker . 15 2.2.1 Distributing your annotated project . 15 2.2.2 Summary of command-line options . 16 2.2.3 Checker auto-discovery . 17 2.2.4 Shorthand for built-in checkers . 17 2.3 What the checker guarantees . 18 2.4 Tips about writing annotations . 19 2.4.1 How to get started annotating legacy code . 19 2.4.2 Do not annotate local variables unless necessary . 19 2.4.3 Annotations indicate normal behavior . 19 2.4.4 Subclasses must respect superclass annotations . 20 2.4.5 Annotations on constructor invocations . 21 2.4.6 What to do if a checker issues a warning about your code . 21 3 Nullness Checker 22 3.1 What the Nullness Checker checks . 22 3.2 Nullness annotations . 23 3.2.1 Nullness qualifiers . 23 3.2.2 Nullness method annotations . 24 3.2.3 Initialization qualifiers . 24 3.2.4 Map key qualifiers . 24 3.3 Writing nullness annotations . 25 3.3.1 Implicit qualifiers . 25 3.3.2 Default annotation . 25 3.3.3 Conditional nullness . 25 3.3.4 Nullness and arrays . 26 3.3.5 Run-time checks for nullness . 26 3.3.6 Additional details . 26 3.3.7 Inference of @NonNull and @Nullable annotations . 26 3.4 Suppressing nullness warnings . 27 3.4.1 Suppressing warnings with assertions and method calls . 27 3.5 Examples . 28 2 3.5.1 Tiny examples . 28 3.5.2 Example annotated source code . 28 3.6 Tips for getting started . 28 3.7 Other tools for nullness checking . 29 3.7.1 Which tool is right for you? . 30 3.7.2 Incompatibility note about FindBugs @Nullable ........................ 31 3.7.3 Relationship to Optional<T> .................................. 31 3.8 Initialization Checker . 32 3.8.1 Initialization qualifiers . 33 3.8.2 How an object becomes initialized . 34 3.8.3 Partial initialization . 34 3.8.4 Initialization of circular data structures . 35 3.8.5 How to handle warnings . 37 3.8.6 More details about initialization checking . 38 3.8.7 Rawness Initialization Checker . 39 4 Map Key Checker 44 4.1 Map key annotations . 44 4.2 Examples . 45 4.3 Inference of @KeyFor annotations . 45 5 Interning Checker 47 5.1 Interning annotations . 48 5.2 Annotating your code with @Interned .................................. 48 5.2.1 Implicit qualifiers . 48 5.3 What the Interning Checker checks . 48 5.3.1 Limitations of the Interning Checker . 49 5.4 Examples . 49 5.5 Other interning annotations . 49 6 Lock Checker 50 6.1 Lock annotations . 50 6.1.1 Type annotations for objects protected by locks . 50 6.1.2 Lock method annotations . 50 6.1.3 Discussion of @Holding ..................................... 51 6.2 Examples . 52 6.2.1 Examples of @GuardedBy and @Holding . 52 6.2.2 Examples of @EnsuresLockHeld and @EnsuresLockHeldIf . 52 6.2.3 Example of @LockingFree . 53 6.3 Other lock annotations . 54 6.3.1 Relationship to annotations in Java Concurrency in Practice .................. 54 6.4 Possible extensions . 55 6.5 A note on Lock Checker internals . 55 7 Fake Enum Checker 56 7.1 Fake enum annotations . 56 7.2 What the Fenum Checker checks . 57 7.3 Running the Fenum Checker . 57 7.4 Suppressing warnings . 58 7.5 Example . 58 7.6 References . 59 3 8 Tainting Checker 60 8.1 Tainting annotations . 60 8.2 Tips on writing @Untainted annotations . 60 8.3 @Tainted and @Untainted can be used for many purposes . 61 8.3.1 Qualifier Parameters . 61 9 Regex Checker for regular expression syntax 62 9.1 Regex annotations . 62 9.2 Annotating your code with @Regex .................................... 62 9.2.1 Implicit qualifiers . 62 9.2.2 Capturing groups . 63 9.2.3 Concatenation of partial regular expressions . 63 9.2.4 Testing whether a string is a regular expression . ..