Auto-select JDK toolchain when running JDK cannot compile source level by gnodet · Pull Request #12633 · apache/maven

gnodet · 2026-07-30T14:32:14Z

Summary

When the running JDK does not support a project's --source/--release level (e.g., JDK 21 cannot compile --source 6), Maven now automatically searches for a compatible JDK and selects it for compilation — no configuration needed.

This is a zero-cost feature: auto-selection only triggers when the running JDK is genuinely incompatible. Normal builds see no change.

How it works

DefaultToolchainManager.getToolchainFromBuildContext() gains a two-stage fallback for "jdk" type:

If an explicit toolchain is stored (via maven-toolchains-plugin), return it immediately (unchanged behavior)
Read the project's required source level from:
- Model 4.1.0 <source><targetVersion> elements
- Legacy properties: maven.compiler.release, maven.compiler.source
- Compiler plugin configuration: <configuration><release>, <configuration><source>
If the running JDK supports that level → return empty (no auto-selection needed)
Search configured toolchains (toolchains.xml) for the newest compatible JDK
If no match, lazily discover JDKs from the filesystem via JdkToolchainDiscoverer
Cache the result and emit warnings:

[WARNING] Project requires --source 6 which is not supported by JDK 21.
[WARNING] Automatically selected JDK 11 (discovered at /usr/lib/jvm/java-11) for compilation.
[WARNING] To suppress this warning, configure the maven-toolchains-plugin explicitly
[WARNING] or set <targetVersion> to a value supported by your JDK.

Lazy filesystem discovery (`JdkToolchainDiscoverer`)

Scans well-known locations — only when needed (running JDK incompatible AND no configured toolchain matches):

Environment: JAVA_HOME, JAVA*_HOME env vars, java.home system property, plus sibling directories of each (for CI environments where multiple JDKs are installed under the same parent)
Tool managers: SDKMan, IntelliJ .jdks/, Gradle .gradle/jdks/, jEnv, JBang, asdf, Jabba, mise, Maven .m2/jdks/
OS paths: Linux (/usr/lib/jvm, /opt/java, etc.), macOS (/Library/Java/JavaVirtualMachines with Contents/Home handling), Windows (C:\Program Files\Java, Adoptium, Zulu, Corretto, Scoop)

JDK version is read from the release file (present since JDK 9) — no java processes are spawned. Results are cached in memory after first discovery. All environment access goes through Session.getSystemProperties(), not System.*.

Source level compatibility (`JdkSourceLevelSupport`)

Maps JDK major versions to their supported --source levels based on JEP 182:

JDK 9: dropped source 1–5, minimum is 6
JDK 12: dropped source 6, minimum is 7
JDK 21: dropped source 7, minimum is 8

Compat layer

ToolchainManagerFactory (v3 compat bridge) now passes the JdkToolchainDiscoverer through to DefaultToolchainManager, so plugins going through the v3 API also benefit from filesystem discovery.

New files

File	Description
`JdkSourceLevelSupport`	JDK version → source level mapping (JEP 182 schedule)
`JdkToolchainDiscoverer`	Lazy filesystem JDK discovery from env vars, tool managers, OS paths
`JdkSourceLevelSupportTest`	14 tests
`JdkToolchainDiscovererTest`	18 tests
`DefaultToolchainManagerTest`	17 tests for auto-selection
`MavenITAutoJdkToolchainSelectTest`	2 integration tests

Test plan

Unit tests: source level normalization (legacy 1.5→5, 1.8.0_392→8, dotted 21.0.1→21), release file parsing (JDK 8/11/17), JDK home validation, macOS bundle resolution, caching, properties-based collection
Unit tests: auto-selection logic, discovery fallback, explicit toolchain precedence, compiler plugin config detection
Integration tests: project with source=6 on JDK 12+ → auto-selects; project with source=11 on JDK 12+ → no selection
CI green on all platforms (Linux, macOS, Windows) × JDK versions (17, 21, 25)

🤖 Generated with Claude Code

