Add nullability annotations to jOOQ API for better Kotlin interop

lukaseder commented 7 years ago

While generating JSR-305 annotations is not technically correct (https://github.com/jOOQ/jOOQ/issues/4748) as a non-null column may be null "in transit" (e.g. when the constraint is deferred, or for a while in Java code, prior to storing the record, or when fetching a record from an outer join, which removes not null constraints) it might certainly make sense to annotate most jOOQ API with @javax.annotation.Nonnull and @javax.annotation.Nullable. This would greatly improve the interoperability experience, especially for Kotlin / Ceylon users.

Alternatives are possible, e.g. using the JetBrains annotations.

When annotating the API, the following things can be done automatically:

[x] Almost every method that is annotated with @Support is also automatically @NotNull. Exceptions:
- [x] fetchOne()
- [x] fetchValue()
- [x] fetchSingle() (if it takes a Field<T> argument and returns T)
[x] Methods returning "collection" or "wrapper" types (which could be monads if designed this way)
- [x] Stream
- [x] Optional
- [x] List, Map, Set (there are a few exceptions, where the object corresponds to a record)
- [x] X[]
- [x] CompletionStage

Some API will be left out of this improvement. This includes:

[x] Parameters (this is too much noise right now)
- [x] Almost every argument of type T is @Nullable
- [x] Every argument of type Field or Condition, etc. is @NotNull
[x] Generic types where nullability would have to be inferred, e.g.
- [x] DSLContext.transactionResult()
[x] API returning primitive types, which cannot be null, so @NotNull is implied

Incompatible change

For Kotlin users, this will be an incompatible change as they will get occasional compilation errors, e.g. when using fetchOne()

lukaseder commented 7 years ago

See licensing concerns here: https://github.com/jOOQ/jOOQ/issues/4748#issuecomment-303380405

lukaseder commented 7 years ago

Spring has moved forward with JSR 305 adoption through the TypeQualifierNickname backdoor, which allows for defining custom @Nullable annotations that "correspond" to the JSR 305 annotations of equivalent semantics, without exposing them to clients. Background info here:

Let's wait how Spring fares with this strategy. I feel that we're really on a very wrong path as an ecosystem. If we cannot agree on something silly and stupid as a @Nullable annotation as part of the JRE, it's better to wait and see what happens. Let's not jump on this part of the Kotlin hype.

GuiSim commented 6 years ago

Kotlin added support for @TypeQualifierNickname in version 1.1.50.

While I agree that this isn't the perfect solution, I think it would be great to have jOOQ annotate nullable and non-nullable types, even if it's with its own custom annotation.

lukaseder commented 6 years ago

I rest my case (for now):

I feel that we're really on a very wrong path as an ecosystem. If we cannot agree on something silly and stupid as a @Nullable annotation as part of the JRE, it's better to wait and see what happens. Let's not jump on this part of the Kotlin hype.

fkowal commented 5 years ago

Thank you for the great library

A lot of time has passed since this topic was first discussed. Perhaps it's worth reconsidering?

Support @Nullable annotations would be great. It could be an optin feature, and the user would decide what package he would use if any.

generate {
   nullable: "javax.annotations.Nullable"
}

lukaseder commented 5 years ago

Thanks for your comments, @fkowal. The usage of JSR 305 is crystal clear. The reservations mentioned in this issue and elsewhere aren't purely technical. JSR 305 still creates a legal mess. Is it LGPL licensed like FindBugs? Or BSD licensed as claimed on some websites? Or ASL 2.0 licensed as mentioned in the maven artifact com.google.code.findbugs:jsr305:3.0.2? What does the groupId com.google.code.findbugs even mean, who owns it? Were they allowed to re-license the library, or did they just not care and do it anyway? Will Oracle allow the continued use of the javax namespace (they didn't in the case of Jakarta!)

Nothing seems to have changed since this issue was first created. Everyone is just hacking around, and I'm really reluctant to spend a lot of time annotating the entire jOOQ API with something that is so unclean - without any clear and obvious benefits, too! The Kotlin integration could profit from this, yes, but only to a limited extent, as Kotlin has made good choices to integrate with Java APIs by introducing T! types, i.e. types that might be nullable, but are not type checked as strongly as T? types, which are known to be nullable.

So, this issue remains dormant, until it has been shown that either:

Some significant ecosystem would profit tremendously from this addition
JSR 305 finally moves into a non-messy state

xenomachina commented 4 years ago

The lack of nullalbe annotations on things that can be null also leaves a lot to be desired when you're used to Kotlin warning you when you forgot to properly handle the null values. Every time I see fetchOne or fetchSingle in code I have to go look up whether it's the one that always returns a value, or the one that sometimes returns null. If they were properly annotated, I'd know from the type.

If the JSR annotations have legal problems, why not use one of the alternatives? I agree it isn't ideal having to depend on a non "standard" library like org.jetbrains:annotations, but if a better alternative ever arises in the future it should be pretty easy to search and replace.