The Checker Framework Manual: Custom pluggable types for Java https://checkerframework.org/ Version 3.18.0 (1 Sep 2021) For the impatient: Section 1.3 (page 15) describes how to install and use pluggable type-checkers. Contents 1 Introduction 14 1.1 How to read this manual . 15 1.2 How it works: Pluggable types . 15 1.3 Installation . 15 1.4 Example use: detecting a null pointer bug . 16 2 Using a checker 17 2.1 Where to write type annotations . 17 2.2 Running a checker . 18 2.2.1 Using annotated libraries . 18 2.2.2 Summary of command-line options . 19 2.2.3 Checker auto-discovery . 22 2.2.4 Shorthand for built-in checkers . 22 2.3 What the checker guarantees . 22 2.4 Tips about writing annotations . 23 2.4.1 Write annotations before you run a checker . 23 2.4.2 How to get started annotating legacy code . 23 2.4.3 Annotations indicate non-exceptional behavior . 25 2.4.4 Subclasses must respect superclass annotations . 26 2.4.5 What to do if a checker issues a warning about your code . 27 2.4.6 Calls to unannotated code (legacy libraries) . 29 3 Nullness Checker 30 3.1 What the Nullness Checker checks . 30 3.1.1 Nullness Checker optional warnings . 31 3.2 Nullness annotations . 31 3.2.1 Nullness qualifiers . 31 3.2.2 Nullness method annotations . 32 3.2.3 Initialization qualifiers . 33 3.2.4 Map key qualifiers . 33 3.3 Writing nullness annotations . 33 3.3.1 Implicit qualifiers . 33 3.3.2 Default annotation . 33 3.3.3 Conditional nullness . 34 3.3.4 Nullness and array initialization . 34 3.3.5 Nullness and conversions from collections to arrays . 35 3.3.6 Run-time checks for nullness . 35 3.3.7 Inference of @NonNull and @Nullable annotations . 35 3.4 Suppressing nullness warnings . 35 3.4.1 Suppressing warnings with assertions and method calls . 36 2 3.4.2 Null arguments to collection classes . 36 3.5 Examples . 37 3.5.1 Tiny examples . 37 3.5.2 Example annotated source code . 37 3.5.3 Publications . 37 3.6 Tips for getting started . 37 3.7 Other tools for nullness checking . 38 3.7.1 Which tool is right for you? . 38 3.7.2 Incompatibility note about FindBugs and SpotBugs @Nullable ................ 40 3.7.3 Relationship to Optional<T> .................................. 40 3.8 Initialization Checker . 41 3.8.1 Initialization qualifiers . 42 3.8.2 How an object becomes initialized . 43 3.8.3 @UnderInitialization examples . 43 3.8.4 Partial initialization . 45 3.8.5 Method calls from the constructor . 46 3.8.6 Initialization of circular data structures . 47 3.8.7 How to handle warnings . 49 3.8.8 Suppressing warnings . 50 3.8.9 More details about initialization checking . 51 4 Map Key Checker 52 4.1 Invoking the Map Key Checker . 52 4.2 Map key annotations . 52 4.3 Default annotations . 53 4.3.1 Default for lower bounds . 53 4.3.2 Diagnosing the need for explicit @KeyFor on lower bounds . 54 4.4 Examples . 54 4.5 Inference of @KeyFor annotations . 55 5 Optional Checker for possibly-present data 57 5.1 How to run the Optional Checker . 57 5.2 Optional annotations . 57 5.3 What the Optional Checker guarantees . 58 6 Interning Checker 59 6.1 Interning annotations . 60 6.1.1 Interning qualifiers . 60 6.1.2 Interning method and class annotations . 60 6.2 Annotating your code with @Interned .................................. 60 6.3 Interned classes . 61 6.3.1 The intern() methods . 61 6.3.2 Default qualifiers and qualifiers for literals . 62 6.3.3 InternedDistinct: values not equals() to any other value . 62 6.4 What the Interning Checker checks . 62 6.4.1 Imprecision (false positive warnings) of the Interning Checker . 63 6.5 Examples . 63 6.6 Other interning annotations . 64 3 7 Called Methods Checker for the builder pattern and more 65 7.1 How to run the Called Methods Checker . 65 7.2 For Lombok users . 66 7.3 Specifying your code . 66 7.4 Default handling for Lombok and AutoValue . 68 7.5 Using the Called Methods Checker for properties unrelated to builders . 68 8 Resource Leak Checker for must-call obligations 70 8.1 How to run the Resource Leak Checker . 70 8.2 Resource Leak Checker annotations . 71 8.3 Example of how safe resource usage is verified . 71 8.4 Aliased references and ownership transfer . 72 8.4.1 Owning fields . 72 8.5 Resource aliasing ..