…'s source level When the running JDK does not support the project's --source/--release level (e.g., JDK 17 cannot compile --source 6), Maven now automatically searches configured toolchains for a compatible JDK and selects it for compilation. The auto-selection hooks into getToolchainFromBuildContext() — when no explicit toolchain has been set via maven-toolchains-plugin, the manager checks the project's targetVersion (Model 4.1.0) or legacy properties (maven.compiler.release, maven.compiler.source) against the running JDK's supported source levels. If the running JDK cannot handle the required level, it picks the newest compatible JDK from configured toolchains, caches the selection, and emits a warning. Key changes: - New JdkSourceLevelSupport utility mapping JDK versions to supported --source levels based on the javac retirement schedule (JEP 182) - DefaultToolchainManager.getToolchainFromBuildContext() now falls back to auto-selection for "jdk" type when no explicit toolchain is stored - Reads source level from Model 4.1.0 <source><targetVersion> elements and legacy maven.compiler.release/source properties - Prefers the newest compatible JDK from configured toolchains Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Two ITs verify the auto-selection behavior end-to-end through Maven's compat bridge: - testAutoSelectToolchainWhenSourceLevelUnsupported: project requires source 6 (unsupported by JDK 12+), verifies Maven auto-selects a compatible JDK 11 toolchain and logs a warning - testNoAutoSelectWhenSourceLevelSupported: project requires source 11 (supported by JDK 12+), verifies no auto-selection occurs Also adds debug logging to the auto-selection path for diagnostics. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

elharo

Good idea. does this need an issue to get picked up in the release notes?

gnodet · 2026-07-30T16:49:58Z

Good idea. does this need an issue to get picked up in the release notes?

No, an issue and a PR are similar in all points, but the fact that an issue does not have code.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

When no compatible JDK is found in toolchains.xml, Maven now lazily discovers JDKs from the filesystem by scanning well-known locations: JAVA*_HOME env vars, SDKMan, IntelliJ .jdks/, Gradle, jEnv, JBang, asdf, mise, and OS-specific paths (/usr/lib/jvm, etc.). Discovery only runs on the failure path (running JDK incompatible AND no configured toolchain matches), so normal builds pay zero cost. JDK version is read from the release file (no java process spawned). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Replace direct System.getProperty/System.getenv calls with the properties map from Session.getSystemProperties(), where env vars are available as "env.VAR_NAME" entries. This follows Maven's convention of accessing environment through the Session and makes the discoverer fully testable without relying on JVM global state. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…nd JDK discovery Three fixes for automatic JDK toolchain selection: 1. Read source level from compiler plugin configuration: many projects set <source> and <release> directly in the maven-compiler-plugin <configuration> block rather than as properties. Added getSourceLevelFromCompilerPlugin() to check both <release> and <source> elements. 2. Pass JdkToolchainDiscoverer to compat layer: ToolchainManagerFactory was creating DefaultToolchainManager without the discoverer, so old plugins going through the compat layer could detect incompatibility but had no discoverer to find alternative JDKs. 3. Scan JAVA_HOME parent directory for sibling JDKs: in CI and container environments, multiple JDKs are often installed as siblings (e.g. /toolchain/jdk-8, /toolchain/jdk-11, /toolchain/jdk-21). Added parent directory scanning from each JAVA*_HOME env var. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

The gh-11055 DI service injection IT calls new DefaultToolchainManager(Map.of()) from outside the package, so the single-arg Map constructor must be public. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…nd IT harness The gh-11055 DI service injection IT calls new DefaultToolchainManager(Map.of()) from outside the package, and the compat layer ToolchainManagerFactory calls the 3-arg constructor (factories, discoverer, logger). All constructors must be accessible from outside the package. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

gnodet and others added 2 commits July 30, 2026 16:31

elharo added the enhancement New feature or request label Jul 30, 2026

elharo reviewed Jul 30, 2026

View reviewed changes

gnodet and others added 6 commits July 31, 2026 07:44

Remove public modifiers from IT class and methods

8ec56c4

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Fix DefaultToolchainManager(Map) constructor visibility for IT harness

617ee27

The gh-11055 DI service injection IT calls new DefaultToolchainManager(Map.of()) from outside the package, so the single-arg Map constructor must be public. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Auto-select JDK toolchain when running JDK cannot compile source level - #12633

Auto-select JDK toolchain when running JDK cannot compile source level#12633
gnodet wants to merge 8 commits into
masterfrom
implement-automatic-jdk-toolchain-selection-when-t

gnodet commented Jul 30, 2026 •

edited

Loading

Uh oh!

elharo left a comment

Uh oh!

gnodet commented Jul 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

gnodet commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

How it works

Lazy filesystem discovery (JdkToolchainDiscoverer)

Source level compatibility (JdkSourceLevelSupport)

Compat layer

New files

Test plan

Uh oh!

elharo left a comment

Choose a reason for hiding this comment

Uh oh!

gnodet commented Jul 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

gnodet commented Jul 30, 2026 •

edited

Loading

Lazy filesystem discovery (`JdkToolchainDiscoverer`)

Source level compatibility (`JdkSourceLevelSupport`)