[Hawkular-dev] @Null / @NotNull

[Heiko W.Rupp]

Hey,

as we were having a discussion this morning on #hawkular-dev about null

I think we should start (on top of writing more JavaDoc) using
annotations to mark methods and method parameters that
allow being null / not null and if they may return null or not.

This is especially important on API classes(*1), that may be 
consumed by 3rd parties that may or may not have insight
into source of the implementation (on top of that, such annotations
are an enhancement of the API contract).

I know we have been talking about that in the past without
no real result. Luckily since then JSR 308 has been
marked as final and thus a standard exists, that includes such
annotations (+ a checking framework, + tooling to retroactively add
such annotations to existing source).

See http://types.cs.washington.edu/checker-framework/
and http://mvnrepository.com/artifact/org.checkerframework for mvn artifacts

http://mvnrepository.com/artifact/org.checkerframework/checker-qual/1.8.10 <- annotations
http://types.cs.washington.edu/checker-framework/current/api/ <- Javadoc

Another option are the org.jetbrains versions of the annotations, which are around for a while.

If we only care about documentation, but not compile time and/or static analysis, we can also
use the ones from BeanValidation, which live under the javax package spaces (iirc). *2

Here is a more complete list of frameworks
http://stackoverflow.com/questions/4963300/which-notnull-java-annotation-should-i-use




*1) Java and REST
*2) BV may be a good idea for more complex input like in alert definition