jspecify with other annotations

[Greg Thomas]

So, I'm looking forward to what looks like the imminent release of version 1.0.0 - well done all involved.

However, as my mind turns to using it in our code, a query of how it will interact with the various other annotations springs to mind (ahem).

I guess the "belt+braces" solution is (bear with me ...);

@org.jspecify.annotations.NonNull [1]

@javax.annotation.Nonnull [2]

@jakarta.annotation.Nonnull [3]

@org.springframework.lang.NonNull [4]

@jakarta.validation.constraints.NotNull [5]

public MyClass getFoo() {...}

Now, AIUI, jspecify, [1], replaces [2] and [3] so we can strike those out (and yes, [2] and [3] really should be mutually exclusive, but this is just an example!). 

I've seen that Spring is looking to adopt jspecify, but in the meantime I /think/ [4] gives us additional run-time protection if we're using Spring. 

However, unless I've missed something I think [5] will still be required if you want to use a validation framework, no? (and I guess for consistency I could have included @javax.validation.constraints.NotNull in that list but didn't!)

Can anyone correct my mis-apprehensions here?

Thanks,

Greg

[Chris Povirk]

Hi, Greg,

To work backward:

Validation frameworks: I'm hoping that someone else on the list has some actual familiarity with validation frameworks (as it sounds like you may have?), but I have likewise gotten the impression that those are somehow intended to be separate. (Not that that stops tools from treating them identically, either by explicitly recognizing those specific annotations or by automatically recognizing all annotations with the simple class name "NotNull.") My sense is that the validation frameworks are conceptually intended more for runtime checking than compile-time checking but, given that most sets of annotations could in principle be used for either purpose, that the difference goes deeper. Possibly the idea is that a @jakarta.validation.constraints.NotNull value could temporarily be null but should be populated by the time that validation occurs? and/or that validation should specifically result in ConstraintViolationException, which is not otherwise what I'd normally expect for an unexpected null value? I hereby invoke Cunningham's Law :)

Spring: I'm not sure how much Spring reads nullness annotations in user code (outside of maybe the validation case discussed above?). I do know that they annotate their own code, so I've mostly been thinking in terms of that when I hear their discussion about JSpecify adoption. But I'm CCing someone who would know much more than I do.

Other annotations in general: The good news / bad news is that tools (aside from perhaps the validation case) generally treat the various sets of nullness annotations equivalently. Given that, one annotation is likely to be enough. But of course you should check into the specific tools that you care about. When there are differences between artifacts, it's usually a matter of things like:

• Are the annotations type-use annotations or declaration annotations?
• Which additional annotations does the artifact offer, and how widely supported are they?
• How is the documentation for those annotations?

And of course, for @NonNull in particular, the goal is that (once more, validation case aside :)) you don't normally have to use that annotation because you can use a single @NullMarked annotation to affect all enclosed types. @Nullable is, of course, a different story.

[Sebastien Deleuze]

Hi,

The reason for Spring null-safety annotations like org.springframework.lang.NonNull is that we did not want to expose directly JSR 305 annotations in Spring APIs, or push for Spring developers to use JSR 305 directly. With JSpecify 1.0.0 released, it is up to Spring Developers to decide which one to use. JSpecify or Spring null-safety annotations are fine, I would not recommend using JSR 305 directly anymore.

I agree with Chris POV on build-time versus runtime, even if there is a grey area. For example, Spring Framework is using any Nullable annotation at method parameter level (package is not taken in account) to identify optional parameters. See also this Spring Data issue where the null-safety support may be refined and will support JSpecify. We may unify the approach at Spring level later if JSpecify introduces support for meta-annotating custom annotation or an implication mechanism, see framework#28797 for more context.

It is up to validation frameworks to decide if they support annotations like JSpecify, for now I would assume they don't, but it is maybe worth creating an issue in Hibernate Validator and other validation libraries to discuss that idea with them.

Best regards,

Sébastien

This electronic communication and the information and any files transmitted with it, or attached to it, are confidential and are intended solely for the use of the individual or entity to whom it is addressed and may contain information that is confidential, legally privileged, protected by privacy laws, or otherwise restricted from disclosure to anyone else. If you are not the intended recipient or the person responsible for delivering the e-mail to the intended recipient, you are hereby notified that any use, copying, distributing, dissemination, forwarding, printing, or copying of this e-mail is strictly prohibited. If you received this e-mail in error, please return the e-mail to the sender, delete it from your computer, and destroy any printed copy of it.