Returning empty values

[slinkydeveloper]

From #119 and #108 (comment):

What technique should we use, around the sdk, to notify the user of an eventual empty return value?

1. Optional getters
2. Have an annotation called @Nullable which notifies the user of an eventual null return value
3. Just explicit in the Javadoc that a method can return null

[slinkydeveloper]

I'm fine both with the @Nullable annotation (as soon as it's internal to the sdk and not an external dependency) or just having the javadoc to explicitly mention that a method can return null.

[bsideup]

Yeah, I think JSR-305 @io.cloudevents.lang.Nullable meta-annotation (similar to Spring's, for example) would be the best option, so that the static analysis tools can help.

We should also mark the package as non-nullable by default

[slinkydeveloper]

If i understood correctly with JSR-305 we need to bring in an additional dependency, which I want to avoid as much as possible, even more for just an annotation.

[bsideup]

@slinkydeveloper the point of JSR-305 is that you don't need the dependency, but create your own annotation (and this meta-annotation is annotated with provided JSR-305 annotation)

[slinkydeveloper]

@bsideup the one that you linked from Spring uses @Nonnull from javax.annotation, can you provide an example/doc that explains how it works?

[bsideup]

The JVM spec allows you to keep the annotations without having them at runtime. it is used by JSR-305 to implement meta-annotations that are marked with java.annotation at compile time, but don't need them at runtime.

As you can see, Spring does not depend on it:
https://mvnrepository.com/artifact/org.springframework/spring-core/5.2.5.RELEASE

BTW it is also Kotlin-friendly.

[making]

Hi, here is an example that follows Spring's approach.
https://github.com/making/yavi/tree/develop/src/main/java/am/ik/yavi/jsr305
https://github.com/making/yavi/blob/develop/src/main/java/am/ik/yavi/core/package-info.java#L16
The dependecy on JSR-305 is optional.
https://github.com/making/yavi/blob/develop/pom.xml#L64-L68

[slinkydeveloper]

I was looking around for this jsr305 dep, it looks an old unmantained module without anybody actively mantaining it, it even looks like they didn't migrated the code from https://code.google.com/archive/p/jsr-305/source. I'm not sure it's really a good idea... Anybody else implemented this jsr and is actively mantaining it?

[bsideup]

One of the most commonly used is https://mvnrepository.com/artifact/com.google.code.findbugs/jsr305/3.0.2/usages

Spring Framework and other top Java projects are using it:
https://github.com/spring-projects/spring-framework/blob/8265db0ae1d83a1e204e602fa96e542c2677977f/build.gradle#L348

Kotlin supports it too:
https://kotlinlang.org/docs/reference/java-interop.html#nullability-annotations

Note that it is just a set of annotations.

[slinkydeveloper]

The fact that everybody uses it doesn't make it maintained 😄 Anyway, are you willing to provide a PR to add them to api package?

[bsideup]

@slinkydeveloper I would agree with you if not the usages tab of that dependency where you will find a ton of major Java projects ;)

Anyway, are you willing to provide a PR to add them to api package?

Sure! Expect a PR soon

[bsideup]

Status update: not stale, will be working on the PR today.