You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by zh...@apache.org on 2023/05/17 14:57:40 UTC
[camel] branch camel-3.18.x updated: CAMEL-16929: Document the DSLs
This is an automated email from the ASF dual-hosted git repository.
zhfeng pushed a commit to branch camel-3.18.x
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/camel-3.18.x by this push:
new 803d64807f0 CAMEL-16929: Document the DSLs
803d64807f0 is described below
commit 803d64807f0a84fb8f2e1ecec8b24c8898b67e6c
Author: Claus Ibsen <cl...@gmail.com>
AuthorDate: Sat Sep 3 11:52:42 2022 +0200
CAMEL-16929: Document the DSLs
---
.../src/main/docs/java-joor-dsl.adoc | 46 +++++++++++
dsl/camel-js-dsl/src/main/docs/js-dsl.adoc | 44 +++++++++++
dsl/camel-jsh-dsl/src/main/docs/jsh-dsl.adoc | 39 ++++++++++
dsl/camel-kotlin-dsl/src/main/docs/kotlin-dsl.adoc | 88 ++++++++++++++++++++++
.../src/main/docs/java-xml-io-dsl.adoc | 49 ++++++++++++
.../src/main/docs/java-xml-jaxb-dsl.adoc | 14 ++++
6 files changed, 280 insertions(+)
diff --git a/dsl/camel-java-joor-dsl/src/main/docs/java-joor-dsl.adoc b/dsl/camel-java-joor-dsl/src/main/docs/java-joor-dsl.adoc
index 1eb6b937ebd..802946de97f 100644
--- a/dsl/camel-java-joor-dsl/src/main/docs/java-joor-dsl.adoc
+++ b/dsl/camel-java-joor-dsl/src/main/docs/java-joor-dsl.adoc
@@ -10,4 +10,50 @@
*Since Camel {since}*
+The `java-joor-dsl` is used for runtime compiling Java routes in an existing running Camel integration.
+This was invented for Camel K and later ported to Apache Camel.
+
+This means that Camel will load the `.java` source during startup and compile this to Java byte code as `.class`,
+which then are loaded via class loader and behaves as regular Java compiled routes.
+
+== Example
+
+The following `MyRoute.java` source file:
+
+.MyRoute.java
+[source,java]
+----
+import org.apache.camel.builder.RouteBuilder;
+
+public class MyRoute extends RouteBuilder {
+
+ @Override
+ public void configure() throws Exception {
+ from("timer:tick")
+ .setBody()
+ .constant("Hello Camel K!")
+ .to("log:info");
+ }
+}
+----
+
+Can then be loaded and run with Camel CLI or Camel K.
+
+.Running with Camel K
+
+[source,bash]
+----
+kamel run MyRoute.java
+----
+
+.Running with Camel CLI
+
+[source,bash]
+----
+camel run MyRoute.java
+----
+
+
+== See Also
+
See xref:manual:ROOT:dsl.adoc[DSL]
diff --git a/dsl/camel-js-dsl/src/main/docs/js-dsl.adoc b/dsl/camel-js-dsl/src/main/docs/js-dsl.adoc
index 4a4846f3457..4c6150ac5a2 100644
--- a/dsl/camel-js-dsl/src/main/docs/js-dsl.adoc
+++ b/dsl/camel-js-dsl/src/main/docs/js-dsl.adoc
@@ -10,4 +10,48 @@
*Since Camel {since}*
+IMPORTANT: This DSL is experimental support level and is not recommended being used for production
+
+The `js-dsl` is used for runtime compiling JavaScript routes in an existing running Camel integration.
+This was invented for Camel K and later ported to Apache Camel.
+
+This means that Camel will load the `.js` source during startup and via the JavaScript compiler transform
+this into Camel routes.
+
+
+== Example
+
+The following `hello.js` source file:
+
+.hello.js
+[source,javascript]
+----
+function proc(e) {
+ e.getIn().setBody('Hello Camel K!')
+}
+
+from('timer:tick')
+ .process(proc)
+ .to('log:info')
+----
+
+Can then be loaded and run with Camel CLI or Camel K.
+
+.Running with Camel K
+
+[source,bash]
+----
+kamel run hello.js
+----
+
+.Running with Camel CLI
+
+[source,bash]
+----
+camel run hello.js
+----
+
+
+== See Also
+
See xref:manual:ROOT:dsl.adoc[DSL]
diff --git a/dsl/camel-jsh-dsl/src/main/docs/jsh-dsl.adoc b/dsl/camel-jsh-dsl/src/main/docs/jsh-dsl.adoc
index 697e357796a..df56b839058 100644
--- a/dsl/camel-jsh-dsl/src/main/docs/jsh-dsl.adoc
+++ b/dsl/camel-jsh-dsl/src/main/docs/jsh-dsl.adoc
@@ -10,4 +10,43 @@
*Since Camel {since}*
+IMPORTANT: This DSL is experimental support level and is not recommended being used for production
+
+The `jsh-dsl` is used for runtime compiling JavaShell routes in an existing running Camel integration.
+This was invented for Camel K and later ported to Apache Camel.
+
+This means that Camel will load the `.jsh` source during startup and use the JavaShell compiler to transform
+this into Camel routes.
+
+== Example
+
+The following `example.js` source file:
+
+.example.jsh
+[source,java]
+----
+builder.from("timer:tick")
+ .setBody()
+ .constant("Hello Camel K!")
+ .to("log:info");
+----
+
+Can then be loaded and run with Camel CLI or Camel K.
+
+.Running with Camel K
+
+[source,bash]
+----
+kamel run example.jsh
+----
+
+.Running with Camel CLI
+
+[source,bash]
+----
+camel run example.jsh
+----
+
+== See Also
+
See xref:manual:ROOT:dsl.adoc[DSL]
diff --git a/dsl/camel-kotlin-dsl/src/main/docs/kotlin-dsl.adoc b/dsl/camel-kotlin-dsl/src/main/docs/kotlin-dsl.adoc
index 81eea70031f..0514eb97b78 100644
--- a/dsl/camel-kotlin-dsl/src/main/docs/kotlin-dsl.adoc
+++ b/dsl/camel-kotlin-dsl/src/main/docs/kotlin-dsl.adoc
@@ -10,4 +10,92 @@
*Since Camel {since}*
+IMPORTANT: This DSL is experimental support level and is not recommended being used for production
+
+The `java-kotlin-dsl` is used for runtime compiling Kotlin routes in an existing running Camel integration.
+This was invented for Camel K and later ported to Apache Camel.
+
+This means that Camel will load the `.kts` source during startup and let Kotlin compile this to Java byte code.
+
+== Example
+
+The following `hello.kts` source file:
+
+.hello.kts
+[source,kotlin]
+----
+from("timer:tick")
+ .process { e -> e.getIn().body = "Hello Camel K!" }
+ .to("log:info")
+----
+
+Can then be loaded and run with Camel CLI or Camel K.
+
+.Running with Camel K
+
+[source,bash]
+----
+kamel run hello.kts
+----
+
+.Running with Camel CLI
+
+[source,bash]
+----
+camel run hello.kts
+----
+
+== Rest Example
+
+REST endpoints can be configured using the top level _rest_ block:
+
+.my-rest.ktn
+[source,kotlin]
+----
+rest {
+ configuration {
+ host = "localhost"
+ port = "8080"
+ }
+
+ path("/hello") {
+ get("/get") {
+ produces("application/json")
+ to("direct:get")
+ }
+ }
+
+ path("/bye") {
+ post("/post") {
+ produces("application/json")
+ to("direct:post")
+ }
+ }
+}
+
+from("direct:get")
+ .process { e -> e.getIn().body = "{ 'message': 'Hello GET' }" }
+
+from("direct:post")
+ .process { e -> e.getIn().body = "{ 'message': 'Hello POST' }" }
+----
+
+Can then be loaded and run with Camel CLI or Camel K.
+
+.Running with Camel K
+
+[source,bash]
+----
+kamel run my-rest.kts
+----
+
+.Running with Camel CLI
+
+[source,bash]
+----
+camel run my-rest.kts
+----
+
+== See Also
+
See xref:manual:ROOT:dsl.adoc[DSL]
diff --git a/dsl/camel-xml-io-dsl/src/main/docs/java-xml-io-dsl.adoc b/dsl/camel-xml-io-dsl/src/main/docs/java-xml-io-dsl.adoc
index 8adfb596606..823923e973a 100644
--- a/dsl/camel-xml-io-dsl/src/main/docs/java-xml-io-dsl.adoc
+++ b/dsl/camel-xml-io-dsl/src/main/docs/java-xml-io-dsl.adoc
@@ -11,4 +11,53 @@
*Since Camel {since}*
+The `xml-io-dsl` is the Camel optimized XML DSL with a very fast and low overhead XML parser.
+The classic XML DSL was loaded via JAXB that is heavy and overhead.
+
+The JAXB parser is generic and can be used for parsing any XML.
+However, the `xml-io-dsl` is a source code generated parser that is Camel specific and can only parse Camel `.xml`
+route files (not classic Spring `<beans>` XML files).
+
+If you are using Camel XML DSL then its recommended using `xml-io-dsl` instead of `xml-jaxb-dsl`.
+You can use this in all of Camel's runtime such as Spring Boot, Quarkus, Camel Main, and Camel K etc.
+
+== Example
+
+The following `my-route.xml` source file:
+
+.my-route.xml
+[source,xml]
+----
+<routes xmlns="http://camel.apache.org/schema/spring">
+ <route>
+ <from uri="timer:tick"/>
+ <setBody>
+ <constant>Hello Camel K!</constant>
+ </setBody>
+ <to uri="log:info"/>
+ </route>
+</routes>
+----
+
+TIP: You can omit the `xmlns` namespace. And if there is only a single route, you can use `<route>` as the root XML tag.
+
+Can then be loaded and run with Camel CLI or Camel K.
+
+.Running with Camel K
+
+[source,bash]
+----
+kamel run my-route.xml
+----
+
+.Running with Camel CLI
+
+[source,bash]
+----
+camel run my-route.xml
+----
+
+
+== See Also
+
See xref:manual:ROOT:dsl.adoc[DSL]
diff --git a/dsl/camel-xml-jaxb-dsl/src/main/docs/java-xml-jaxb-dsl.adoc b/dsl/camel-xml-jaxb-dsl/src/main/docs/java-xml-jaxb-dsl.adoc
index 61098397acf..4b92dd18428 100644
--- a/dsl/camel-xml-jaxb-dsl/src/main/docs/java-xml-jaxb-dsl.adoc
+++ b/dsl/camel-xml-jaxb-dsl/src/main/docs/java-xml-jaxb-dsl.adoc
@@ -11,4 +11,18 @@
*Since Camel {since}*
+The `xml-jaxb-dsl` is the original Camel XML DSL that are loaded via JAXB that is heavy and with overhead.
+
+The JAXB parser is generic and can be used for parsing any XML.
+However, the `xml-io-dsl` is a source code generated parser that is Camel specific and can only parse Camel `.xml`
+route files (not classic Spring `<beans>` XML files).
+
+If you are using Camel XML DSL then its recommended using `xml-io-dsl` instead of `xml-jaxb-dsl`.
+You can use this in all of Camel's runtime such as Spring Boot, Quarkus, Camel Main, and Camel K etc.
+
+If you use classic Spring `<beans>` XML files, or OSGi `<blueprint>` then you must use the `camel-jaxb-dsl`,
+which comes out of the box when using `camel-spring-xml` or `camel-blueprint`.
+
+== See Also
+
See xref:manual:ROOT:dsl.adoc[DSL]