davsclaus commented on code in PR #28747:
URL: https://github.com/apache/camel/pull/28747#discussion_r4429462445
##########
docs/user-manual/modules/ROOT/pages/camel-jbang-java-api.adoc:
##########
@@ -0,0 +1,201 @@
+= Camel CLI - Java API for Export and Run
+
+*Since Camel 4.24 (preview)*
+
+`camel export` and `camel run` are built on a Java API, in the
`camel-jbang-run` module, which tools such as an IDE, a visual designer or an
AI agent can use directly, instead of starting the `camel` command and parsing
its output.
+The CLI itself uses this API, so a tool exports and runs an integration the
same way as `camel export` and `camel run` do.
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-jbang-run</artifactId>
+ <version>4.24.0</version>
Review Comment:
_Claude Code on behalf of davsclaus_
Thanks, done in 0543e6979555: `${camel-version}`, as the other pages of the
user manual write it in a Maven dependency.
##########
docs/user-manual/modules/ROOT/pages/camel-jbang-java-api.adoc:
##########
@@ -0,0 +1,201 @@
+= Camel CLI - Java API for Export and Run
+
+*Since Camel 4.24 (preview)*
+
+`camel export` and `camel run` are built on a Java API, in the
`camel-jbang-run` module, which tools such as an IDE, a visual designer or an
AI agent can use directly, instead of starting the `camel` command and parsing
its output.
+The CLI itself uses this API, so a tool exports and runs an integration the
same way as `camel export` and `camel run` do.
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-jbang-run</artifactId>
+ <version>4.24.0</version>
+</dependency>
+----
+
+The module does not need `camel-jbang-core` or picocli.
+
+NOTE: The API is a preview in Camel 4.24, and may still change in the next
releases.
+
+== The API at a glance
+
+A run is an export with a run on top, and the classes of the run extend those
of the export:
+
+[cols="1,1,3",options="header"]
+|===
+| Export | Run | What it is
+
+| `ExportRequest`
+| `RunRequest`
+| What to export or run: the options of `camel export` and `camel run`, as
public fields. `RunRequest` adds the options that only a run has (dev mode, the
source directory, stubs, tracing, the execution limits, ...).
+
+| `ExportContext`
+| `RunContext`
+| What the caller provides: where to print, how to ask for confirmation, the
plugins, and listeners such as what to report when the integration fails to
start.
+
+| `ProjectExporter`
+| `ProjectRunner`
+| Exports a project, or runs the integration.
+
+|
+| `RunningIntegration`
+| The handle of a running integration: its pid, wait for it to end, stop it.
+|===
+
+The classes of the export are in the `org.apache.camel.dsl.jbang.run.export`
package, and the classes of the run in `org.apache.camel.dsl.jbang.run`.
+
+== Exporting a project
+
+[source,java]
+----
+ExportRequest request = new ExportRequest();
+request.files.add("hello.camel.yaml");
+request.runtime = RuntimeType.main; // or springBoot, quarkus
+request.gav = "com.acme:hello:1.0-SNAPSHOT";
+request.exportDir = "target/hello";
+
+int exit = new ProjectExporter().export(request);
+----
+
+The export reads `application.properties` (and the one of the profile) of the
files, the same as `camel export`, and completes the request with what they
configure.
+The exit code is the one `camel export` exits with (see
xref:camel-jbang-exit-codes.adoc[Exit Codes and Output]).
+
+An `ExportContext` sets where the export prints, how it asks for confirmation
(for example before it cleans the export directory), the plugins, and what to
report when the integration fails to start:
+
+[source,java]
+----
+ExportContext context = new ExportContext()
+ .withPrinter(myPrinter)
+ .withConfirm(message -> askTheUser(message))
+ .withStartFailureListener((failure, files) -> showTheProblem(failure,
files));
+
+int exit = new ProjectExporter(context).export(request);
+----
+
+By default, the export prints to the console (`System.out` and `System.err`),
confirms everything, and has no plugins.
+`camel export` logs what `camel validate yaml` says about a YAML route that
did not load, with the start failure listener.
+
+To find the dependencies of the integration, the export boots it silently in
the same JVM, the same way as `camel run` does.
+This is done by the `SilentRunDependencyResolver` of the module, which `camel
export` uses as well; you can set your own `DependencyResolver` with
`ExportContext.withDependencyResolver`.
+
+== Running an integration
+
+[source,java]
+----
+RunRequest request = new RunRequest();
+request.files.add("hello.camel.yaml");
+request.runtime = RuntimeType.main; // or springBoot, quarkus, jbang
+request.port = 8080;
+
+RunningIntegration integration = new ProjectRunner().start(request);
+// ... later
+integration.stop();
+----
+
+`ProjectRunner.start` returns once the integration is started, and `run`
starts it and waits for it to end, as `camel run` does in the foreground:
+
+[source,java]
+----
+int exit = new ProjectRunner().run(request);
+----
+
+The `RunningIntegration` handle has:
+
+* `pid()`: the pid of the process of the integration (0 when the run ended
before it started, such as a build that failed).
+* `waitFor()`: waits for the integration to end, and returns its exit code, as
`camel run` exits with it.
+* `stop()`: stops the integration and the processes it started; with a Maven
runtime, it also removes the files of the run.
Review Comment:
_Claude Code on behalf of davsclaus_
Good catch: the page is right, the javadoc was not. With the jbang runtime,
`stop()` stops Camel, and the work directory of the run stays until the next
run prepares it again; only a run with Maven has files of its own (the Maven
project of the run), which `stop()` and the exit of the JVM remove. Fixed in
the javadoc of `RunningIntegration.stop()` in 0543e6979555.
##########
docs/user-manual/modules/ROOT/pages/camel-jbang-java-api.adoc:
##########
@@ -0,0 +1,201 @@
+= Camel CLI - Java API for Export and Run
+
+*Since Camel 4.24 (preview)*
+
+`camel export` and `camel run` are built on a Java API, in the
`camel-jbang-run` module, which tools such as an IDE, a visual designer or an
AI agent can use directly, instead of starting the `camel` command and parsing
its output.
+The CLI itself uses this API, so a tool exports and runs an integration the
same way as `camel export` and `camel run` do.
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-jbang-run</artifactId>
+ <version>4.24.0</version>
+</dependency>
+----
+
+The module does not need `camel-jbang-core` or picocli.
+
+NOTE: The API is a preview in Camel 4.24, and may still change in the next
releases.
+
+== The API at a glance
+
+A run is an export with a run on top, and the classes of the run extend those
of the export:
+
+[cols="1,1,3",options="header"]
+|===
+| Export | Run | What it is
+
+| `ExportRequest`
+| `RunRequest`
+| What to export or run: the options of `camel export` and `camel run`, as
public fields. `RunRequest` adds the options that only a run has (dev mode, the
source directory, stubs, tracing, the execution limits, ...).
+
+| `ExportContext`
+| `RunContext`
+| What the caller provides: where to print, how to ask for confirmation, the
plugins, and listeners such as what to report when the integration fails to
start.
+
+| `ProjectExporter`
+| `ProjectRunner`
+| Exports a project, or runs the integration.
+
+|
+| `RunningIntegration`
+| The handle of a running integration: its pid, wait for it to end, stop it.
+|===
+
+The classes of the export are in the `org.apache.camel.dsl.jbang.run.export`
package, and the classes of the run in `org.apache.camel.dsl.jbang.run`.
+
+== Exporting a project
+
+[source,java]
+----
+ExportRequest request = new ExportRequest();
+request.files.add("hello.camel.yaml");
+request.runtime = RuntimeType.main; // or springBoot, quarkus
+request.gav = "com.acme:hello:1.0-SNAPSHOT";
+request.exportDir = "target/hello";
+
+int exit = new ProjectExporter().export(request);
+----
+
+The export reads `application.properties` (and the one of the profile) of the
files, the same as `camel export`, and completes the request with what they
configure.
+The exit code is the one `camel export` exits with (see
xref:camel-jbang-exit-codes.adoc[Exit Codes and Output]).
+
+An `ExportContext` sets where the export prints, how it asks for confirmation
(for example before it cleans the export directory), the plugins, and what to
report when the integration fails to start:
+
+[source,java]
+----
+ExportContext context = new ExportContext()
+ .withPrinter(myPrinter)
+ .withConfirm(message -> askTheUser(message))
+ .withStartFailureListener((failure, files) -> showTheProblem(failure,
files));
+
+int exit = new ProjectExporter(context).export(request);
+----
+
+By default, the export prints to the console (`System.out` and `System.err`),
confirms everything, and has no plugins.
+`camel export` logs what `camel validate yaml` says about a YAML route that
did not load, with the start failure listener.
+
+To find the dependencies of the integration, the export boots it silently in
the same JVM, the same way as `camel run` does.
+This is done by the `SilentRunDependencyResolver` of the module, which `camel
export` uses as well; you can set your own `DependencyResolver` with
`ExportContext.withDependencyResolver`.
+
+== Running an integration
+
+[source,java]
+----
+RunRequest request = new RunRequest();
+request.files.add("hello.camel.yaml");
+request.runtime = RuntimeType.main; // or springBoot, quarkus, jbang
+request.port = 8080;
+
+RunningIntegration integration = new ProjectRunner().start(request);
+// ... later
+integration.stop();
+----
+
+`ProjectRunner.start` returns once the integration is started, and `run`
starts it and waits for it to end, as `camel run` does in the foreground:
+
+[source,java]
+----
+int exit = new ProjectRunner().run(request);
+----
+
+The `RunningIntegration` handle has:
+
+* `pid()`: the pid of the process of the integration (0 when the run ended
before it started, such as a build that failed).
+* `waitFor()`: waits for the integration to end, and returns its exit code, as
`camel run` exits with it.
+* `stop()`: stops the integration and the processes it started; with a Maven
runtime, it also removes the files of the run.
+
+=== How the integration runs
+
+The runtime of the request decides where the integration runs:
+
+* *Camel Main, Spring Boot, Quarkus* (`RuntimeType.main`, `springBoot`,
`quarkus`): the files are exported to a Maven project in a directory of the run
(under `.camel-jbang-run` in the current directory), built with Maven, and
started in a JVM of its own.
+With Spring Boot and Quarkus, the process of the handle is Maven
(`spring-boot:run`, or `quarkus:run`, and `quarkus:dev` in dev mode), which
runs the application; stopping it stops the application too.
+The output of Maven and of the application goes to the console of the JVM that
runs them (`ProcessBuilder.inheritIO`), unless you start the processes yourself
(see `RunContext.withProcessStarter` below).
+* *An existing Maven project*: a `pom.xml` as the file to run is run with
Maven as it is, with the runtime of the project.
+* *JBang* (`RuntimeType.jbang`, the default of a `RunRequest`): Camel runs in
the current JVM, the JVM of your tool.
+`waitFor()` runs Camel in the calling thread until it stops, so call it from a
thread of its own, and `stop()` from another one.
+
+TIP: To run an integration apart from the JVM of your tool, use a Maven
runtime, or start the `camel` command (`camel run --background`).
+Starting the jbang runtime in a JVM of its own is not part of the API yet.
+
+As with `camel run`, a directory as the file to run (`camel run .`) runs the
files of that directory, and the run reads `application.properties` (and the
one of the profile) and completes the request with what they configure, such as
the name of the integration and the files it found.
+
+The log of a run with the jbang runtime is kept as the previous log of the
integration when you set `RunRequest.logFile` and `RunRequest.keepPreviousLog`,
as `camel run` does on the command line.
Review Comment:
_Claude Code on behalf of davsclaus_
Thanks, done in 0543e6979555: the page says what the log of the previous run
is (`~/.camel/<name>-previous.log`, shown by `camel log <name> --previous`, for
example to see why an integration failed to start), links to the section about
it, and says what the two fields are.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
