Hi, This is actually very good read about Optional benefits (with lambdas especially): http://vanillajava.blogspot.fi/2015/01/java-8-optional-is-not-just-for.html Then again, I hope we don't start to use Optional when something really isn't optional. That kills readability. - Micke ----- Original Message ----- From: "John Sanda" <jsanda(a)redhat.com&gt; To: hawkular-dev(a)lists.jboss.org Sent: Monday, 2 March, 2015 2:54:28 PM Subject: Re: [Hawkular-dev] @Null / @NotNull How about using the Optional class introduced in Java instead of null? Not only does it provide documentation like the annotations do, but Optional also provides a rich API that the annotations do not. If you are not familiar with Optional, this article[1] is a good overview. [1] http://www.oracle.com/technetwork/articles/java/java8-optional-2175753.html On Mar 2, 2015, at 5:27 AM, Heiko W.Rupp < hrupp(a)redhat.com > wrote: 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-... *1) Java and REST *2) BV may be a good idea for more complex input like in alert definition _______________________________________________ hawkular-dev mailing list hawkular-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hawkular-dev _______________________________________________ hawkular-dev mailing list hawkular-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hawkular-dev

I think not every IDE can do it, so adding the annotations are a benefit for all users. The annotations from FindBugs and JSR-308 can allow for static code analysis, which may be helpful in error prevention as well.

Regardless of which parameter annotations we use it's been a pain point with Eclipse formatting. I played around a little in one of our Alerts Rest handlers and I think the best I've seen is to enable these options in the formatter, under the New Lines tab: x Insert New Line after annotations on parameters x Insert New Line after type annotations The unfortunate thing is that at least with my version of Eclipse, it works well only if you manually put the first parameter on a new line. With the changes you'll get this from Eclipse: @GET @Path("/trigger/{triggerId}") @Produces(APPLICATION_JSON) @ApiOperation(value = "Find all threshold conditions", responseClass = "Collection<org.hawkular.alerts.api.model.condition.StringCondition>", notes = "Pagination is not yet implemented") public void findAllThresholdConditionsByTrigger( @Suspended final AsyncResponse response, @ApiParam(value = "Trigger id to get threshold conditions", required = true) @PathParam("triggerId") final String triggerId) { try { Collection<Condition> conditionsList = definitions.getTriggerConditions(triggerId, null); Collection<ThresholdCondition> thresholdConditions = new ArrayList<ThresholdCondition>(); for (Condition cond : conditionsList) { if (cond instanceof ThresholdCondition) { thresholdConditions.add((ThresholdCondition) cond); } } if (thresholdConditions.isEmpty()) { log.debugf("GET - findAllThresholdConditions - Empty"); response.resume(Response.status(Response.Status.NO_CONTENT).type(APPLICATION_JSON_TYPE).build()); } else { log.debugf("GET - findAllThresholdConditions - %s compare conditions. ", thresholdConditions.size()); response.resume(Response.status(Response.Status.OK) .entity(thresholdConditions).type(APPLICATION_JSON_TYPE).build()); } } catch (Exception e) { log.debugf(e.getMessage(), e); Map<String, String> errors = new HashMap<String, String>(); errors.put("errorMsg", "Internal Error: " + e.getMessage()); response.resume(Response.status(Response.Status.INTERNAL_SERVER_ERROR) .entity(errors).type(APPLICATION_JSON_TYPE).build()); } } Basically the convention being that if you have annotations in the params, each goes on it's own line. I actually don't care what options we use but this is one formatting area where I still keep seeing disparity between the IDEs. On 3/2/2015 10:41 AM, Thomas Segismont wrote:

Hello, I have set up a Doodle to determine how we proceed. http://doodle.com/we2yweic43i4nz3g Please fill it in. Heiko -- Reg. Adresse: Red Hat GmbH, Technopark II, Haus C, Werner-von-Siemens-Ring 14, D-85630 Grasbrunn Handelsregister: Amtsgericht München HRB 153243 Geschäftsführer: Charles Cachera, Michael Cunningham, Paul Hickey, Charlie Peters

The annotations not only help convey the intention of the writer. Folks that just browse the GitHub repo or that we send pointers to api methods on GitHub also do not have the benefit of IDEs inferring the values. But then it was hard to write, so it should be hard to understand. :-)))