The Checker Framework Manual: Custom pluggable types for Java https://checkerframework.org/ Version 2.5.7 (4 Nov 2018) For the impatient: Section 1.3 (page 13) describes how to install and use pluggable type-checkers. Contents 1 Introduction 12 1.1 How to read this manual . 13 1.2 How it works: Pluggable types . 13 1.3 Installation . 13 1.4 Example use: detecting a null pointer bug . 13 2 Using a checker 15 2.1 Writing annotations . 15 2.2 Running a checker . 16 2.2.1 Using annotated libraries . 16 2.2.2 Distributing your annotated project . 17 2.2.3 Summary of command-line options . 17 2.2.4 Checker auto-discovery . 19 2.2.5 Shorthand for built-in checkers . 19 2.3 What the checker guarantees . 19 2.4 Tips about writing annotations . 20 2.4.1 Write annotations before you run a checker . 20 2.4.2 How to get started annotating legacy code . 20 2.4.3 Annotations indicate non-exceptional behavior . 22 2.4.4 Subclasses must respect superclass annotations . 22 2.4.5 Annotations on constructor invocations . 23 2.4.6 What to do if a checker issues a warning about your code . 24 3 Nullness Checker 26 3.1 What the Nullness Checker checks . 26 3.2 Nullness annotations . 27 3.2.1 Nullness qualifiers . 27 3.2.2 Nullness method annotations . 28 3.2.3 Initialization qualifiers . 28 3.2.4 Map key qualifiers . 28 3.3 Writing nullness annotations . 29 3.3.1 Implicit qualifiers . 29 3.3.2 Default annotation . 29 3.3.3 Conditional nullness . 29 3.3.4 Nullness and arrays . 30 3.3.5 Run-time checks for nullness . 30 3.3.6 Additional details . 30 3.3.7 Inference of @NonNull and @Nullable annotations . 31 3.4 Suppressing nullness warnings . 31 3.4.1 Suppressing warnings with assertions and method calls . 31 2 3.5 Examples . 32 3.5.1 Tiny examples . 32 3.5.2 Example annotated source code . 32 3.6 Tips for getting started . 32 3.7 Other tools for nullness checking . 33 3.7.1 Which tool is right for you? . 34 3.7.2 Incompatibility note about FindBugs @Nullable ........................ 35 3.7.3 Relationship to Optional<T> .................................. 35 3.8 Initialization Checker . 36 3.8.1 Initialization qualifiers . 38 3.8.2 How an object becomes initialized . 39 3.8.3 Partial initialization . 40 3.8.4 Method calls from the constructor . 40 3.8.5 Initialization of circular data structures . 42 3.8.6 How to handle warnings . 43 3.8.7 More details about initialization checking . 44 3.8.8 Rawness Initialization Checker . 45 4 Map Key Checker 50 4.1 Map key annotations . 50 4.2 Default annotations . 50 4.2.1 Default for lower bounds . 51 4.3 Examples . 51 4.4 Inference of @KeyFor annotations . 52 5 Optional Checker for possibly-present data 54 5.1 How to run the Optional Checker . 54 5.2 Optional annotations . 54 6 Interning Checker 56 6.1 Interning annotations . 57 6.2 Annotating your code with @Interned .................................. 57 6.2.1 Implicit qualifiers . 57 6.2.2 InternedDistinct: values not equals() to any other value . 57 6.3 What the Interning Checker checks . 58 6.3.1 Limitations of the Interning Checker . 59 6.4 Examples . 59 6.5 Other interning annotations . 59 7 Lock Checker 60 7.1 What the Lock Checker guarantees . 60 7.2 Lock annotations . 60 7.2.1 Type qualifiers . 60 7.2.2 Declaration annotations . 62 7.3 Type-checking rules . 62 7.3.1 Polymorphic qualifiers . 62 7.3.2 Dereferences . 63 7.3.3 Primitive types, boxed primitive types, and Strings . 63 7.3.4 Overriding . 63 7.3.5 Side effects . 63 7.4 Examples . 63 7.4.1 Examples of @GuardedBy . 64 3 7.4.2 @GuardedBy({“a”, “b”}) is not a subtype of @GuardedBy({“a”}) . 65 7.4.3 Examples of @Holding . 65 7.4.4 Examples of @EnsuresLockHeld and @EnsuresLockHeldIf . 66 7.4.5 Example of @LockingFree, @ReleasesNoLocks, and @MayReleaseLocks . 66 7.4.6 Polymorphism and method formal parameters with unknown guards . 67 7.5 More locking details . 68 7.5.1 Two types of locking: monitor locks and explicit locks . 68 7.5.2 Held locks and held expressions; aliasing . 68 7.5.3 Run-time checks for locking . ..