Mess around more with Javadoc and Maven toolchains:

- Use Temurin over Zulu. Per [advice](#7492 (comment)) from @ben-manes, LTS versions of Temurin [come pre-installed](https://github.com/actions/setup-java/blob/main/docs/advanced-usage.md#Hosted-Tool-Cache). - But be willing to run with any JDK of the appropriate version that's available, rather than requiring Zulu. (Not that this makes a huge difference, given that we'll still *download* Temurin JDKs. I didn't think this through much. I guess you can now at least avoiding downloading a Temurin JDK if you make sure you already have enough JDKs registered and you pass `-Dtoolchain.skip`.) - Make the test jobs fail [if they need to download a needed JDK](https://github.com/linux-china/toolchains-maven-plugin#how-to-skip-toolchains-maven-plugin-on-cicd-platform) because we didn't already put that one in place with `setup-java`. (Our other CI jobs, which publish snapshots to Sonatype and regenerate snapshot Javadoc, will continue to tolerate missing JDKs. We could change them, too, by making their scripts pass through options to identify the run as a CI run.) This should help us keep our versions in sync, and it should prevent us from silently falling back to slower downloads, per b/334979149. - Use Java 21 to generate Javadoc (as that's the best we can do now without [further trouble](#6790 (comment))). I've made sure to make Java 21 available through `setup-java`, including for generating Sonatype snapshots, which [do include Javadoc](https://oss.sonatype.org/content/repositories/snapshots/com/google/guava/guava/HEAD-jre-SNAPSHOT/). Plus, use Java 23 for the Maven VM itself there (so as to standardize on the same version as we already use for the Maven VM itself during our test workflows as of cl/711476575). - Fix a few Javadoc warnings, leaving behind only [a handful that we can't easily do anything about](#6790 (comment)). - Download Java 11 only when it is required. Currently, that's for JDiff and for our Gradle integration tests. There is a decent chance that this CL will break something, possibly not until we run the snapshot steps after submission... :) RELNOTES=n/a PiperOrigin-RevId: 711746683
google · Jan 3, 2025 · c171b9c · c171b9c
1 parent 1a300f6
commit c171b9c
Show file tree

Hide file tree

Showing 9 changed files with 96 additions and 59 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -39,24 +39,24 @@ jobs:
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
       # When we specify multiple JDKs, the final one becomes the default, which is used to execute Maven itself.
       # Our Maven configuration then specifies different JDKs to use for some of the steps:
-      # - 11 for building Javadoc
+      # - 11 (sometimes) to *download* to support anyone who runs JDiff or our Gradle integration tests (including our doc snapshots and our Java 11 CI test run) but not to use directly
+      # - 21 for building Javadoc
       # - 23 for running javac (to help people who build Guava locally and might not use a recent JDK to run Maven)
-      # (Note that we also use Java 11 for running our Gradle integration tests. But we run those only when we are already going to run tests under Java 11.)
       - name: 'Set up JDKs'
         uses: actions/setup-java@8df1039502a15bceb9433410b1a100fbe190c53b # v4.5.0
         with:
           java-version: |
             ${{ matrix.java }}
-            11
+            21
             23
-          distribution: 'zulu'
+          distribution: 'temurin'
           cache: 'maven'
       - name: 'Install'
         shell: bash
-        run: ./mvnw -B -Dorg.slf4j.simpleLogger.log.org.apache.maven.cli.transfer.Slf4jMavenTransferListener=warn install -U -DskipTests=true -f $ROOT_POM
+        run: ./mvnw -B -Dorg.slf4j.simpleLogger.log.org.apache.maven.cli.transfer.Slf4jMavenTransferListener=warn -Dtoolchain.skip install -U -DskipTests=true -f $ROOT_POM
       - name: 'Test'
         shell: bash
-        run: ./mvnw -B -P!standard-with-extra-repos verify -U -Dmaven.javadoc.skip=true -Dsurefire.toolchain.version=${{ matrix.java }} -f $ROOT_POM
+        run: ./mvnw -B -P!standard-with-extra-repos -Dtoolchain.skip verify -U -Dmaven.javadoc.skip=true -Dsurefire.toolchain.version=${{ matrix.java }} -f $ROOT_POM
       - name: 'Print Surefire reports'
         # Note: Normally a step won't run if the job has failed, but this causes it to
         if: ${{ failure() }}
@@ -75,14 +75,15 @@ jobs:
     steps:
       - name: 'Check out repository'
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-      - name: 'Set up JDK 21'
+      - name: 'Set up JDKs'
         uses: actions/setup-java@8df1039502a15bceb9433410b1a100fbe190c53b # v4.5.0
         with:
-          java-version: 21
-          distribution: 'zulu'
-          server-id: sonatype-nexus-snapshots
-          server-username: CI_DEPLOY_USERNAME
-          server-password: CI_DEPLOY_PASSWORD
+          # For discussion, see the first setup-java block.
+          # The publish-snapshot workflow doesn't run tests, so we don't have to care which version Maven would select for that step.
+          java-version: |
+            21
+            23
+          distribution: 'temurin'
           cache: 'maven'
       - name: 'Publish'
         env:
@@ -100,11 +101,17 @@ jobs:
     steps:
       - name: 'Check out repository'
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-      - name: 'Set up JDK 11'
+      - name: 'Set up JDKs'
         uses: actions/setup-java@8df1039502a15bceb9433410b1a100fbe190c53b # v4.5.0
         with:
-          java-version: 11
-          distribution: 'zulu'
+          # For discussion, see the first setup-java block.
+          # The generate-docs workflow doesn't run tests, so we don't have to care which version Maven would select for that step.
+          # But we need Java 11 for JDiff.
+          java-version: |
+            11
+            21
+            23
+          distribution: 'temurin'
           cache: 'maven'
       - name: 'Generate latest docs'
         env:

diff --git a/android/guava/src/com/google/common/graph/ValueGraph.java b/android/guava/src/com/google/common/graph/ValueGraph.java
@@ -17,6 +17,7 @@
 package com.google.common.graph;
 
 import com.google.common.annotations.Beta;
+import java.util.Collection;
 import java.util.Set;
 import org.jspecify.annotations.Nullable;
 

diff --git a/android/guava/src/com/google/common/primitives/package-info.java b/android/guava/src/com/google/common/primitives/package-info.java
@@ -29,7 +29,7 @@
  * <ul>
  *   <li>{@link ImmutableDoubleArray}
  *   <li>{@link ImmutableIntArray}
- *   <li>{@link ImmutableLongrray}
+ *   <li>{@link ImmutableLongArray}
  *   <li>{@link UnsignedInteger}
  *   <li>{@link UnsignedLong}
  * </ul>

diff --git a/android/guava/src/com/google/common/util/concurrent/ExecutionSequencer.java b/android/guava/src/com/google/common/util/concurrent/ExecutionSequencer.java
@@ -29,6 +29,7 @@
 import com.google.errorprone.annotations.concurrent.LazyInit;
 import java.util.concurrent.Callable;
 import java.util.concurrent.Executor;
+import java.util.concurrent.Future;
 import java.util.concurrent.atomic.AtomicReference;
 import org.jspecify.annotations.Nullable;
 

diff --git a/android/pom.xml b/android/pom.xml
@@ -194,7 +194,6 @@
         <plugin>
           <groupId>org.mvnsearch</groupId>
           <artifactId>toolchains-maven-plugin</artifactId>
-          <version>4.5.0</version>
           <executions>
             <!--
             We can apparently have only one <jdk> per execution: Others are silently ignored :(
@@ -203,15 +202,15 @@
             (But don't run that if you have put something into ~/.m2/toolchains.xml yourself.)
             -->
             <execution>
-              <id>download-11</id>
+              <id>download-21</id>
               <goals>
                 <goal>toolchain</goal>
               </goals>
               <configuration>
                 <toolchains>
                   <jdk>
-                    <version>11</version>
-                    <vendor>zulu</vendor>
+                    <version>21</version>
+                    <vendor>temurin</vendor>
                   </jdk>
                 </toolchains>
               </configuration>
@@ -225,11 +224,11 @@
                 <toolchains>
                   <jdk>
                     <version>23</version>
-                    <vendor>zulu</vendor>
+                    <vendor>temurin</vendor>
                   </jdk>
                   <testJdk>
                     <version>${surefire.toolchain.version}</version>
-                    <vendor>zulu</vendor>
+                    <vendor>temurin</vendor>
                   </testJdk>
                 </toolchains>
               </configuration>
@@ -250,7 +249,6 @@
             <toolchains>
               <jdk>
                 <version>23</version>
-                <vendor>zulu</vendor>
               </jdk>
             </toolchains>
           </configuration>
@@ -332,10 +330,9 @@
           <artifactId>maven-javadoc-plugin</artifactId>
           <version>3.11.1</version>
           <configuration>
-            <!-- TODO: b/286965322 - Use a newer version (probably the default javac toolchain we set up?) if it doesn't break Javadoc (including causing trouble for our later run of JDiff, which we do outside Maven, during snapshots/releases). At that point, we'll likely want to remove the no-module-directories additionalJOption, as documented below. -->
             <jdkToolchain>
-              <version>11</version>
-              <vendor>zulu</vendor>
+              <version>21</version>
+              <vendor>temurin</vendor>
             </jdkToolchain>
             <quiet>true</quiet>
             <notimestamp>true</notimestamp>
@@ -348,14 +345,6 @@
             </additionalOptions>
             <linksource>true</linksource>
             <source>8</source>
-            <!--
-                Required to make symbol search work correctly in the generated pages under JDK 11-12.
-
-                This flag does not exist on 9-10 and 13+ (https://bugs.openjdk.java.net/browse/JDK-8215582).
-
-                Consider removing it once our Javadoc generation is migrated to a recent JDK.
-             -->
-            <additionalJOption>--no-module-directories</additionalJOption>
           </configuration>
           <executions>
             <execution>
@@ -378,7 +367,6 @@
           <configuration>
             <jdkToolchain>
               <version>${surefire.toolchain.version}</version>
-              <vendor>zulu</vendor>
             </jdkToolchain>
             <includes>
               <include>${test.include}</include>
@@ -420,6 +408,11 @@
           <artifactId>build-helper-maven-plugin</artifactId>
           <version>3.4.0</version>
         </plugin>
+        <plugin>
+          <groupId>org.mvnsearch</groupId>
+          <artifactId>toolchains-maven-plugin</artifactId>
+          <version>4.5.0</version>
+        </plugin>
       </plugins>
     </pluginManagement>
   </build>
@@ -511,11 +504,32 @@
         <test.add.opens></test.add.opens>
       </properties>
     </profile>
-    <!-- The Gradle integration tests need to set JAVA_HOME to the location of Java 11. The following profile extracts that location. -->
+    <!-- JDiff and the Gradle integration tests need Java 11 to be installed, and they need to know where it's located so that they can set JAVA_HOME to point to it. The following profile downloads a temurin Java 11 (if one isn't already available) and writes its location to target/java_11_home. This lets our JDiff and Gradle-integration-test scripts invoke the `print-java-11-home` profile and then read that file. -->
     <profile>
       <id>print-java-11-home</id>
       <build>
         <plugins>
+          <plugin>
+            <groupId>org.mvnsearch</groupId>
+            <artifactId>toolchains-maven-plugin</artifactId>
+            <executions>
+              <execution>
+                <id>download-11</id>
+                <phase>initialize</phase>
+                <goals>
+                  <goal>toolchain</goal>
+                </goals>
+                <configuration>
+                  <toolchains>
+                    <jdk>
+                      <version>11</version>
+                      <vendor>temurin</vendor>
+                    </jdk>
+                  </toolchains>
+                </configuration>
+              </execution>
+            </executions>
+          </plugin>
           <plugin>
             <artifactId>maven-toolchains-plugin</artifactId>
             <executions>
@@ -531,7 +545,6 @@
               <toolchains>
                 <jdk>
                   <version>11</version>
-                  <vendor>zulu</vendor>
                 </jdk>
               </toolchains>
             </configuration>

diff --git a/guava/src/com/google/common/graph/ValueGraph.java b/guava/src/com/google/common/graph/ValueGraph.java
@@ -17,6 +17,7 @@
 package com.google.common.graph;
 
 import com.google.common.annotations.Beta;
+import java.util.Collection;
 import java.util.Optional;
 import java.util.Set;
 import org.jspecify.annotations.Nullable;

diff --git a/guava/src/com/google/common/primitives/package-info.java b/guava/src/com/google/common/primitives/package-info.java
@@ -29,7 +29,7 @@
  * <ul>
  *   <li>{@link ImmutableDoubleArray}
  *   <li>{@link ImmutableIntArray}
- *   <li>{@link ImmutableLongrray}
+ *   <li>{@link ImmutableLongArray}
  *   <li>{@link UnsignedInteger}
  *   <li>{@link UnsignedLong}
  * </ul>

diff --git a/guava/src/com/google/common/util/concurrent/ExecutionSequencer.java b/guava/src/com/google/common/util/concurrent/ExecutionSequencer.java
@@ -29,6 +29,7 @@
 import com.google.errorprone.annotations.concurrent.LazyInit;
 import java.util.concurrent.Callable;
 import java.util.concurrent.Executor;
+import java.util.concurrent.Future;
 import java.util.concurrent.atomic.AtomicReference;
 import org.jspecify.annotations.Nullable;