When to Use JSR 305 for Nullability in Java
JSR 305 became a de-facto standard despite its many problems.
Join the DZone community and get the full member experience.Join For Free
JSR 305 became a de-facto standard despite its many problems. I advise to use it for nullability until something better is adopted by Kotlin and major IDEs.
When it comes to nullability annotations in Java, there is no official standard. In this post, I describe:
- What my requirements with respect to nullability in Java are
- Why I decided to use JSR 305 over its alternatives (like Checker Framework) for this
- How I decided to use it to meet my requirements.
I love how Kotlin approaches null safety. In Kotlin, you (and the compiler!) always know if a type can store
null or not:
The exception to this rule are the infamous platform types (which occur only implicitly, when you reference unannotated Java classes):
String!→ non-null or nullable
I'd love to bring as much of Kotlin-like null safety as possible into Java and make sure that my Java libraries can be safely consumed from Kotlin.
Therefore, my requirements are:
- Code clarity: ensure that when code is read, the reader knows whether a type is nullable or not.
- Code brevity: ensure that it's not required to explicitly mark every non-null type as being non-null.
- Tooling support: ensure that the tools (primarily IDEs; compiler if possible) recognize nullable types and raise warnings/errors about their incorrect usage.
- Kotlin interop: ensure that types from Java code are not represented as platform types in Kotlin.
JSR 305 (Annotations for Software Defect Detection) is a Java Specification Request created in 2006, which has been dormant since 2012.
The JCP page doesn't provide many details, but we can read there that:
This JSR would attempt to develop a standard set of annotations that can assist defect detection tools. [...] Some annotations already identified as potential candidates include:
• Nullness annotations (e.g.,William Pugh, JSR 305
More details can be found in this presentation by the author of JSR 305, William Pugh.
In this post, I'll focus only on the following nullability annotation:
And the following two meta-annotations:
Why? Because by combining
@NonNull(when = ...) with either
@TypeQualifier*, we can define custom nullability annotations that are:
- Clear yet unobtrusive (requirements 1 & 2),
- Widely recognized (requirements 3 & 4).
Assessment of JSR 305
Here, I tried to assemble all the pros and cons of using JSR 305 for nullability in Java.
Pros of JSR 305
- Honored by Kotlin for its Java interop.
- Honored by IntelliJ IDEA (IDEA-173544).
- Honored by Eclipse (518839).
- Embraced by some popular libraries:
- Mark Reinhold (Chief Java Architect) seems to at least tolerate using JSR 305.
Cons of JSR 305
- May cause split packages in JPMS (can be patched, though).
- Has no true specification other than this presentation by William Pugh.
- Has potential licensing problems.
- Due to the above, libraries:
- Never used JSR 305 and don't intend to: RxJava, AutoValue
- Stopped using JSR 305: SLF4J, Testcontainers, Caffeine, Apache Sling
- Use JSR 305 but want to stop using it: Guava, rsocket
- In the future, Kotlin might support a non-JSR-305 mechanism for its Java interop (KT-21408).
Response to Criticism
Some experts (like Lukas Eder) advise not to worry about annotating your code will nullability annotations:
You can spare yourself the work of adding aLukas Eder
@NonNullannotation on 99 percent of all of your types just to shut up your IDE, in case you turned on those warnings.
Fortunately, JSR 305 allows you to mark 99 percent of all your types without annotating all of them explicitly, thanks to its
@TypeQualifierDefault meta-annotation, which can be used on packages! True, this requires creating a
package-info.java for every package and putting the annotation there, but it's still easier than annotating every type.
In the future, I'd like to write a simple Gradle plugin that'd verify if the annotation is indeed present on every package.
Basic Java Annotations
I have created a simple library (named Basic Java Annotations) that takes the following approach to nullability:
Everything is non-null by default, unless explicitly annotated as nullable.
For this purpose, the library provides two nullability annotations:
- Annotated with:
- Targets: packages
- Affects: all type uses within an annotated package
- Similar to:
- Example usage
- Annotated with:
- Annotated with:
- Targets: type uses (e.g. in fields, methods, parameters, local variables, etc.)
- Affects: the annotated type use
- Similar to:
- Annotated with:
So after you annotate your package like below:
@NonNullPackage package pl.tlinkowski.sample.api.annotated.nullability;
You get the following mappings between Kotlin and Java:
String(Java) → non-null
@NullOr String(Java) → nullable
This answers how I decided to use JSR 305.
Two words about naming — I chose
- to avoid potential import conflicts with all the other
- because I like how
@NullOr Stringreads as "
Note that thanks to the possibility of creating custom JSR-305-based annotations, I was able to define JSR 305 as a non-transitive dependency (=
In other words, the users of Basic Java Annotations won't be able to reference JSR 305 types (which is good, IMO).
Much has been written on the Internet about which Java annotations to use for nullability. The best summaries I have found so far are this StackOverflow answer and this Checker Framework resource.
I won't be going into details here, and I'll cover only the most interesting alternative (and the only one that — to the best of my knowledge — also lets you annotate packages).
Checker Framework is a beast! It has almost 15k commits on GitHub, over 100 releases, several ways of integrating with external tools, and a 34-chapter-long manual. It is a very complex framework, providing annotations and checkers regarding:
- Nullability (AKA "nullness"; I still struggle to see the difference between these terms),
- And many more.
With respect to nullability, Checker Framework provides
@NonNull annotations, which are recognized by major IDEs and Kotlin.
The framework also provides a complex defaults mechanism, from which the most suitable for us is
@DefaultQualifier, which can be used on packages.
Replacing JSR 305 with Checker Framework in Basic Annotations would look like this, which can be summarized as:
api(...)(no custom annotations, so we need to expose the dependency)
How does it relate to our goals?
- Code clarity: OK.
- Code brevity: OK.
- Tooling support: IntelliJ recognizes the explicit
@Nullableannotations but... doesn't recognize
@DefaultQualifier. So, FAIL!
- Kotlin interop: Kotlin compiler also recognizes the explicit
@Nullableannotations but doesn't recognize
@DefaultQualifier(no errors, no warnings). Again, FAIL!
As you can see, this answers why I chose JSR 305 over Checker Framework.
With respect to point 3 (Tooling support), I didn't mention the Java compiler. And Checker Framework provides a Gradle plugin for this! However, that's what happened when I applied it:
FAILURE: Build failed with an exception. * What went wrong: Execution failed for task ':sample-java-usage:compileJava'. > org.checkerframework.javacutil.UserError: The Checker Framework must be run under JDK 1.8. You are using version 12,000000.
It turns out the manual actually mentions this JDK 8 requirement (which seems a strange requirement to me), but — because this manual is so huge — I missed it easily.
So, no Checker Framework + JPMS yet.
In this post, I showed how JSR 305 is (currently) the only library that can meet the following four nullability-related requirements:
- Code clarity
- Code brevity
- Tooling support
- Kotlin interop
I also showed how I met those requirements by using JSR 305 as an
implementation dependency in my Basic Annotations library.
Thanks for reading!
Published at DZone with permission of Tomasz Linkowski. See the original article here.
Opinions expressed by DZone contributors are their own.