Guava + JPMS

[sgammon]

Summary

This PR adds modular Java support to Guava, by adding a module-info.java definition to the guava and guava-testlib modules. This includes upstream work in the Error Prone Compiler, J2ObjC Annotations, and Checker Framework to land modules as well, rendering Guava able to build entirely on the modulepath.

Fixes and closes #2970

Current Status

• ✅ Guava builds as a module
• ✅ Guava builds completely on modulepath
• ✅ All tests pass
• ✅ All warnings fixed (within reason, some cannot be fixed or suppressed)
• ✅ Javadoc builds at JVM21
• ⚠️ Docs for modular use of Guava
• ⚠️ Integration and smoke tests
• ⚠️ Benchmarks and other verifications
• ⚠️ Final PR cleanup + autorebase

Warning

This branch of Guava is still in testing. See the JPMS attic and the tracking issue if you want to use it ahead of release.

PR Tree

On the way to a finished PR, there were a number of other changes and improvements that surfaced. These have been broken out into their own PRs for easier review; they are listed below as Downstream PRs.

PRs that are Included in this PR can be rebased away, either when they are merged or closed without merging, at the Guava team's choosing.

The following PRs relate to this one:

• Downstream: (Pending: benchmark split)
• Downstream: chore: parallel test and build #7093
• Downstream: fix: drop jdk srzip javadoc infra #7092
• Included: chore(ci): improvements to gha workflows #7089
• Included: Fix: Java 18+ Builds #7087
• Upstream: Add the 'compile' goal for 'compile-java9' error-prone#4314
• Upstream: feat: add jpms definition for annotations error-prone#4311
• Upstream: feat: support jpms in annotations module j2objc#2302
• Upstream: Add module-info.java to checker-qual typetools/checker-framework#6326

Using Modular Guava

From a Java 9+ application, in module-info.java:

module my.module {
  requires com.google.common;
}

Tip

To build your app without any Guava transitive dependencies on the classpath, make sure to exclude jsr305. You will also need to use the JPMS Attic repository until a release occurs.

Maven:

<dependency>
  <groupId>com.google.guava</groupId>
  <artifactId>guava</artifactId>
  <version>33.0.0-jre-jpms</version>
  <exclusions>
    <exclusion>
      <groupId>com.google.findbugs</groupId>
      <artifactId>jsr305</artifactId>
    </exclusion>
  </exclusions> 
</dependency>

Gradle (Groovy):

dependencies {
  api('com.google.guava:guava:33.0.0-jre-jpms') {
    exclude group: 'com.google.findbugs', module: 'jsr305'
  }
}

Gradle (Kotlin):

dependencies {
  api("com.google.guava:guava:33.0.0-jre-jpms") {
    exclude(group = "com.google.findbugs", module = "jsr305")
  }
}

Gradle (Version Catalog + Kotlin):

[versions]
guava = "33.0.0-jre-jpms"

[libraries]
guava = { module = "com.google.guava:guava", version.ref = "guava" }

dependencies {
  api(libs.guava) {
    exclude(group = "com.google.findbugs", module = "jsr305")
  }
}

Forcing Resolution

Sometimes, your build will resolve to a different version of Guava. This usually happens because of a transitive dependency. Here are some instructions for Gradle:

build.gradle.kts:

configurations.all {
  resolutionStrategy.force("com.google.guava:guava:33.0.0-jre-jpms")
}

Changelog

Expand for full changelog

- feat: add `module-info.java` to `guava` module
- feat(jpms): add `module-info.java` to `failureaccess`
- feat(jpms): add `module-info.java` to `testlib`
- fix: necessary fixes to get testsuite running on modular java
- fix: apply jpms args on JVM18+ for javadoc build
- fix: generate checksums at install
- fix: enable test retries (max = 3) for parallel-flaky tests
- fix: javadoc warning fixes
- chore: drop jdk srczip dependencies
- chore: cleanup comments and config related to srczip
- chore: update `guava` to build MRJAR
- chore: adjust dev version → `1.0-HEAD-[jre|android]-SNAPSHOT`
- chore: upgrade maven compiler plugin → `3.12.1`
- chore: cleanup suppressions in Striped64.java
- chore: enable parallel build
- chore: enable parallel test execution
- chore: enable parallel gc for maven
- chore: tune tiered compilation for maven
- chore: tune thread count for maven
- chore: upgrade maven → 3.9.6
- chore: add coverage via maven-jacoco-plugin

[norrisjeremy]

Curious as to which parts of Guava require jdk.unsupported?
Not sure if it's correct to explicitly add a module requirement on it, since this is not a module dictated in the JLS, so it could be changed/removed/altered in some incompatible way in future Java releases?

