Backport #1111: Preserve Maven toolchains across repeated setup-java runs (#1099)

[brunoborges]

Summary

Backport of #1111 to the releases/v5 branch. Fixes #1099.

Running setup-java multiple times in the same job (matrix builds or multiple java-version values) could drop toolchain entries registered by earlier runs, leaving only one JDK in ~/.m2/toolchains.xml.

Root cause

Toolchains generation was gated behind the overwrite-settings input. When overwrite-settings: false, writeToolchainsFileToDisk skipped writing entirely if the file already existed — so a second setup-java run never persisted its JDK, silently discarding the merged result.

This gating was inappropriate because:

• overwrite-settings is documented (in action.yml) to control regeneration of settings.xml only.
• generateToolchainDefinition already performs a non-destructive merge: existing JDK, custom, and user-managed toolchains are preserved, and only an entry with the exact same type + provides.id is replaced.

So writing the toolchains file is always safe and should not be blocked.

Changes

• src/toolchains.ts: Remove overwriteSettings from configureToolchains, createToolchainsSettings, and writeToolchainsFileToDisk. The toolchains file is now always written (non-destructively). settings.xml behavior in auth.ts is unchanged.
• __tests__/toolchains.test.ts: Update call sites, rewrite the "does not overwrite" test to assert non-destructive extension, and add a regression test that runs configureToolchains three times and asserts every JDK is preserved with no duplicates.
• docs/advanced-usage.md: Clarify that the merge is non-destructive and independent of overwrite-settings.
• dist/setup/index.js: Rebuilt.

Backport notes

releases/v5 predates the ESM migration on main, so the change was re-applied to v5's CommonJS sources rather than cherry-picked (imports use ./util/./constants without .js, and the new regression test uses jest.spyOn(core, 'getInput') to match v5's mocking style instead of unstable_mockModule). The net behavioral change is identical to #1111.

Testing

• npm run build, format-check, and lint all pass.
• npm test: the toolchains suite passes (15/15), including the new regression test; full suite passes on clean runs.

Fixes #1099

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

[Copilot]

Pull request overview

This PR backports the fix for #1099 to releases/v5, ensuring repeated setup-java executions in the same job do not drop previously-registered Maven toolchain entries in ~/.m2/toolchains.xml.

Changes:

• Always write toolchains.xml after performing the non-destructive merge, removing the incorrect gating on overwrite-settings.
• Update and extend the toolchains test suite, including a regression test covering multiple consecutive configureToolchains runs.
• Clarify documentation around non-destructive toolchain merging and the fact that it’s independent of overwrite-settings; rebuild the bundled dist output.

Show a summary per file

File	Description
src/toolchains.ts	Removes overwrite-settings gating so merged toolchains are always persisted across multiple runs.
tests/toolchains.test.ts	Updates call sites and adds regression coverage to ensure toolchains accumulate without duplication.
docs/advanced-usage.md	Documents that toolchain merging is non-destructive and independent of overwrite-settings.
dist/setup/index.js	Rebuilt distribution output reflecting the source changes.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 3/4 changed files
• Comments generated: 1
• Review effort level: Low