fix: make jspecify a compile time/optional dependency

[jeremylong]

As jspecify is just a compile-time annotation, I believe this should be marked as an optional dependency. Other examples of this:

• https://github.com/google/google-java-format/blob/ccb56c79b0bf4cec457e06f1156a0a0234ca576d/core/pom.xml#L44-L48
• https://github.com/google/jimfs/blob/68dcc63d5386ad015611400f72778217c981f40c/jimfs/pom.xml#L63-L67
• https://github.com/google/turbine/blob/a2aa5bee245643d1939c16c3c2e9f67ab51da5e7/pom.xml#L81-L85

[jeremylong]

@ppkarwasz can you please take a look at this PR? Am I correct?

[dwalluck]

None of these examples have <scope>provided</scope>, but I think we want it (just match the existing jakarta-validation exactly).

[ppkarwasz]

@jeremylong,

Whether to put JSpecify as compile or provided dependency is mostly a judgment call:

• At runtime JSpecify is mostly useless. Guice uses JSpecify annotations for dependency injection, but that is not applicable to PackageURL.
• If JSpecify is absent at compile time, users get warnings with -Xlint:classfile or -Xlint:all and complain like in Upgrading to 2.24.1 produces a compile time warning: BaselineIgnore not found apache/logging-log4j2#3110.
• The ideal scope is therefore a compile time only scope that is inherited by dependents. Gradle has compileOnlyApi for this and the gradle-module-metadata-maven-plugin can be use to publish this information (see Compiling on Module Path with -Werror and -Xlint:all apache/logging-log4j2#3437).
• Maven does not have an ideal scope, so it is either compile with an additional dependency or provided with user complaints. In Log4j we settled for compile for everything except log4j-api: Move JSpecify from provided to compile scope apache/logging-log4j2#3228

[jeremylong]

I think my PR title might have confused things a bit. I didn't mean to raise the concern of the <scope> - but rather the fact that many annotation libraries can be marked as <optional>true</optional>. I just installed this snapshot version locally, upgraded my local copy of DependencyCheck, and ran mvn clean verify on DC. There were no compilation or test errors.

[dwalluck]

I am in favor of this change, but it is related to scope.

https://stackoverflow.com/questions/40393098/when-to-use-optional-dependencies-and-when-to-use-provided-scope

[ppkarwasz]

I think my PR title might have confused things a bit. I didn't mean to raise the concern of the <scope> - but rather the fact that many annotation libraries can be marked as <optional>true</optional>.

I am looking at this from a purely functional perspective: <scope>provided</scope> and <scope>compile</scope><optional>true</optional> behave exactly in the same way.

I just installed this snapshot version locally, upgraded my local copy of DependencyCheck, and ran mvn clean verify on DC. There were no compilation or test errors.

Interesting! 💯
After some simple tests it seems that a warning is issued if:

• An annotation is missing at compile time.
• The annotation has some values.

This is good news, because JSpecify annotations have no values (at least currently)! Go ahead and merge this.

Note: There is a bug in JRE 8 (JDK8152174) that throws an NPE if someone is trying to access a missing type annotation via reflection. So this code will throw a NullPointerException on JRE 8 (but will be OK on more recent JVMs):

PackageURL.class.getDeclaredMethod("getNamespace").getAnnotatedReturnType();

[dwalluck]

I think you want provided or it can be pulled in as a dependency in some other ways. I think shading is one.

[jeremylong]

Unfortunately - I'll need to get @stevespringett to approve this one.