CAMEL-23703: camel-launcher - shared Java 17+ runtime discovery for camel.sh and camel.bat

[ammachado]

Description

First slice of the larger CAMEL-23703 unified Camel CLI package distribution effort, split out for focused review. This branch is independent of the other CAMEL-23703 slices and targets main directly.

It gives the self-contained camel-launcher scripts (bin/camel.sh and bin/camel.bat) a single, shared Java 17+ runtime discovery contract. Candidates are evaluated in a fixed order and the first that exists, is executable, and reports a Java major version >= 17 wins:

1. JAVACMD (explicit override, unchanged)
2. $JAVA_HOME/bin/java (%JAVA_HOME%\bin\java.exe on Windows; also honors the SDKMAN java candidate)
3. The first java (java.exe) on PATH
4. CAMEL_FALLBACK_JAVA, a new variable set by package-manager installs when the JDK location is deterministic

Candidates older than 17, missing, non-executable, or with unparseable version output are skipped. If none qualify, the launcher exits nonzero with a diagnostic listing the sources it checked instead of running an unsuitable Java. The obsolete macOS JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/... default is removed from camel.sh; JAVA_OPTS handling is unchanged.

Included: the POSIX and Windows-batch discovery contracts, a shared FakeJava test harness, behavioral discovery tests for both scripts, and an upgrade-guide note.

Target

• I checked that the commit is targeting the correct branch (Camel 4 uses the main branch)

Tracking

• If this is a large change, bug fix, or code improvement, I checked there is a JIRA issue filed for the change (usually before you start working on it).

Apache Camel coding standards and style

• I checked that each commit in the pull request has a meaningful subject line and body.
• I have run mvn clean install -DskipTests locally from root folder and I have committed all auto-generated changes.

AI-assisted contributions

• If this PR includes AI-generated code, commits have proper co-authorship attribution (e.g., Co-authored-by trailers) and the PR description identifies the AI tool used.

---

Claude Code (Opus 4.8) on behalf of ammachado

[github-actions]

🌟 Thank you for your contribution to the Apache Camel project! 🌟
🤖 CI automation will test this PR automatically.

🐫 Apache Camel Committers, please review the following items:

• First-time contributors require MANUAL approval for the GitHub Actions to run
• You can use the command /component-test (camel-)component-name1 (camel-)component-name2.. to request a test from the test bot although they are normally detected and executed by CI.
• You can label PRs using skip-tests and test-dependents to fine-tune the checks executed by this PR.
• Build and test logs are available in the summary page. Only Apache Camel committers have access to the summary.

⚠️ Be careful when sharing logs. Review their contents before sharing them publicly.

[github-actions]

🧪 CI tested the following changed modules:

• docs
• dsl/camel-jbang/camel-launcher

---

🔬 Scalpel shadow comparison — Scalpel: 3 tested, 0 compile-only — current: 1 all tested

Maveniverse Scalpel detected 3 affected modules (current approach: 1).

⚠️ Modules only in Scalpel (2)

• camel-launcher
• docs

Skip-tests mode would test 3 modules (2 direct + 1 downstream), skip tests for 0 (generated code, meta-modules)

Modules Scalpel would test (3)

• camel-launcher
• camel-launcher-container
• docs

ℹ️ Shadow mode — Scalpel observes but does not affect test execution. Learn more

💡 Manual integration tests recommended:

You modified dsl/camel-jbang/camel-launcher. The related integration tests in dsl/camel-jbang/camel-jbang-it are excluded from CI. Consider running them manually:

mvn verify -f dsl/camel-jbang/camel-jbang-it -Djbang-it-test

All tested modules (3 modules)

• Camel :: Docs
• Camel :: Launcher
• Camel :: Launcher :: Container

---

⚙️ View full build and test results

[gnodet]

Thanks for this well-structured contribution, @ammachado. The unified Java 17+ discovery contract is a clear improvement over the ad-hoc logic in both scripts. I reviewed the shell scripts, batch files, test harness, and upgrade guide entry. CI is green.

Positive observations

