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.
The JCP page doesn’t provide much 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
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 & 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:
- In 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% 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% 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
Everything is non-null by default, unless explicitly annotated as nullable.
For this purpose, the library provides two nullability annotations:
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 “
In other words, the users of Basic Java Annotations won’t be able to reference JSR 305 types (which is good, IMO).
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.
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.
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!