[sgammon]

@norrisjeremy I believe this is because of sun.misc.Unsafe; I'm not sure there is any way around requires jdk.unsupported at least for the time being. Once Unsafe is refactored away this can be removed. We're 10 years in to the launch of JPMS and jdk.unsupported is still around, and it is supported on all current Java versions up to latest LTS, so it should be okay.

[norrisjeremy]

Ok, I suppose.
But not sure if you have seen JDK-8323072 & it's associated draft JEP, which I believe may land in Java 23 later this year.
I think the doomsday clock for sun.misc.Unsafe is advancing ever closer to midnight.

[sgammon]

@norrisjeremy Oh, agreed, for sure; but this PR just focuses on JPMS for now. JPMS and Unsafe are both sensitive changes that should be done soon, no question.

Java 22 comes out this month, in about 10 days. So you're right to be concerned for Java 23, but Guava has some time to address that before it becomes a problem. JPMS, meanwhile, has been out since Java 9 and is currently unsupported by Guava, so this PR advances on that front.

Even if Unsafe is deprecated in Java 23 (I don't foresee it getting removed completely yet), this changeset will let Guava work at Java 9 - Java 22 with fully modular Java. Then, working to refactor/fix the Unsafe usages becomes easier, because Guava is shipping MRJARs, so Unsafe can safely be used for earlier JVMs only, with later JVMs using classes that override with other intrinsics.

[norrisjeremy]

Yes, that makes sense.
Btw, finally adding JPMS support is greatly appreciated btw. :)

[sgammon]

@norrisjeremy Thank you likewise for the reviews :)

[Sineaggi]

Does guava require unsafe, or can it safely fallback? If it doesn't require unsafe, we could use requires static here I think.

[sgammon]

@Sineaggi If I understand correctly, the implications of that are basically the modular equivalent of a compile-time dependency, right? So users could effectively opt-in by adding requires jdk.unsupported in their own module?

In any case, great catch. You're right: the testsuite passes in full with only requires static.

@cpovirk Curious about your thoughts on behavior defaults here. By the way: technically it is legal to have a slightly different module-info.java for different META-INF/versions/ within a single JAR. The public API surface of the module graph can't change, but including things from java or jdk was specifically imagined to be possible, so that newer class suites can leverage the latest JVM features while remaining compatible with strong module encapsulation:

Modular multi-release JAR files in JEP-238: Multi-Release JARs

(Fwiw, jar --validate checks the consistency of these MRJAR APIs, the JPMS Attic is running this on Guava already)

That should mean that it is possible, in theory, to build with requires or requires static for jdk.unsupported based on the active JVM. It would add some build complexity, but it's possible. So I think that means the options are:

• requires jdk.unsupported: All users are opting in to Unsafe whether they like it or not; this is a drawback but the benefit is that the library performs as expected out of the box (i.e. it implies no performance hit from falling back from Unsafe)

• requires static jdk.unsupported: All users can opt-in to use of Unsafe; when they upgrade Guava, depending on the shape of their workload, they may see a performance hit, but only if they are using fully modular Java, which would be a new use case at that library version anyway. Otherwise, on the classpath, there is no isolation and so there is no difference.

• Varied by JVM level: Perhaps, for users of Java 9 or even Java 11, we use requires jdk.unsupported, so that the library performs as expected for the vast majority of "legacy" use cases, which happen to begin building with Guava on the modulepath simply because it ships a module-info.java. For Java 11+, the module-info.java specifies requires static jdk.unsupported, and we trust more modern Java users (who are building in a fully modular manner, remember, classpath is still fine) to add requires jdk.unsupported if they need it.

Thoughts? Maybe this is overthinking it, I'm not sure.

[sgammon]

(Also, it would be helpful to see the actual performance hit that should realistically be expected; I'm midway through breaking the benchmark suite out and modernizing with JMH, so perhaps we'll look to some numbers from there or Caliper to help inform this. I think a big question mark is exactly what performance drop would be expected with the loss of Unsafe as a default.)

[norrisjeremy]

Yes, perhaps adding requires static jdk.unsupported to avoid a hard requirement on it at runtime would work?
I believe users that are performance sensitive and also desiring the ability to then also use Guava on the module-path instead of class-path could still make it work by adding --add-exports jdk.unsupported/sun.misc=com.google.common --add-opens jdk.unsupported/sun.misc=com.google.common to their application.

[sgammon]

New complication to this: failureaccess will need to see a modular release. I've added a definition and set the current version to 1.0.3-jpms. It will be added shortly to the attic repo.

[Sineaggi]

What's left to get this merged?