• The 4-candidate precedence chain (JAVACMD, JAVA_HOME, PATH, CAMEL_FALLBACK_JAVA) is cleanly implemented in both camel.sh and camel.bat with consistent behavior.
• Good use of command -v java instead of which java -- the former is POSIX-standard while which is a GNU coreutils extension that may not be available on all systems.
• Stdin preservation via </dev/null during version probes prevents the probe from consuming input meant for the final Java process. This is a subtle but important detail.
• The old camel.bat had a bug where if ERRORLEVEL 1 goto error mapped all non-zero exit codes to 1. The new code correctly preserves the actual child exit code via set ERROR_CODE=%ERRORLEVEL%. Nice fix.
• The FakeJava test harness is well-designed: it handles both POSIX and Windows, prevents deadlocks with proper stream draining and timeouts, and supports stdin injection for verifying that probes don't steal input.
• Test coverage is comprehensive with good edge cases (early-access versions, Unicode paths, unparseable output, batch wrapper call vs. native invocation).

Findings

1. Removed platform-specific auto-detection not documented in upgrade guide [low]

The upgrade guide correctly documents the removal of the macOS JavaVM.framework default, but two other platform-specific behaviors were also removed without mention:

• IBM AIX: The old camel.sh probed $JAVA_HOME/jre/sh/java first (IBM's JDK on AIX uses non-standard paths). Users on AIX can still set JAVACMD explicitly, but the automatic detection is gone.
• Gentoo Linux: The old camel.sh detected /etc/gentoo-release and ran java-config --jre-home to set JAVA_HOME. Gentoo users who relied on this would need to set JAVA_HOME manually.

Both are likely very low-impact for the Camel CLI user base, and the JAVACMD override provides a workaround. Consider adding a brief mention to the upgrade guide entry for completeness, e.g.:

The Gentoo java-config auto-detection and the IBM AIX $JAVA_HOME/jre/sh/java probe were also removed; set JAVA_HOME or JAVACMD explicitly on those platforms.

2. No concerns found with the batch probe mechanism [info]

The camel.bat temp-file approach for capturing version output (camel-java-probe-%RANDOM%-%RANDOM%.tmp) is reasonable. The TOCTOU window between if exist and the actual write is negligible in practice for a CLI launcher. The cleanup is handled correctly on both success and failure paths.

Scanner coverage

No static analysis tools were available for this PR (SonarCloud was skipped). This review does not replace specialized review tools such as CodeRabbit, Sourcery, or SonarCloud.

---

Claude Code review on behalf of @gnodet

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

[gnodet]

Consider adding a note about the other two removed platform-specific behaviors that are not mentioned here:

• Gentoo Linux: The java-config --jre-home auto-detection (triggered by /etc/gentoo-release) was removed. Gentoo users should set JAVA_HOME explicitly.
• IBM AIX: The $JAVA_HOME/jre/sh/java probe (IBM's non-standard JDK path) was removed. AIX users should set JAVACMD to point at their Java binary.

Both are very low-impact, but mentioning them makes the upgrade guide exhaustive for the rare users who might rely on these.

Claude Code review on behalf of @gnodet

[ammachado]

Good catch — added a sentence covering both removals:

The Gentoo java-config auto-detection and the IBM AIX $JAVA_HOME/jre/sh/java probe were also removed; set JAVA_HOME or JAVACMD explicitly on those platforms.

Both platforms are rare in the Camel CLI user base, but documenting them keeps the upgrade guide exhaustive for anyone who relied on the old auto-detection.

[davsclaus]

Review: CAMEL-23703 - camel-launcher shared Java 17+ runtime discovery

Well-structured PR with comprehensive testing across both POSIX and Windows platforms.

Highlights

• Thorough test coverage: CamelShDiscoveryTest (POSIX), CamelBatDiscoveryTest (Windows), FakeJavaTest, and a shared FakeJava test harness covering the full discovery order, version parsing (including legacy 1.x format), fallback chains, rejection of old/garbage/non-executable candidates, stdin isolation, exit code propagation, and edge cases (spaces/unicode in paths).
• Clean discovery contract: Clear candidate order (JAVACMD → JAVA_HOME → PATH → CAMEL_FALLBACK_JAVA), version validation with minimum Java 17, and clean fallback chain with diagnostic output on failure.
• Safe removals: The macOS JavaVM.framework default (invalid since macOS 10.15+), Gentoo java-config, and AIX jre/sh/java probes are all correctly removed — none would ever resolve to Java 17+. The darwin variable was only set but never read after the removed block.
• Breaking changes documented: The upgrade guide covers all platform-specific removals (including Gentoo and AIX, added in response to gnodet's review comment).
• AI attribution: Properly attributed in commit metadata and PR description.

No blocking issues found. CI is green.

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