Document how to declare that your JPMS module uses JSpecify

[xenoterracide]

I'm not certain what libraries should do as far as their own jpms

should I have

import org.jspecify.annotations.NullMarked;

@NullMarked module com.xenoterracide.jpa {
  requires transitive static org.jspecify;
}

or

import org.jspecify.annotations.NullMarked;

@NullMarked module com.xenoterracide.jpa {
  requires static org.jspecify;
}

I would generally think the second, but then I'm constantly plagued by warnings from java of annotations at compile time that are missing, or missing dependent fields of. Is static actually appropriate? I notice that the annotations are marked as "runtime" but I don't understand the use case for that.

[SentryMan]

transitive and static cannot both take effect at the same time

[xenoterracide]

is that true? I would think it'd be roughly equivalent to compileOnlyApi in gradle... it doesn't result in a compile error. I can't find anything that says either way.

https://www.oracle.com/corporate/features/understanding-java-9-modules.html

is like, we're going to glaze over that... reading it sounds like it would be optional, but any module, if it's available? would also be able to read it based on using mine... which doesn't sound mutually exclusive.

[agentgt]

I think and I’m tired so this is probably wrong

requires static transitive

The sort of reason is JSpecify annotations are retention RUNTIME.

I would say less than 1% of Java devs know this so it is a good point.

edit I will say I have never done requires transitive and static both so maybe there are compat issues or maybe it doesn’t work but iirc it does.

I use the eclipse annotations which are CLASS so requires static is good enough.

[SentryMan]

is that true?

I guess not, but modules that depend on it will need to have jspecify in the dependency tree or they'll get a module not found error.

[agentgt]

I’m not sure of that when it comes to annotations. Like if you are just sniffing via reflection which is precisely why you want the transitive for nullness.

That is a third party runtime library trying to deduce if a field to inject is nullable or not.

[agentgt]

I wasn't at my computer before but it appears on googling @lukaseder had compat issues with Maven and I believe I did as well: jOOQ/jOOQ#13619

I will need to double check but I believe mine were with Javadoc of all things.

Ultimately I don't think it matters as the annotations are public but I believe requires static transitive is technically correct assuming tooling works in an application. For a library that may not be desired.

Later today I will try experimenting. @bowbahdoe do you have any experience with requires static transitive? I am sorry to ping you but there are not many (like I said I wager 1% of java devs are aware of most of the module rules) and at this point I think its more about compat with external tooling.

[bowbahdoe]

@agentgt Yeah - i'm not too sure of a good usage for requires static transitive. You need it at compile time and dependent modules need it at compile time, but none need it at runtime.

Annotations that aren't on the module path just become invisible, so its perfectly fine to not require the jspecify annotations downstream. For me, I think thats interesting/important only when you want to have a zero dependency library. Once you have one dependency might as well have two.

I don't really understand the state of tooling either.

[cpovirk]

• Thanks for all the information so far. I don't know who in the group knows the most about the module system, but it is definitely not me. (I still haven't even absorbed the previous discussion on Is it safe to have jspecify be an optional dependency? #389.)
• Given many experiences with the sort of warnings and errors discussed in this thread, I am always nervous about advising people that they don't really need annotations to be visible, even at compile time. (See the notes about annotations in this part of the Guava wiki.) I would be happy if we could end presenting both "Here is a policy that we're sure is safe" and "Here is what you might be able to get away with if you're trying very hard to avoid dependencies, and here are the associated risks that we know of."
• I am re-titling this issue to be a little more specifically about how to declare your dependency on JSpecify. I'm doing that because I want to open another issue about what happens if you annotate your module but your users aren't using JPMS, which I have been failing to follow up on for a while now.
• The main specific purpose of runtime retention is for libraries like Guice that want to reject nulls. The more general reason is that runtime retention has few downsides relative to class retention (which we obviously need), with the main exception being Android (which we largely sidestep because @Nullable is a type-use annotation, which doesn't become part of the Android dex). I am probably forgetting things from Decide retention for our annotations [working decision: runtime] #28, Annotation targets and retentions for nullness annotations #96, and Ensure 1.0 does not preclude supporting both retention levels well later #234, but I could brush up on them if you want to get into this more (on whichever of those threads seems best to you).

[xenoterracide]

I have one further comment about when annotations currently seem to be required on the compile class path, but I've only for sure seen this coming from things that you use the automatic modules. Since most libraries only use automatic modules currently.

The example would be if spring had a non-null (on my phone) annotation that had a field that supported A Jspecify annotation, then, in my experience spring needs to export in some way jspecify as well or you will get compiler warnings. This only happens of course if you're using that specific annotation from spring. I do not know and haven't tested if this is a problem when full JPMS is used. I can link an issue I opened in spring boot with this recently if it's helpful. Since the solution and Gradle would be to use the API or compile only API dependency scope.

[agentgt]

The example would be if spring had a non-null (on my phone) annotation that had a field that supported A Jspecify annotation, then, in my experience spring needs to export in some way jspecify as well or you will get compiler warnings. This only happens of course if you're using that specific annotation from spring. I do not know and haven't tested if this is a problem when full JPMS is used. I can link an issue I opened in spring boot with this recently if it's helpful. Since the solution and Gradle would be to use the API or compile only API dependency scope.

With javac you do not get compiler warnings or errors unless of course you actually access the annotations methods (the methods on the annotation itself). With ecj aka Eclipse Java compiler you will get a warning if you have a generic parameter annotated albeit I believe that is a bug. I can't recall if I have already told Stephan Herrmann about that.

You can actually see this through my current two projects code bases of jstachio and rainbowgum where I constantly have to SuppressWarnings of "exported".

@SuppressWarnings("exports")
public @Nullable /* this one is fine */ Object blah(List<@Nullable /* this one causes warnings */ Object> o) {
}

EDIT I think I misunderstood you. Yes you will need to requires as Spring does not have true modules.

Speaking of which you should never requires transitive any of Springs stuff because they are automatic modules. Which is annoying.

[xenoterracide]

For clarity on warnings I'm referring to issues like this (linking to reproducer comment) spring-projects/spring-boot#39901 (comment)

spring-core currently has this exact kind of issue with jsr305