[
https://issues.apache.org/jira/browse/CAMEL-24726?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Claus Ibsen updated CAMEL-24726:
--------------------------------
Description:
_Updated by Claude Code on behalf of davsclaus (Claus Ibsen): the plan below
replaces the original proposal (kept at the end), after stage 1 (CAMEL-24727)
made camel-jbang-export the picocli-free engine of camel run and camel export._
h2. Goal
camel-jbang-export is the engine that the CLI itself uses for run and export,
and a plain Java API for Kaoto, the TUI and other tools. The CLI is a thin
picocli layer on top of it: the engine configures no logging and reads no
system properties, and a difference between the CLI and the API is an explicit
input of the request, not a hidden branch.
A run is an export with a run on top: with Camel Main, Quarkus and Spring Boot,
camel run exports the project to a temporary directory, builds it with Maven
and starts it; with the jbang runtime, it boots the integration in the current
JVM with the same pipeline that the export uses to find the dependencies
({{RunPipeline}}).
h2. Design
The runner goes into camel-jbang-export, next to the exporter, and is built on
it:
* {{RunRequest extends ExportRequest}}: the options that a run shares with an
export are the fields of {{ExportRequest}}; {{RunRequest}} adds the ones that
only a run has (dev mode, the source and data directories, stubs, tracing, the
execution limits, JFR, ...).
* {{RunContext extends ExportContext}}: what the caller provides to a run, such
as how a process is started.
* {{ProjectRunner extends ProjectExporter}}:
** {{start(RunRequest)}} returns a handle to the running integration (pid, wait
for it to end, stop it);
** {{run(RunRequest)}} starts and waits, and returns the exit code, as camel
run does.
What stays in the CLI ({{Run}}): the picocli options mapped onto the request,
the logging configuration, the examples, {{--code}}, the clipboard, the
camel-launcher check of {{--camel-version}}, and the runs that start the camel
CLI again in a new JVM with the original command line: {{--background}},
{{--camel-version}} (also a custom Camel distribution) and {{camel debug}}.
Why not a separate camel-jbang-runner module: the in-JVM run ({{RunPipeline}},
{{RunRequest}}) must stay in camel-jbang-export, as the export uses it to find
the dependencies, so the run API would be split over two JARs; a runner module
adds no dependency of its own (only processes), every known consumer needs
both, and a module boundary would make more classes public (and part of the
compatibility promise of 4.24). No code outside Camel uses these classes, so
the runner can still move to a module of its own later.
h2. Pull requests
# 2a: {{RunRequest extends ExportRequest}}, one name per option
({{ExportRequest.exportBaseDir}} is {{baseDir}}, {{RunRequest.property}} is
{{applicationProperties}}) - https://github.com/apache/camel/pull/28739
# 2b: {{ProjectRunner}} and {{RunContext}}, with the Camel Main run (a new
project and an existing Maven project), the log of the run kept as the previous
run, and {{start}} returning a handle.
# 2c: the Quarkus and Spring Boot runs.
# 2d: the run in the current JVM (jbang runtime): no routes found, the
previous-run log, JFR, the exit code; the detection of {{camel run .}} and of
the runtime of a {{pom.xml}}; the profile properties loaded once
({{RunProfileProperties}}, which {{Run}} duplicates today).
# 2e: docs ("Running from Java", next to "Exporting from Java").
Afterwards: the module camel-jbang-export is renamed to camel-jbang-run.
Later, when a tool needs it: an engine run in a new JVM (what {{--background}}
does for the CLI), for Kaoto, and also to run Hawtio (embedded or in a child
JVM), the TUI and others.
h2. What must keep working
* {{camel run}} with every runtime behaves as today; the golden tests
({{RunExportGoldenTest}}: the runs, the Maven runs and the exports) guard it,
with no change to their expected files.
* The exit codes of CAMEL-25388 / CAMEL-25397, the log of the previous run
(CAMEL-25784, CAMEL-25832), {{--background}} and {{--background-wait}},
{{--camel-version}}, {{--jvm-debug}}, dev mode (reload), and the runs of
{{camel transform}}, {{camel cmd send --local}} and the other commands that run
Camel in their JVM.
* No CLI option is added, removed or renamed.
----
h2. Original proposal (superseded)
h2. Motivation
{{Run.runCamelMain()}}, {{runQuarkus()}} and {{runSpringBoot()}} (~700 lines)
contain the logic for exporting a project to a temp dir, packaging it with
Maven, and launching the resulting JAR or dev server. This logic is reusable
but today is locked inside the CLI.
Extracting it is the first step toward letting the Camel TUI, Kaoto and
external tooling build and launch projects through a Java API without spawning
the {{camel}} binary.
h2. What changes
New module {{dsl/camel-jbang/camel-jbang-runner}} (package
{{org.apache.camel.dsl.jbang.runner}}).
Dependencies: {{camel-jbang-core}}, {{camel-util}}. No picocli, no jline, no
camel-kamelet-main.
New public API:
* {{LaunchOptions}} — plain POJO: jvmArgs, jvmDebugPort, profile, dev,
sourceDir, logFile,
durationMax*, jfr, quiet
* {{LaunchCommand}} — record(List<String> command, Path workingDir,
Map<String,String> env) with a {{start()}} convenience method
* {{ProjectRunner}} — interface with {{buildCommand(Path, LaunchOptions)}}
(runs mvnw package) and {{runCommand(Path, LaunchOptions)}} (runs java -jar /
quarkus:run / spring-boot:run); implementations: {{CamelMainProjectRunner}},
{{QuarkusProjectRunner}}, {{SpringBootProjectRunner}}
{{Run.runCamelMain()}}, {{runQuarkus()}} and {{runSpringBoot()}} in
{{camel-jbang-core}} each shrink to ~10 lines delegating to the matching
{{ProjectRunner}}. The exportRun / KameletMain / writeSettings machinery is
completely untouched.
Add the module to {{dsl/camel-jbang/pom.xml}} and {{bom/camel-bom}}.
h2. Compatibility
* No type moves. No import rewrites anywhere.
* No CLI option added, removed or renamed.
* {{camel run --runtime=main|quarkus|spring-boot}} behaviour is identical.
h2. Note
After this stage a consumer of {{camel-jbang-runner}} still gets picocli, jline
and camel-kamelet-main transitively through {{camel-jbang-core}}. The
picocli-free API is available after stage 2.
was:
h2. Motivation
{{Run.runCamelMain()}}, {{runQuarkus()}} and {{runSpringBoot()}} (~700 lines)
contain the logic for exporting a project to a temp dir, packaging it with
Maven, and launching the resulting JAR or dev server. This logic is reusable
but today is locked inside the CLI.
Extracting it is the first step toward letting the Camel TUI, Kaoto and
external tooling build and launch projects through a Java API without spawning
the {{camel}} binary.
h2. What changes
New module {{dsl/camel-jbang/camel-jbang-runner}} (package
{{org.apache.camel.dsl.jbang.runner}}).
Dependencies: {{camel-jbang-core}}, {{camel-util}}. No picocli, no jline, no
camel-kamelet-main.
New public API:
* {{LaunchOptions}} — plain POJO: jvmArgs, jvmDebugPort, profile, dev,
sourceDir, logFile,
durationMax*, jfr, quiet
* {{LaunchCommand}} — record(List<String> command, Path workingDir,
Map<String,String> env) with a {{start()}} convenience method
* {{ProjectRunner}} — interface with {{buildCommand(Path, LaunchOptions)}}
(runs mvnw package) and {{runCommand(Path, LaunchOptions)}} (runs java -jar /
quarkus:run / spring-boot:run); implementations: {{CamelMainProjectRunner}},
{{QuarkusProjectRunner}}, {{SpringBootProjectRunner}}
{{Run.runCamelMain()}}, {{runQuarkus()}} and {{runSpringBoot()}} in
{{camel-jbang-core}} each shrink to ~10 lines delegating to the matching
{{ProjectRunner}}. The exportRun / KameletMain / writeSettings machinery is
completely untouched.
Add the module to {{dsl/camel-jbang/pom.xml}} and {{bom/camel-bom}}.
h2. Compatibility
* No type moves. No import rewrites anywhere.
* No CLI option added, removed or renamed.
* {{camel run --runtime=main|quarkus|spring-boot}} behaviour is identical.
h2. Note
After this stage a consumer of {{camel-jbang-runner}} still gets picocli, jline
and camel-kamelet-main transitively through {{camel-jbang-core}}. The
picocli-free API is available after stage 2.
Summary: camel-jbang: stage 2 - the runner API in camel-jbang-export (a
run is an export with a run on top) (was: camel-jbang: stage 2 - extract
camel-jbang-runner module)
> camel-jbang: stage 2 - the runner API in camel-jbang-export (a run is an
> export with a run on top)
> --------------------------------------------------------------------------------------------------
>
> Key: CAMEL-24726
> URL: https://issues.apache.org/jira/browse/CAMEL-24726
> Project: Camel
> Issue Type: Sub-task
> Components: camel-jbang
> Reporter: Ricardo Martinez
> Assignee: Claus Ibsen
> Priority: Trivial
> Fix For: 4.24.0
>
>
> _Updated by Claude Code on behalf of davsclaus (Claus Ibsen): the plan below
> replaces the original proposal (kept at the end), after stage 1 (CAMEL-24727)
> made camel-jbang-export the picocli-free engine of camel run and camel
> export._
> h2. Goal
> camel-jbang-export is the engine that the CLI itself uses for run and export,
> and a plain Java API for Kaoto, the TUI and other tools. The CLI is a thin
> picocli layer on top of it: the engine configures no logging and reads no
> system properties, and a difference between the CLI and the API is an
> explicit input of the request, not a hidden branch.
> A run is an export with a run on top: with Camel Main, Quarkus and Spring
> Boot, camel run exports the project to a temporary directory, builds it with
> Maven and starts it; with the jbang runtime, it boots the integration in the
> current JVM with the same pipeline that the export uses to find the
> dependencies ({{RunPipeline}}).
> h2. Design
> The runner goes into camel-jbang-export, next to the exporter, and is built
> on it:
> * {{RunRequest extends ExportRequest}}: the options that a run shares with an
> export are the fields of {{ExportRequest}}; {{RunRequest}} adds the ones that
> only a run has (dev mode, the source and data directories, stubs, tracing,
> the execution limits, JFR, ...).
> * {{RunContext extends ExportContext}}: what the caller provides to a run,
> such as how a process is started.
> * {{ProjectRunner extends ProjectExporter}}:
> ** {{start(RunRequest)}} returns a handle to the running integration (pid,
> wait for it to end, stop it);
> ** {{run(RunRequest)}} starts and waits, and returns the exit code, as camel
> run does.
> What stays in the CLI ({{Run}}): the picocli options mapped onto the request,
> the logging configuration, the examples, {{--code}}, the clipboard, the
> camel-launcher check of {{--camel-version}}, and the runs that start the
> camel CLI again in a new JVM with the original command line:
> {{--background}}, {{--camel-version}} (also a custom Camel distribution) and
> {{camel debug}}.
> Why not a separate camel-jbang-runner module: the in-JVM run
> ({{RunPipeline}}, {{RunRequest}}) must stay in camel-jbang-export, as the
> export uses it to find the dependencies, so the run API would be split over
> two JARs; a runner module adds no dependency of its own (only processes),
> every known consumer needs both, and a module boundary would make more
> classes public (and part of the compatibility promise of 4.24). No code
> outside Camel uses these classes, so the runner can still move to a module of
> its own later.
> h2. Pull requests
> # 2a: {{RunRequest extends ExportRequest}}, one name per option
> ({{ExportRequest.exportBaseDir}} is {{baseDir}}, {{RunRequest.property}} is
> {{applicationProperties}}) - https://github.com/apache/camel/pull/28739
> # 2b: {{ProjectRunner}} and {{RunContext}}, with the Camel Main run (a new
> project and an existing Maven project), the log of the run kept as the
> previous run, and {{start}} returning a handle.
> # 2c: the Quarkus and Spring Boot runs.
> # 2d: the run in the current JVM (jbang runtime): no routes found, the
> previous-run log, JFR, the exit code; the detection of {{camel run .}} and of
> the runtime of a {{pom.xml}}; the profile properties loaded once
> ({{RunProfileProperties}}, which {{Run}} duplicates today).
> # 2e: docs ("Running from Java", next to "Exporting from Java").
> Afterwards: the module camel-jbang-export is renamed to camel-jbang-run.
> Later, when a tool needs it: an engine run in a new JVM (what
> {{--background}} does for the CLI), for Kaoto, and also to run Hawtio
> (embedded or in a child JVM), the TUI and others.
> h2. What must keep working
> * {{camel run}} with every runtime behaves as today; the golden tests
> ({{RunExportGoldenTest}}: the runs, the Maven runs and the exports) guard it,
> with no change to their expected files.
> * The exit codes of CAMEL-25388 / CAMEL-25397, the log of the previous run
> (CAMEL-25784, CAMEL-25832), {{--background}} and {{--background-wait}},
> {{--camel-version}}, {{--jvm-debug}}, dev mode (reload), and the runs of
> {{camel transform}}, {{camel cmd send --local}} and the other commands that
> run Camel in their JVM.
> * No CLI option is added, removed or renamed.
> ----
> h2. Original proposal (superseded)
> h2. Motivation
> {{Run.runCamelMain()}}, {{runQuarkus()}} and {{runSpringBoot()}} (~700 lines)
> contain the logic for exporting a project to a temp dir, packaging it with
> Maven, and launching the resulting JAR or dev server. This logic is reusable
> but today is locked inside the CLI.
> Extracting it is the first step toward letting the Camel TUI, Kaoto and
> external tooling build and launch projects through a Java API without
> spawning the {{camel}} binary.
> h2. What changes
> New module {{dsl/camel-jbang/camel-jbang-runner}} (package
> {{org.apache.camel.dsl.jbang.runner}}).
> Dependencies: {{camel-jbang-core}}, {{camel-util}}. No picocli, no jline, no
> camel-kamelet-main.
> New public API:
> * {{LaunchOptions}} — plain POJO: jvmArgs, jvmDebugPort, profile, dev,
> sourceDir, logFile,
> durationMax*, jfr, quiet
> * {{LaunchCommand}} — record(List<String> command, Path workingDir,
> Map<String,String> env) with a {{start()}} convenience method
> * {{ProjectRunner}} — interface with {{buildCommand(Path, LaunchOptions)}}
> (runs mvnw package) and {{runCommand(Path, LaunchOptions)}} (runs java -jar /
> quarkus:run / spring-boot:run); implementations: {{CamelMainProjectRunner}},
> {{QuarkusProjectRunner}}, {{SpringBootProjectRunner}}
> {{Run.runCamelMain()}}, {{runQuarkus()}} and {{runSpringBoot()}} in
> {{camel-jbang-core}} each shrink to ~10 lines delegating to the matching
> {{ProjectRunner}}. The exportRun / KameletMain / writeSettings machinery is
> completely untouched.
> Add the module to {{dsl/camel-jbang/pom.xml}} and {{bom/camel-bom}}.
> h2. Compatibility
> * No type moves. No import rewrites anywhere.
> * No CLI option added, removed or renamed.
> * {{camel run --runtime=main|quarkus|spring-boot}} behaviour is identical.
> h2. Note
> After this stage a consumer of {{camel-jbang-runner}} still gets picocli,
> jline and camel-kamelet-main transitively through {{camel-jbang-core}}. The
> picocli-free API is available after stage 2.
--
This message was sent by Atlassian Jira
(v10.3.26#10030026)
