Document how to declare that your JPMS module uses JSpecify about jspecify HOT 12 OPEN

• 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 #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 #28, #96, and #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).

from jspecify.

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.

from jspecify.

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

from jspecify.

transitive and static cannot both take effect at the same time

from jspecify.

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.

from jspecify.

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.

from jspecify.

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.

from jspecify.

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.

from jspecify.

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.

from jspecify.

@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.

from jspecify.

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.

from jspecify.

(further discussion of this on #503)

from jspecify.