@Incubating
class NullChecker
extends TypeCheckingDSL

A compile-time type checker that detects potential null dereferences and null-safety violations in code annotated with @Nullable, @NonNull, and @MonotonicNonNull annotations.

By default, this checker performs annotation-based null checking only. For additional flow-sensitive analysis that tracks nullability through assignments and control flow (even in unannotated code), enable the strict option:

 @TypeChecked(extensions = 'groovy.typecheckers.NullChecker(strict: true)')
 

Supported annotations are recognized by simple name from any package:

• Nullable: @Nullable, @CheckForNull, @MonotonicNonNull
• Non-null: @NonNull, @NotNull, @Nonnull

Detected errors include:

• Assigning null to a @NonNull variable
• Passing null or a @Nullable value to a @NonNull parameter
• Returning null or a @Nullable value from a @NonNull method
• Dereferencing a @Nullable variable without a null check or safe navigation (?.)
• Dereferencing the result of a @Nullable-returning method without a null check, whether called explicitly (x.getA().b) or via property syntax (x.a.b)
• Dereferencing a safe-navigation result without a further guard (a?.b.c; use a?.b?.c instead)
• Passing other nullable expressions (safe-navigation results, @Nullable-returning calls, ternaries with a nullable branch) to @NonNull parameters, or returning them from @NonNull methods
• Re-assigning null to a @MonotonicNonNull field after initialization
• Dereferencing a variable known to be null through flow analysis (strict mode only)

The checker recognizes a range of null-guard patterns:

• Null comparisons: if (x != null), if (x == null)
• Early exit patterns: if (x == null) return/throw
• Safe navigation: ?.
• Groovy-truth guards: if (x), if (!x) return
• Boolean conjunctions and disjunctions with short-circuit semantics: if (x != null && x.length() > 0), if (x == null || x.isEmpty()) return
• Type checks: if (x instanceof Foo), if (x !instanceof Foo) return
• Utility methods: Objects.nonNull(x), Objects.isNull(x)
• Assert statements: assert x, assert x != null
• Guard conditions of while loops and ternary expressions

 @TypeChecked(extensions = 'groovy.typecheckers.NullChecker')
 void process(@Nullable String input) {
     // input.length()     // error: potential null dereference
     input?.length()       // ok: safe navigation
     if (input != null) {
         input.length()    // ok: null guard
     }
 }
 

Since:

6.0.0