Null Safety in Java: JSpecify in Action

NullPointerExceptions are among the most common errors in Java applications. JSpecify now offers a standardized approach to clearly document nullability in Java code and verify it through static analysis. Open-source projects like Spring Boot have begun extending their code with JSpecify.

In this presentation, I'll demonstrate how I successfully implement JSpecify in all new client projects.

First, we'll look at what JSpecify is and how it differs from other nullability annotations like JetBrains' @Nullable or JSR-305.

Then we'll move on to practical application. I'll show you how to configure JSpecify in a Spring Boot project and how to integrate it with Maven, NullAway, ErrorProne, and IntelliJ.

We'll also discuss how to migrate existing projects to greater null safety step by step and which typical pitfalls to avoid.

This presentation is aimed at Java developers who want to improve their code quality. Basic knowledge of Spring Boot is helpful, but not required.

After this presentation, you'll be able to use JSpecify in your own projects and know what to look out for.

Transcript

1. Null-safety in Java: jSpecify in Practice Simon Martinelli
2. About Me • 30 years in software engineering • 25 years with Java • Self-employed since 2009 • Teaching at two Universities • Co-lead Berne, JUG Switzerland
3. The Billion Dollar Mistake • Tony Hoare introduced the null reference in ALGOL W in the 1960s • Many years later 2009, he said it was a mistake that has cost the industry billions in bugs, crashes, and wasted time
4. The Core Problem • Nullability is part of the API contract • Java types cannot express non-nullability • NullPointerException in production
5. What We Tried • Defensive null checks • Many if (x != null) • Code reviews • Doesn’t find every problem • Optional • Not a good fit for parameters • Various Nullable annotations • No standard
6. Why Optional Is Not Enough • Optional solves one narrow problem • Models “value may be absent” for return values • Helps avoid null in fluent APIs • But Optional is not a null-safety system • Does not express parameter contracts • Does not define field or property nullability • Does not work across layers consistently
7. JSR-305: The First Attempt
8. What Went Wrong with JSR-305 • Never finalized • No active ownership • Different tools interpreted it differently • Ecosystem fragmentation
9. Jakarta Validation aka Bean Validation • Answers a different question • Is the value valid at runtime? • Not: can this value ever be null? • Is reactive, not preventive • Violations are detected after the code runs • Often at REST or persistence boundaries • No compile-time guarantees • Compiler allows null dereferences • IDE cannot enforce API contracts
10. Checker Framework • The Checker Framework extends Java’s type system with pluggable type checkers.Supports nullness, immutability, units • https://checkerframework.org • The Core Problem: It’s Too Heavy for Most Teams • Cognitive Overhead Is High • Annotation Explosion • Poor Fit for Incremental Adoption • Tooling Friction in Daily Development • Ecosystem Alignment Is Weak
11. Vendor-Specific Nullability • Examples you probably know: • JetBrains: Nullable, NotNull • Spring: Nullable, NonNullApi • AndroidX, Eclipse, FindBugs, etc. • They all try to answer the same question: Can this be null? • No Standard! • JetBrains annotations work very well in IntelliJ IDEA • Spring annotations integrate nicely with Spring Framework
12. How Kotlin Handles Nulls • Nullability is part of the type system • Compiler enforces null check
13. What Java Can Learn from Kotlin • Make nullability explicit • Fail fast at compile time • Clear contracts between APIs • https://openjdk.org/jeps/8303099
14. Why JSpecify Exists • Standardized, minimal, well-defined semantics • Tool-agnostic • Designed for wide adoption • https://jspecify.dev
15. JSpecify Core Principles • Non-null by default • Nullable and NonNull • Nullable is explicit • Defaults via package or class annotations
16. Nullability as a Contract • NullMarked vs NullUnmarked • Caller must respect non-null contract • Callee must handle nullable inputs • Violations become compile-time errors
17. Generics
18. Tooling Makes It Real • Annotations alone are documentation • Static analysis enforces contracts • Build-time feedback • Typical toolchain • Maven or Gradle • Error Prone • NullAway • IDE support
19. What is Error Prone? • Error Prone enhances the Java compiler • Runs during compilation • Extends javac with additional checks • Finds bugs before the code runs • Originally developed at Google • Used on very large Java codebases • Focused on real, recurring bugs • Low false-positive rate • https://errorprone.info
20. What is NullAway? • NullAway is a null-safety checker • Built on top of Error Prone • Focused exclusively on nullability • Enforces null contracts at compile time • Originally developed at Uber to reduce production NullPointerExceptions • https://github.com/uber/NullAway
21. NullAway in the Toolchain • JSpecify → Error Prone → NullAway • JSpecify defines what is allowed • Error Prone provides how to analyze • NullAway enforces the rules
22. https://github.com/simasch/jspecify
23. Migration Strategy • Do not annotate everything at once • Start with public APIs • Use package-level defaults • NullMarked • NullUnmarked
24. Dealing with Legacy Code • Isolate boundaries • Be pragmatic • Gradually increase coverage
25. Best Practices • Non-null by default everywhere • Annotate API boundaries first • Fix design, not warnings!
26. Common Pitfalls • Mixing annotation types • Overusing Nullable • JPA Entities are special
27. Conclusion • Null safety is API design • Static analysis turns intent into guarantees • JSpecify brings standardization • Java is constantly evolving
28. Thank you! • Web martinelli.ch • EMail simon@martinelli.ch • Bluesky @martinelli.ch • X/Twitter @simas_ch • LinkedIn https://linkedin.com/in/ simonmartinelli