The Checker Framework Manual: Custom pluggable types for Java https://checkerframework.org/ Version 3.5.0 (1 Jul 2020) For the impatient: Section 1.3 (page 14) describes how to install and use pluggable type-checkers. Contents 1 Introduction 13 1.1 How to read this manual . 14 1.2 How it works: Pluggable types . 14 1.3 Installation . 14 1.4 Example use: detecting a null pointer bug . 15 2 Using a checker 16 2.1 Where to write type annotations . 16 2.2 Running a checker . 17 2.2.1 Using annotated libraries . 17 2.2.2 Summary of command-line options . 18 2.2.3 Checker auto-discovery . 20 2.2.4 Shorthand for built-in checkers . 21 2.3 What the checker guarantees . 21 2.4 Tips about writing annotations . 22 2.4.1 Write annotations before you run a checker . 22 2.4.2 How to get started annotating legacy code . 22 2.4.3 Annotations indicate non-exceptional behavior . 23 2.4.4 Subclasses must respect superclass annotations . 24 2.4.5 What to do if a checker issues a warning about your code . 25 3 Nullness Checker 27 3.1 What the Nullness Checker checks . 27 3.1.1 Nullness Checker optional warnings . 28 3.2 Nullness annotations . 28 3.2.1 Nullness qualifiers . 28 3.2.2 Nullness method annotations . 29 3.2.3 Initialization qualifiers . 29 3.2.4 Map key qualifiers . 30 3.3 Writing nullness annotations . 30 3.3.1 Implicit qualifiers . 30 3.3.2 Default annotation . 30 3.3.3 Conditional nullness . 30 3.3.4 Nullness and array initialization . 31 3.3.5 Nullness and conversions from collections to arrays . 31 3.3.6 Run-time checks for nullness . 32 3.3.7 Inference of @NonNull and @Nullable annotations . 32 3.4 Suppressing nullness warnings . 32 3.4.1 Suppressing warnings with assertions and method calls . 33 3.4.2 Null arguments to collection classes . 33 2 3.5 Examples . 34 3.5.1 Tiny examples . 34 3.5.2 Example annotated source code . 34 3.6 Tips for getting started . 34 3.7 Other tools for nullness checking . 35 3.7.1 Which tool is right for you? . 35 3.7.2 Incompatibility note about FindBugs @Nullable ........................ 35 3.7.3 Relationship to Optional<T> .................................. 37 3.8 Initialization Checker . 38 3.8.1 Initialization qualifiers . 39 3.8.2 How an object becomes initialized . 39 3.8.3 @UnderInitialization examples . 40 3.8.4 Partial initialization . 41 3.8.5 Method calls from the constructor . 42 3.8.6 Initialization of circular data structures . 43 3.8.7 How to handle warnings . 45 3.8.8 Suppressing warnings . 46 3.8.9 More details about initialization checking . 47 4 Map Key Checker 48 4.1 Map key annotations . 48 4.2 Default annotations . 48 4.2.1 Default for lower bounds . 49 4.2.2 Diagnosing the need for explicit @KeyFor on lower bounds . 49 4.3 Examples . 50 4.4 Inference of @KeyFor annotations . 50 5 Optional Checker for possibly-present data 52 5.1 How to run the Optional Checker . 52 5.2 Optional annotations . 52 5.3 What the Optional Checker guarantees . 53 6 Interning Checker 54 6.1 Interning annotations . 55 6.1.1 Interning qualifiers . 55 6.1.2 Interning method and class annotations . 55 6.2 Annotating your code with @Interned .................................. 55 6.3 Interned classes . 55 6.3.1 The intern() methods . 56 6.3.2 Default qualifiers and qualifiers for literals . 56 6.3.3 InternedDistinct: values not equals() to any other value . 57 6.4 What the Interning Checker checks . 57 6.4.1 Imprecision (false positive warnings) of the Interning Checker . 58 6.5 Examples . 58 6.6 Other interning annotations . 58 7 Lock Checker 59 7.1 What the Lock Checker guarantees . 59 7.2 Lock annotations . 59 7.2.1 Type qualifiers . 59 7.2.2 Declaration annotations . 61 7.3 Type-checking rules . 61 3 7.3.1 Polymorphic qualifiers . 61 7.3.2 Dereferences . 62 7.3.3 Primitive types, boxed primitive types, and Strings . 62 7.3.4 Overriding . 62 7.3.5 Side effects . 62 7.4 Examples . 62 7.4.1 Examples of @GuardedBy . 63 7.4.2 @GuardedBy({“a”, “b”}) is not a subtype of @GuardedBy({“a”}) . 64 7.4.3 Examples of.