fix(java): use Maven mirror, remove unnecessary plugins, other CI-stability improvements (#2253)

Contributes to NVIDIA/cuvs-lucene#145

Java builds have been failing like this:

```text
Error:  Unresolveable build extension: Plugin org.sonatype.plugins:nexus-staging-maven-plugin:1.6.7 or one of its dependencies could not be resolved:
	Failed to read artifact descriptor for org.sonatype.plugins:nexus-staging-maven-plugin:jar:1.6.7
```

This is hiding the true issue ... **we're getting rate-limited by Maven Central**, with requests hitting `429 (Too Many Requests)`.

This proposes the following changes to fix that:

* switching to the unofficial Maven Central read-only mirror on GCS
* removing unnecessary dependencies from `pom.xml`
* configuring Maven to download more slowly and wait longer between retries
* fine-tuning `changed-files` rules to reduce how often Java CI runs on PRs

And these other changes relevant to the Java builds:

* validating XML in `pre-commit` hooks (this did catch a syntax error in the Java examples' `pom.xml`!)
* removing unnecessary configuration for snapshots (this project doesn't publish or download snapshots)
* reformatting Java READMEs per https://yihui.org/en/2021/06/markdown-breath/

See inline comments for more details.

## Notes for Reviewers

### Impact

I don't believe there are any breaking changes in this PR. Our existing publishing process for `cuvs-java` should be unaffected and CI should become faster and more reliable.

If anything breaks because of it, assume that was unintentional.

### AI use

I'm not very familiar with Java packaging, so heavily relied on back-and-forth with an agent for help with this.

I wrote this PR description, code comments, and all inline review comments here myself.

My motivation is to unblock CI here and in `cuvs-lucene`. If a more qualified reviewer wants to close this and implement a different fix, please do.

Authors:
  - James Lamb (https://github.com/jameslamb)

Approvers:
  - Bradley Dice (https://github.com/bdice)
  - Corey J. Nolet (https://github.com/cjnolet)
  - Tim Liu (https://github.com/NvTimLiu)

URL: #2253

Author: jameslamb

.github/workflows/pr.yaml

@@ -160,6 +160,10 @@ jobs:
           - '!.github/workflows/trigger-breaking-change-alert.yaml'
           - '!.pre-commit-config.yaml'
           - '!.shellcheckrc'
+          - '!CODEOWNERS'
+          - '!Dockerfile'
+          - '!README.md'
+          - '!SECURITY.md'
           - '!ci/build_docs.sh'
           - '!ci/build_go.sh'
           - '!ci/build_python.sh'
@@ -171,14 +175,19 @@ jobs:
           - '!ci/test_python.sh'
           - '!ci/test_wheel_cuvs.sh'
           - '!ci/validate_wheel.sh'
-          - '!Dockerfile'
+          - '!conda/environments/**'
+          - '!conda/recipes/cuvs/**'
+          - '!conda/recipes/cuvs-bench/**'
+          - '!conda/recipes/cuvs-bench-cpu/**'
           - '!docs/**'
+          - '!examples/**'
           - '!fern/**'
+          - '!go/**'
           - '!img/**'
           - '!notebooks/**'
+          - '!pyproject.toml'
           - '!python/**'
           - '!rust/**'
-          - '!go/**'
           - '!thirdparty/LICENSES/**'
         test_python_conda:
           - '**'
@@ -192,8 +201,12 @@ jobs:
           - '!.github/labeler.yml'
           - '!.github/ops-bot.yaml'
           - '!.github/release.yml'
+          - '!.github/workflows/check-c-abi.yaml'
+          - '!.github/workflows/labeler.yml'
           - '!.github/workflows/publish-rust.yaml'
+          - '!.github/workflows/store-c-abi-baseline.yaml'
           - '!.github/workflows/trigger-breaking-change-alert.yaml'
+          - '!.github/workflows/update-c-abi-baseline.yaml'
           - '!.pre-commit-config.yaml'
           - '!.shellcheckrc'
           - '!ci/build_go.sh'
@@ -210,6 +223,7 @@ jobs:
           - '!cpp/.clang-format'
           - '!cpp/.clang-tidy'
           - '!cpp/doxygen/**'
+          - '!CODEOWNERS'
           - '!Dockerfile'
           - '!README.md'
           - '!SECURITY.md'
@@ -252,6 +266,7 @@ jobs:
           - '!ci/test_python.sh'
           - '!ci/test_standalone_c.sh'
           - '!ci/validate_wheel.sh'
+          - '!CODEOWNERS'
           - '!Dockerfile'
           - '!README.md'
           - '!SECURITY.md'
@@ -283,6 +298,7 @@ jobs:
           - '!.github/workflows/trigger-breaking-change-alert.yaml'
           - '!.pre-commit-config.yaml'
           - '!.shellcheckrc'
+          - '!CODEOWNERS'
           - '!Dockerfile'
           - '!README.md'
           - '!SECURITY.md'
@@ -324,6 +340,7 @@ jobs:
           - '!.github/workflows/trigger-breaking-change-alert.yaml'
           - '!.pre-commit-config.yaml'
           - '!.shellcheckrc'
+          - '!CODEOWNERS'
           - '!Dockerfile'
           - '!README.md'
           - '!SECURITY.md'

.pre-commit-config.yaml

@@ -3,12 +3,13 @@
 
 repos:
       - repo: https://github.com/pre-commit/pre-commit-hooks
-        rev: v5.0.0
+        rev: v6.0.0
         hooks:
               - id: check-json
               - id: trailing-whitespace
               - id: end-of-file-fixer
               - id: check-symlinks
+              - id: check-xml
       - repo: https://github.com/PyCQA/isort
         rev: 5.12.0
         hooks:

java/README.md

@@ -1,6 +1,5 @@
 # cuVS Java API
 
-
 cuVS Java API provides a Java based simple, efficient, and a robust vector search API.
 
 > [!CAUTION]
@@ -13,7 +12,6 @@ cuVS Java API provides a Java based simple, efficient, and a robust vector searc
 - [JDK 22](https://openjdk.org/projects/jdk/22/)
 - [jextract for JDK 22](https://jdk.java.net/jextract/) (If not already installed, the build script downloads it)
 
-
 ## Building
 
 The libcuvs C and C++ libraries are needed for this API. If libcuvs libraries have not been built and installed, use `./build.sh libcuvs java` in the top level directory to build this API.
@@ -26,17 +24,22 @@ do `./build.sh java` in the top level directory or just do `./build.sh` in this
 Run `./build.sh --run-java-tests` from this directory.
 
 To run a single test suite:
+
 ```sh
 cd cuvs-java/
 mvn clean integration-test -Dit.test=com.nvidia.cuvs.CagraBuildAndSearchIT
 ```
+
 or, for a single test:
+
 ```sh
 mvn clean integration-test -Dit.test=com.nvidia.cuvs.CagraBuildAndSearchIT#testMergeStrategies
 ```
+
 Be sure to set (manually, if needed) your `LD_LIBRARY_PATH` to include the directory with the appropriate (matching)
 version of `libcuvs.so`.
 Also, ensure that your panama bindings are up-to-date. They can be re-generated by running:
+
 ```sh
 ./panama-bindings/generate-bindings.sh
 ```
@@ -45,6 +48,7 @@ Tests run using a randomized runner. Specific failures can be reproduced running
 by passing `-Dtests.seed=42FC5CC6B4C6BA8E` (where `42FC5CC6B4C6BA8E` has to be
 replaced with your specific seed). It also possible to re-run a single test, but
 in this case it's necessary to pass the extended seed (suite:method), e.g.
+
 ```shell
 mvn integration-test -Dit.test=com.nvidia.cuvs.CagraBuildAndSearchIT#testFloatIndexing -Dtests.seed=66039A8CAFB9D3C9:449B6310296799E0
 ```

java/benchmarks/README.md

@@ -3,25 +3,32 @@
 This maven project contains JMH benchmarks for the CAGRA Java API.
 
 ## Prerequisites
+
 - [CuVS libraries](https://docs.rapids.ai/api/cuvs/stable/build/#build-from-source)
 - Build the CuVS-Java API (`./build.sh` from the parent directory)
 
 ## Run benchmarks
 
 Build:
+
 ```shell
 mvn clean verify
 ```
+
 Run:
+
 ```shell
 export RAFT_DEBUG_LOG_FILE=/dev/null
 java -jar target/benchmarks.jar
 ```
+
 The environment variable is needed to silence RAFT logging; RAFT emits some logs at INFO level when
 building indices and queries, and writing them to stdout (the default) influences benchmark results.
 
 It is possible to change the dataset size and the vectors dimension via 2 parameters:
+
 ```shell
 java -jar target/benchmarks.jar -p size=4 -p dims=4
 ```
+
 Use `java -jar target/benchmarks.jar -h` for details on the options to fine-tune your benchmark runs.

java/benchmarks/pom.xml

@@ -15,6 +15,60 @@
 
     <name>cuvs-java-benchmarks</name>
 
+    <repositories>
+        <!-- Prefer Google Cloud mirror, which has higher rate limits -->
+        <repository>
+            <id>gcs-maven-central-mirror</id>
+            <name>GCS Maven Central mirror</name>
+            <url>https://maven-central.storage-download.googleapis.com/maven2/</url>
+            <releases>
+                <enabled>true</enabled>
+            </releases>
+            <snapshots>
+                <enabled>false</enabled>
+            </snapshots>
+        </repository>
+        <!-- Fall back to Maven upstream for packages not found in GCS mirror -->
+        <repository>
+            <id>central</id>
+            <name>Maven Central</name>
+            <url>https://repo.maven.apache.org/maven2</url>
+            <releases>
+                <enabled>true</enabled>
+            </releases>
+            <snapshots>
+                <enabled>false</enabled>
+            </snapshots>
+        </repository>
+    </repositories>
+
+    <pluginRepositories>
+        <!-- Prefer Google Cloud mirror, which has higher rate limits -->
+        <pluginRepository>
+            <id>gcs-maven-central-mirror</id>
+            <name>GCS Maven Central mirror</name>
+            <url>https://maven-central.storage-download.googleapis.com/maven2/</url>
+            <releases>
+                <enabled>true</enabled>
+            </releases>
+            <snapshots>
+                <enabled>false</enabled>
+            </snapshots>
+        </pluginRepository>
+        <!-- Fall back to Maven upstream for packages not found in GCS mirror -->
+        <pluginRepository>
+            <id>central</id>
+            <name>Maven Plugin Repository</name>
+            <url>https://repo.maven.apache.org/maven2</url>
+            <releases>
+                <enabled>true</enabled>
+            </releases>
+            <snapshots>
+                <enabled>false</enabled>
+            </snapshots>
+        </pluginRepository>
+    </pluginRepositories>
+
     <dependencies>
         <dependency>
             <groupId>org.openjdk.jmh</groupId>
@@ -104,38 +158,14 @@
                     <artifactId>maven-clean-plugin</artifactId>
                     <version>2.5</version>
                 </plugin>
-                <plugin>
-                    <artifactId>maven-deploy-plugin</artifactId>
-                    <version>2.8.1</version>
-                </plugin>
-                <plugin>
-                    <artifactId>maven-install-plugin</artifactId>
-                    <version>2.5.1</version>
-                </plugin>
                 <plugin>
                     <artifactId>maven-jar-plugin</artifactId>
                     <version>2.4</version>
                 </plugin>
-                <plugin>
-                    <artifactId>maven-javadoc-plugin</artifactId>
-                    <version>2.9.1</version>
-                </plugin>
                 <plugin>
                     <artifactId>maven-resources-plugin</artifactId>
                     <version>2.6</version>
                 </plugin>
-                <plugin>
-                    <artifactId>maven-site-plugin</artifactId>
-                    <version>3.3</version>
-                </plugin>
-                <plugin>
-                    <artifactId>maven-source-plugin</artifactId>
-                    <version>2.2.1</version>
-                </plugin>
-                <plugin>
-                    <artifactId>maven-surefire-plugin</artifactId>
-                    <version>2.17</version>
-                </plugin>
             </plugins>
         </pluginManagement>
     </build>

java/cuvs-java/.mvn/maven.config

@@ -0,0 +1,6 @@
+-e
+-B
+-Daether.connector.basic.downstreamThreads=1
+-Daether.transport.http.retryHandler.count=5
+-Daether.transport.http.retryHandler.interval=10000
+-Dmaven.wagon.http.retryHandler.count=5

java/cuvs-java/pom.xml

@@ -1,8 +1,6 @@
 <!--
-/*
- * SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION.
- * SPDX-License-Identifier: Apache-2.0
- */
+SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
 -->
 <project xmlns="http://maven.apache.org/POM/4.0.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -54,13 +52,59 @@
         <native.build.path>${project.build.directory}/../../../cpp/build</native.build.path>
     </properties>
 
-    <distributionManagement>
-        <snapshotRepository>
-            <id>ossrh</id>
-            <url>https://oss.sonatype.org/content/repositories/snapshots</url>
-        </snapshotRepository>
-    </distributionManagement>
+    <repositories>
+        <!-- Prefer Google Cloud mirror, which has higher rate limits -->
+        <repository>
+            <id>gcs-maven-central-mirror</id>
+            <name>GCS Maven Central mirror</name>
+            <url>https://maven-central.storage-download.googleapis.com/maven2/</url>
+            <releases>
+                <enabled>true</enabled>
+            </releases>
+            <snapshots>
+                <enabled>false</enabled>
+            </snapshots>
+        </repository>
+        <!-- Fall back to Maven upstream for packages not found in GCS mirror -->
+        <repository>
+            <id>central</id>
+            <name>Maven Central</name>
+            <url>https://repo.maven.apache.org/maven2</url>
+            <releases>
+                <enabled>true</enabled>
+            </releases>
+            <snapshots>
+                <enabled>false</enabled>
+            </snapshots>
+        </repository>
+    </repositories>
 
+    <pluginRepositories>
+        <!-- Prefer Google Cloud mirror, which has higher rate limits -->
+        <pluginRepository>
+            <id>gcs-maven-central-mirror</id>
+            <name>GCS Maven Central mirror</name>
+            <url>https://maven-central.storage-download.googleapis.com/maven2/</url>
+            <releases>
+                <enabled>true</enabled>
+            </releases>
+            <snapshots>
+                <enabled>false</enabled>
+            </snapshots>
+        </pluginRepository>
+        <!-- Fall back to Maven upstream for packages not found in GCS mirror -->
+        <pluginRepository>
+            <id>central</id>
+            <name>Maven Plugin Repository</name>
+            <url>https://repo.maven.apache.org/maven2</url>
+            <releases>
+                <enabled>true</enabled>
+            </releases>
+            <snapshots>
+                <enabled>false</enabled>
+            </snapshots>
+        </pluginRepository>
+    </pluginRepositories>
 
     <dependencies>
 
@@ -204,17 +248,6 @@
                     </execution>
                 </executions>
             </plugin>
-            <plugin>
-                <groupId>org.sonatype.plugins</groupId>
-                <artifactId>nexus-staging-maven-plugin</artifactId>
-                <version>1.6.7</version>
-                <extensions>true</extensions>
-                <configuration>
-                    <serverId>ossrh</serverId>
-                    <nexusUrl>https://oss.sonatype.org/</nexusUrl>
-                    <autoReleaseAfterClose>false</autoReleaseAfterClose>
-                </configuration>
-            </plugin>
             <plugin>
                 <groupId>com.diffplug.spotless</groupId>
                 <artifactId>spotless-maven-plugin</artifactId>