Skip to content


Repository files navigation

Basic Java Annotations

Build (Linux) Build (Windows) Code coverage Codacy grade

Maven Central Javadocs Semantic Versioning Automated Release Notes by gren


Gradle (Kotlin DSL)
compileOnly(group = "pl.tlinkowski.annotation", name = "pl.tlinkowski.annotation.basic", version = "x.y.z")
Gradle (Groovy DSL)
compileOnly group: 'pl.tlinkowski.annotation', name: 'pl.tlinkowski.annotation.basic', version: 'x.y.z'
requires static pl.tlinkowski.annotation.basic;


The purpose of this library is to provide a couple of basic annotations related to the following concepts:

  1. Nullability

  2. Mutability of Collections / Iterators

  3. Miscellaneous


The approach to nullability taken by this library is:

Everything is non-null by default, unless explicitly annotated as nullable.

This approach is directly in line with Kotlin's approach (although Kotlin enforces it through its type system):

  • String (Kotlin) / String (Java) → non-null String
  • String? (Kotlin) / @NullOr String (Java) → null or String

For this purpose, the library provides two annotations in the pl.tlinkowski.annotation.basic package:

  1. @NonNullPackage:

  2. @NullOr:

The annotations in this library are based on the dormant Java Specification Request JSR 305. JSR 305 has been chosen for this library after analyzing the following pros & cons.

To sum up, even though I'd rather not rely on JSR 305, it seems too well supported right now to discard it.

However, should the state of JSR 305 change in favor of dropping its usage, this library will do just that. The purpose of this library is to provide @NonNullPackage and @NullOr annotations that work in the best currently possible way.


The approach to mutability of Collections (but also Iterators) taken by this library is:

Every use of Collection or Iterator should be annotated with either @ReadOnly or @Mutable.

This approach is in line with Kotlin's approach (although Kotlin enforces it through its type system):

  • List<T> (Kotlin) / @ReadOnly List<T> (Java) → read-only list of T

  • MutableList<T> (Kotlin) / @Mutable List<T> (Java) → mutable list of T

For this purpose, this library includes two annotations in the kotlin.annotations.jvm package (as a transitive dependency on kotlin-annotations-jvm):

  1. @ReadOnly:

  2. @Mutable:

There are three main problems with these annotations, though:

  1. According to Denis Zharkov, these annotations will probably be renamed once KT-23812 is done.

  2. These annotations are JDK6-compatible, and hence they cannot target type uses or type parameters (introduced in JDK 8). There's an issue about improving this (KT-28982), but it seems idle now.

  3. These annotations are not retained at runtime (@Retention(RetentionPolicy.CLASS)), which could be useful (at least theoretically).

To sum up, the main reason this library does not introduce its own annotations is that Kotlin wouldn't recognize them, and they are very useful for Kotlin interop. However, once KT-23812 is done, this library will probably migrate to some new annotations that can be understood by Kotlin.


Sample Projects

Sample projects for this library can be found in sample subdirectory:


Usage: JDK 8+.

Building: Gradle 5+, JDK 11+.

About the Author

See my webpage ( or find me on Twitter (@t_linkowski).


A couple of basic Java annotations that cover null safety (via JSR 305), collection mutability (via Kotlin), and a few other concepts.








No packages published