Cache Maven and Gradle wrapper distributions separately from the dependency cache (#1097)

* Cache Maven wrapper distribution separately from the local repository

The Maven wrapper distribution (~/.m2/wrapper/dists) was cached in the same
entry as the local Maven repository (~/.m2/repository), keyed on a hash of
**/pom.xml (plus wrapper properties and extensions). Because pom.xml changes
frequently and no restoreKeys are used (by design, #269), almost every change
produces a full cache miss and the wrapper distribution is re-downloaded via
mvnw — which intermittently fails due to upstream rate limiting.

The wrapper distribution only depends on maven-wrapper.properties, which
changes very rarely. Give it its own cache entry keyed solely on
**/.mvn/wrapper/maven-wrapper.properties so it survives the frequent pom.xml
changes that rotate the main dependency cache key.

- Add a generic additionalCaches concept to PackageManager, restored and saved
  independently with name-scoped state keys.
- Move ~/.m2/wrapper/dists out of the main maven path into a maven-wrapper
  additional cache; skip silently when the project does not use mvnw.
- Keep cache-hit / cache-primary-key outputs driven by the main cache.
- Update tests, docs, and rebuild dist bundles.

Fixes #1095

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* Cache Gradle wrapper distribution separately from the dependency cache (#1098)

The Gradle wrapper distribution (~/.gradle/wrapper) only depends on
gradle-wrapper.properties, which changes rarely, but it was previously
cached in the same entry as ~/.gradle/caches, keyed on volatile
**/*.gradle* files with no restoreKeys (issue #269). Every dependency
change therefore re-downloaded the wrapper.

Move ~/.gradle/wrapper into a dedicated `gradle-wrapper` additional
cache keyed only on **/gradle-wrapper.properties, reusing the
additionalCaches infrastructure introduced for the Maven wrapper fix.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* Fix broken try/catch in saveAdditionalCache and rebuild dist

The autofix commits dropped the `} catch (error) {` line in
saveAdditionalCache, leaving a `try` block without a catch and a dangling
`error` reference, which broke compilation and Prettier. Restore the catch
clause, reformat, and regenerate the dist bundles.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* Address cache.ts review feedback

- saveAdditionalCache: handle @actions/cache ValidationError (thrown when the
  cache paths do not resolve, e.g. the wrapper distribution was never
  downloaded) by skipping instead of failing the post step. Add a test.
- Point the Gradle wrapper cache comment at issue #269 (Gradle wrapper cache
  churn) instead of the Maven-specific #1095.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* Document Gradle Wrapper distribution caching in README

Add a parallel "Gradle Wrapper" note alongside the Maven Wrapper note, so the
new behavior for cache: 'gradle' (caching ~/.gradle/wrapper in a separate entry
keyed on **/gradle-wrapper.properties) is documented.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

docs/advanced-usage.md

@@ -304,8 +304,7 @@ To run the JavaFX application in CI:
 ## Ensuring the Maven cache is complete (plugin dependencies)
 
 When you enable `cache: maven`, the action caches your local Maven repository
-(`~/.m2/repository`) and downloaded Maven Wrapper distributions
-(`~/.m2/wrapper/dists`). The cache key is a hash of your Maven inputs — every
+(`~/.m2/repository`). The cache key is a hash of your Maven inputs — every
 `**/pom.xml`, plus `**/.mvn/wrapper/maven-wrapper.properties` and
 `**/.mvn/extensions.xml` — so changing any of those files (for example bumping
 the wrapper version or editing core extensions) produces a new key and
@@ -313,6 +312,14 @@ invalidates the cache. At the end of the job the action saves whatever was
 downloaded during that run. It does **not** re-save the cache when the key
 already matches (a cache *hit*).
 
+Downloaded Maven Wrapper distributions (`~/.m2/wrapper/dists`) are cached in a
+**separate** cache entry keyed only on `**/.mvn/wrapper/maven-wrapper.properties`.
+Because the wrapper distribution changes far less often than your `pom.xml`
+files, this keeps it available across the frequent dependency changes that
+rotate the main cache key, so wrapper-based (`./mvnw`) builds don't re-download
+the Maven distribution on every dependency change. See
+[issue #1095](https://github.com/actions/setup-java/issues/1095).
+
 Maven resolves **plugin** dependencies lazily: it only downloads the plugins and
 plugin dependencies required by the goals that actually execute. As a result, the
 run that first creates the cache determines what is stored. If that run executed a