Basic Java Annotations
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'
<dependency> <groupId>pl.tlinkowski.annotation</groupId> <artifactId>pl.tlinkowski.annotation.basic</artifactId> <version>x.y.z</version> <scope>provided</scope> </dependency>
requires static pl.tlinkowski.annotation.basic;
The purpose of this library is to provide a couple of basic annotations related to the following concepts:
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(Java) → non-null
@NullOr String(Java) →
For this purpose, the library provides two annotations in the
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
@NullOr annotations that work in the best currently
Every use of
Iteratorshould be annotated with either
This approach is in line with Kotlin's approach (although Kotlin enforces it through its type system):
@ReadOnly List<T>(Java) → read-only list of
@Mutable List<T>(Java) → mutable list of
For this purpose, this library includes two annotations in the
(as a transitive dependency on
There are three main problems with these annotations, though:
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 for this library can be found in
pl.tlinkowski.annotation.sample.api: sample Java API annotated with
pl.tlinkowski.annotation.sample.usage.java: usage of the above API (both correct and incorrect, the latter resulting in warnings from IntelliJ IDEA)
pl.tlinkowski.annotation.sample.usage.kotlin: usage of the above API (both correct and incorrect, the latter resulting in errors from Kotlin compiler)
Usage: JDK 8+.
Building: Gradle 5+, JDK 11+.