Fail on misconfigured plugin-requested toolchains

[wilx]

Fixes apache/maven-compiler-plugin#618

Maven Compiler Plugin passes its jdkToolchain requirements to Maven Core's
public per-plugin ToolchainManager#getToolchains(...) API. Maven 3 previously
caught MisconfiguredToolchainException, logged it, and returned an empty list.
The compiler plugin consequently fell back to the JDK running Maven and could
report BUILD SUCCESS despite an explicitly requested malformed toolchain.

This change propagates an IllegalStateException with the toolchain type and
the original diagnostic, retaining MisconfiguredToolchainException as its
cause. An unchecked exception avoids changing the established Maven 3 public
method signature; adding a checked exception would break source compatibility
for plugin callers. Valid toolchains that do not match continue to produce an
empty selection, and missing toolchain factories retain their existing
log-and-empty-list behavior.

The regression test exercises the public per-plugin lookup with a real
JavaToolchainFactory, matching requirements, and a nonexistent jdkHome. A
separate control verifies that a valid nonmatching toolchain remains nonfatal.

Verification:

• mvn -pl maven-core -Dtest=DefaultToolchainManagerTest test
• mvn -pl maven-core verify — 366 tests, 1 skipped
• mvn verify — all 16 reactor modules successful
• Maven Core ITs maven-3.10.x at 70eabb0679, run under JDK 8 against
  apache-maven-3.10.0-SNAPSHOT-bin.zip from this branch
  (SHA-256 67b1c28163ecbf09417e262f3f1fc59ff8987fa076a5956b219cc0a97331a53a):
  mvn -B -V clean install -Prun-its -Dmaven.repo.local=/home/wilx/maven-sources/core/3.x/its-3/repo -DmavenDistro=/home/wilx/maven-sources/core/maven-issue-mcompiler-618-misconfigured-toolchain/apache-maven/target/apache-maven-3.10.0-SNAPSHOT-bin.zip
  — 867 tests, 0 failures, 0 errors, 40 skipped; all 78 reactor modules
  successful.
• Maven Compiler Plugin 3.15.0 reproducer:
  • Maven 3.9.16 logged the malformed toolchain, compiled with its runtime JDK,
    and returned BUILD SUCCESS.
  • The patched Maven 3.10.0-SNAPSHOT returned BUILD FAILURE with the invalid
    JDK path and did not compile the source.
  • A valid JDK 17 toolchain requested as version 21 remained a normal
    nonmatch and the build proceeded normally.

Following this checklist to help us incorporate your
contribution quickly and easily:

• Your pull request should address just one issue, without pulling in other changes.
• Write a pull request description that is detailed enough to understand what the pull request does, how, and why.
• Each commit in the pull request should have a meaningful subject line and body.
  Note that commits might be squashed by a maintainer on merge.
• Write unit tests that match behavioral changes, where the tests fail if the changes to the runtime are not applied.
  This may not always be possible but is a best-practice.
• Run mvn verify to make sure basic checks pass.
  A more thorough check will be performed on your pull request automatically.
• You have run the Core IT successfully.

If your pull request is about ~20 lines of code you don't need to sign an
Individual Contributor License Agreement if you are unsure
please ask on the developers list.

To make clear that you license your contribution under
the Apache License Version 2.0, January 2004
you have to acknowledge this by using the following check-box.

• I hereby declare this contribution to be licenced under the Apache License Version 2.0, January 2004
• In any other case, please file an Apache Individual Contributor License Agreement.

[gnodet]

Well-scoped behavioral fix that correctly changes misconfigured toolchain handling from silent swallowing (log + empty list) to fail-fast (IllegalStateException). The approach aligns with Maven 4 which already throws ToolchainManagerException on the equivalent path. Tests are thorough and well-designed.

Minor notes:

• The @throws IllegalStateException Javadoc was added to getToolchains() but not to getToolchainFromBuildContext(), which also calls the same private selectToolchains() method and can now throw the same exception. While in practice this path is unlikely to trigger (models stored in build context were already successfully created), the interface contract should document it for completeness.
• Maven 4 master already fails fast on misconfigured toolchains — the compat layer in ToolchainManagerFactory.java wraps MisconfiguredToolchainException in RuntimeException, and the v4 DefaultToolchainManager.createToolchain() throws ToolchainManagerException. This PR brings Maven 3.10.x into alignment with that behavior using IllegalStateException, which is the right choice given the public API constraint.

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

Claude Code on behalf of gnodet

[wilx]

Fixed this:

The @throws IllegalStateException Javadoc was added to getToolchains() but not to getToolchainFromBuildContext(), which also calls the same private selectToolchains() method and can now throw the same exception. While in practice this path is unlikely to trigger (models stored in build context were already successfully created), the interface contract should document it for completeness.

[gnodet]

Re-review after new commit ✅

The new commit correctly adds the missing @throws IllegalStateException Javadoc to getToolchainFromBuildContext(), completing the documentation that was initially only applied to getToolchains(). Both methods delegate to the shared selectToolchains private method where the exception is thrown, so the annotation accurately reflects runtime behavior.

No remaining issues — the behavioral change, tests, and documentation are all consistent and well-scoped.

---

Reviewed via automated review loop · Feedback? Tag @gnodet