Add conditional JDK caching (#1201)

* Add JDK caching

Cache resolved JDK tool-cache entries by exact platform and release identity, with a default-on cache-jdk input and explicit opt-out.

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

* Apply batched suggestions from code review

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

* Fix JDK cache CI validation

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

* Update brace-expansion security fix

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

* Refresh brace-expansion license metadata

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

* Refine JDK cache semantics

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

* Refine JDK cache documentation

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

* Simplify JDK cache identity

Use one normalized runner OS dimension, reset the internal cache key schema for the unreleased feature, and align documentation, tests, and bundles.

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

* Align JDK cache OS identity

Use the established RUNNER_OS value directly and retain process.platform only as a non-Actions fallback.

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

* Harden JDK cache saves and document tool-cache reuse

Bind each JDK cache key to the installation identity it was computed for,
keep post-job saves best-effort per entry, and state the real reuse and
verification guarantee in the documentation.

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

* docs: restructure README caching section

Rename '## Caching dependencies' to '## Caching' and add a what-gets-cached
overview table covering the dependency, wrapper, and JDK caches. Lead with the
common 'cache: maven' example and the dependency-cache material, and demote JDK
caching into its own subsection.

Also corrects the IMPORTANT callout, which implied JDK caching required an
explicit opt-in; it is enabled implicitly whenever 'cache' is set.

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

* docs: fix caching documentation defects

- Remove pull-request framing that compared behavior to `main`; state the
  tool-cache and `jdkfile` behavior directly and unconditionally.
- Clarify that the JDK cache is a separate cache *entry* from the dependency
  and wrapper caches, while its *enablement* is coupled to `cache`, so the
  opening paragraph agrees with the enablement matrix.
- Cite the actions/setup-java-benchmarks repository instead of an open PR and
  a self-referential PR comment, keeping the measured figures and caveats.
- Keep the `cache`/`cache-jdk` matrix only in docs/advanced-usage.md and
  summarize the rules in prose in README.md to avoid divergence.
- Describe the guarantee that a cache key is only saved with the installation
  it was computed for, instead of documenting inode/size/timestamp internals.

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

* docs: add V6 what's new entry for JDK caching

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: e2755464-4e83-47b6-ba71-731bb481b418

---------

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>
Copilot-Session: e2755464-4e83-47b6-ba71-731bb481b418

__tests__/setup-java.test.ts

@@ -33,7 +33,8 @@ jest.unstable_mockModule('fs', () => ({
 
 jest.unstable_mockModule('../src/util.js', () => ({
   getBooleanInput: jest.fn(),
-  getVersionFromFileContent: jest.fn()
+  getVersionFromFileContent: jest.fn(),
+  isJdkCacheEnabled: jest.fn()
 }));
 
 jest.unstable_mockModule('../src/toolchains.js', () => ({
@@ -113,6 +114,14 @@ describe('setup action orchestration', () => {
         return booleanInputs.get(name as string) ?? defaultValue;
       }
     );
+    (util.isJdkCacheEnabled as jest.Mock).mockImplementation(
+      (cache: string) => {
+        const explicit = inputs.get('cache-jdk');
+        return explicit
+          ? (booleanInputs.get('cache-jdk') ?? explicit === 'true')
+          : Boolean(cache);
+      }
+    );
     (cacheFeature.isCacheFeatureAvailable as jest.Mock).mockReturnValue(true);
     (toolchainIds.validateToolchainIds as jest.Mock).mockImplementation(
       () => undefined
@@ -217,6 +226,7 @@ describe('setup action orchestration', () => {
         packageType: 'jdk',
         checkLatest: true,
         forceDownload: true,
+        cacheJdk: false,
         setDefault: false,
         verifySignature: true,
         verifySignaturePublicKey: 'public-key'
@@ -457,6 +467,7 @@ describe('setup action orchestration', () => {
   it('does not initialize cache modules when cache input is absent', async () => {
     inputs.set('distribution', 'temurin');
     multilineInputs.set('java-version', ['21']);
+    booleanInputs.set('cache-jdk', false);
     (factory.getJavaDistribution as jest.Mock).mockReturnValue({
       setupJava: jest.fn(async () => ({
         version: '21.0.4+7',
@@ -468,8 +479,47 @@ describe('setup action orchestration', () => {
 
     expect(cacheFeature.isCacheFeatureAvailable).not.toHaveBeenCalled();
     expect(cache.restore).not.toHaveBeenCalled();
+    expect(factory.getJavaDistribution).toHaveBeenCalledWith(
+      'temurin',
+      expect.objectContaining({cacheJdk: false}),
+      ''
+    );
   });
 
+  it.each([
+    ['', '', false],
+    ['', 'true', true],
+    ['', 'false', false],
+    ['maven', '', true],
+    ['maven', 'true', true],
+    ['maven', 'false', false]
+  ])(
+    'passes effective JDK caching for cache=%j and cache-jdk=%j',
+    async (cacheInput, cacheJdkInput, expected) => {
+      inputs.set('distribution', 'temurin');
+      inputs.set('cache', cacheInput);
+      inputs.set('cache-jdk', cacheJdkInput);
+      multilineInputs.set('java-version', ['21']);
+      if (cacheJdkInput) {
+        booleanInputs.set('cache-jdk', cacheJdkInput === 'true');
+      }
+      (factory.getJavaDistribution as jest.Mock).mockReturnValue({
+        setupJava: jest.fn(async () => ({
+          version: '21.0.4+7',
+          path: '/opt/java/21'
+        }))
+      });
+
+      await run();
+
+      expect(factory.getJavaDistribution).toHaveBeenCalledWith(
+        'temurin',
+        expect.objectContaining({cacheJdk: expected}),
+        ''
+      );
+    }
+  );
+
   it('reports unsupported distributions through core.setFailed', async () => {
     inputs.set('distribution', 'unsupported');
     multilineInputs.set('java-version', ['21']);