You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by pp...@apache.org on 2021/04/14 11:29:31 UTC
[camel-quarkus] branch main updated: Revisit the documentation
#2136 #2470 #2374
This is an automated email from the ASF dual-hosted git repository.
ppalaga pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-quarkus.git
The following commit(s) were added to refs/heads/main by this push:
new bb64853 Revisit the documentation #2136 #2470 #2374
bb64853 is described below
commit bb648537b3311273a2275fec1bf896637a85eaf7
Author: Peter Palaga <pp...@redhat.com>
AuthorDate: Wed Apr 14 11:43:50 2021 +0200
Revisit the documentation #2136 #2470 #2374
---
docs/README.adoc | 5 +-
docs/modules/ROOT/nav.adoc | 5 +-
.../contributor-guide/create-new-extension.adoc | 2 +-
.../contributor-guide/promote-jvm-to-native.adoc | 2 +-
docs/modules/ROOT/pages/index.adoc | 2 +-
.../ROOT/pages/reference/extensions/core.adoc | 2 +-
docs/modules/ROOT/pages/user-guide/bootstrap.adoc | 176 ---------------------
docs/modules/ROOT/pages/user-guide/cdi.adoc | 23 +++
.../ROOT/pages/user-guide/command-mode.adoc | 30 ++++
.../ROOT/pages/user-guide/configuration.adoc | 137 ++++++++++++++++
.../pages/user-guide/defining-camel-routes.adoc | 141 +++++++++++++++++
.../pages/user-guide/dependency-management.adoc | 86 ++++++++++
.../modules/ROOT/pages/user-guide/first-steps.adoc | 32 +++-
docs/modules/ROOT/pages/user-guide/index.adoc | 2 +-
14 files changed, 458 insertions(+), 187 deletions(-)
diff --git a/docs/README.adoc b/docs/README.adoc
index 7d227a3..17148c4 100644
--- a/docs/README.adoc
+++ b/docs/README.adoc
@@ -20,9 +20,12 @@ To setup the environment you need to execute the following command once (and eve
[code,shell]
----
-yarn install
+yarn install --immutable
----
+`--immutable` makes the install command respect the content of `yarn.lock` file.
+You may want to omit it if you want upgrade the versions in `yarn.lock` file.
+
== Build the Documentation Website
To generate the documentation website, execute:
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index 246758a..7545d0c 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -1,9 +1,12 @@
* xref:user-guide/index.adoc[User guide]
** xref:user-guide/first-steps.adoc[First steps]
-** xref:user-guide/bootstrap.adoc[Bootstrap]
+** xref:user-guide/dependency-management.adoc[Dependency management]
+** xref:user-guide/defining-camel-routes.adoc[Defining routes]
+** xref:user-guide/configuration.adoc[Configuration]
** xref:user-guide/cdi.adoc[CDI]
** xref:user-guide/observability.adoc[Observability]
** xref:user-guide/native-mode.adoc[Native mode]
+** xref:user-guide/command-mode.adoc[Command mode]
** xref:user-guide/testing.adoc[Testing]
** xref:user-guide/examples.adoc[Examples]
* xref:contributor-guide/index.adoc[Contributor guide]
diff --git a/docs/modules/ROOT/pages/contributor-guide/create-new-extension.adoc b/docs/modules/ROOT/pages/contributor-guide/create-new-extension.adoc
index d6a4517..079c7d0 100644
--- a/docs/modules/ROOT/pages/contributor-guide/create-new-extension.adoc
+++ b/docs/modules/ROOT/pages/contributor-guide/create-new-extension.adoc
@@ -70,7 +70,7 @@ Check the xref:contributor-guide/extension-metadata.adoc[Extension metadata] pag
[TIP]
====
If your test application is going to be configured via `camel.component.*` properties, you need to add the
-`camel-quarkus-main` dependency to the test project. See the xref:user-guide/bootstrap.adoc[Bootstrap] section of
+`camel-quarkus-main` dependency to the test project. See the xref:user-guide/configuration.adoc[Bootstrap] section of
the User guide for more details.
====
diff --git a/docs/modules/ROOT/pages/contributor-guide/promote-jvm-to-native.adoc b/docs/modules/ROOT/pages/contributor-guide/promote-jvm-to-native.adoc
index 7be0198..a986317 100644
--- a/docs/modules/ROOT/pages/contributor-guide/promote-jvm-to-native.adoc
+++ b/docs/modules/ROOT/pages/contributor-guide/promote-jvm-to-native.adoc
@@ -49,7 +49,7 @@ $ mvn clean verify -Pnative
[TIP]
====
If your test application is going to be configured via `camel.component.*` properties, you need to add the
-`camel-quarkus-main` dependency to the test project. See the xref:user-guide/bootstrap.adoc[Bootstrap] section of
+`camel-quarkus-main` dependency to the test project. See the xref:user-guide/configuration.adoc[Bootstrap] section of
the User guide for more details.
====
+
diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
index 2a4c6e8..1eb89f7 100644
--- a/docs/modules/ROOT/pages/index.adoc
+++ b/docs/modules/ROOT/pages/index.adoc
@@ -11,7 +11,7 @@ Camel Quarkus provides xref:reference/index.adoc[Quarkus extensions] for many of
Camel Quarkus also takes advantage of the many performance improvements made in Camel 3, which results in a lower memory footprint, less reliance on reflection (which is good for native application support) and faster startup times.
-You can define Camel routes using the Java DSL, XML & Kotlin (see the xref:user-guide/examples.adoc[examples]).
+You can xref:user-guide/defining-camel-routes.adoc[define Camel routes] using the Java DSL, XML, Kotlin, Groovy, YAML or JavaScript.
=== Where to go next?
diff --git a/docs/modules/ROOT/pages/reference/extensions/core.adoc b/docs/modules/ROOT/pages/reference/extensions/core.adoc
index efb4632..6e3dc0f 100644
--- a/docs/modules/ROOT/pages/reference/extensions/core.adoc
+++ b/docs/modules/ROOT/pages/reference/extensions/core.adoc
@@ -174,7 +174,7 @@ What to do if it is not possible to extract CSimple expressions from a route def
|icon:lock[title=Fixed at build time] [[quarkus.camel.main.enabled]]`link:#quarkus.camel.main.enabled[quarkus.camel.main.enabled]`
-If `true` all `camel-main` features are enabled; otherwise no `camel-main` features are enabled. See described the xref:user-guide/bootstrap.adoc#_camel_main[Bootstrap] section of Camel Quarkus documentation for more details.
+If `true` all `camel-main` features are enabled; otherwise no `camel-main` features are enabled. See described the xref:user-guide/configuration.adoc#_camel_main[Bootstrap] section of Camel Quarkus documentation for more details.
| `boolean`
| `true`
diff --git a/docs/modules/ROOT/pages/user-guide/bootstrap.adoc b/docs/modules/ROOT/pages/user-guide/bootstrap.adoc
deleted file mode 100644
index f0e0740..0000000
--- a/docs/modules/ROOT/pages/user-guide/bootstrap.adoc
+++ /dev/null
@@ -1,176 +0,0 @@
-= Bootstrap and configuration
-
-Camel Quarkus automatically configures and deploys a Camel Context bean which by default is started/stopped according to
-the Quarkus Application lifecycle. The configuration step happens at build time during Quarkus' augmentation phase and
-it is driven by the Camel Quarkus extensions which can be tuned using Camel Quarkus specific `camel.quarkus.*`
-properties. After the configuration is done, a minimal Camel Runtime is assembled and started at
-https://quarkus.io/guides/writing-extensions#bootstrap-three-phases[RUNTIME_INIT] time.
-
-
-== CDI
-
-The https://quarkus.io/guides/cdi-reference[CDI] APIs can be used to configure various aspects of Camel behavior. For example, to configure the `LogComponent` you can write a code like:
-
-[source,java]
-----
-import javax.enterprise.context.ApplicationScoped;
-import javax.inject.Named;
-
-import org.apache.camel.component.log.LogComponent;
-import org.apache.camel.support.processor.DefaultExchangeFormatter;
-
-@ApplicationScoped
-public class Configurations {
- /**
- * Produces a {@link LogComponent} instance with a custom exchange formatter set-up.
- */
- @Named // <1>
- LogComponent log() {
- DefaultExchangeFormatter formatter = new DefaultExchangeFormatter();
- formatter.setShowExchangePattern(false);
- formatter.setShowBodyType(false);
-
- LogComponent component = new LogComponent();
- component.setExchangeFormatter(formatter);
-
- return component;
- }
-}
-----
-<1> Camel uses the component URI scheme to look-up components from its registry, this requires you to add the `@Named` annotation to the method, otherwise the CDI container would create an anonymous bean and Camel would not be able to look it up.
-
-In Camel Quarkus the Camel components are discovered during the augmentation phase, producing a new component as shown in the example above would invalidate any optimization that may have been made.
-
-As a better alternative you can use `@Inject` to obtain an instance of a component automatically created by Camel or you can observe one of the https://github.com/apache/camel-quarkus/tree/main/extensions-core/core/runtime/src/main/java/org/apache/camel/quarkus/core/events[events] fired by Camel Quarkus as shown in the following example, in which we use `@Observes` to be notified about components added to the Camel Context:
-
-[source,java]
-----
-import javax.enterprise.context.ApplicationScoped;
-import javax.enterprise.event.Observes;
-import org.apache.camel.quarkus.core.events.ComponentAddEvent;
-import org.apache.camel.component.log.LogComponent;
-
-@ApplicationScoped
-public static class EventHandler {
- public void onComponentAdd(@Observes ComponentAddEvent event) {
- if (event.getComponent() instanceof LogComponent) {
- // do something with the log component
- }
- }
-}
-----
-
-== Camel Main
-
-To configure components and other aspects of Apache Camel through properties, you can add the `camel-quarkus-main`
-extension which brings functionalities from xref:{cq-camel-components}:others:main.adoc[Apache Camel
-Main] to Camel Quarkus.
-
-In the example below, we apply the same configuration as the one from the Java example above by using properties:
-
-[source,properties]
-----
-camel.component.log.exchange-formtatter = #class:org.apache.camel.support.processor.DefaultExchangeFormatter
-camel.component.log.exchange-formtatter.show-exchange-pattern = false
-camel.component.log.exchange-formtatter.show-body-type = false
-----
-
-In addition to support configuring Camel through properties, `camel-quarkus-main` allows you to use conventions to configure the Camel behavior. For example, if there is a single `ExchangeFormatter` instance in the CDI container, then it will automatically wire that bean to the `LogComponent`.
-
-Camel Main also brings the option to write https://quarkus.io/guides/command-mode-reference[Quarkus Command Mode Applications] with control about when the Camel runtime should start:
-
-[source,java]
-----
-import io.quarkus.runtime.Quarkus;
-import io.quarkus.runtime.annotations.QuarkusMain;
-import org.apache.camel.quarkus.main.CamelMainApplication;
-
-@QuarkusMain
-public class Main {
- public static void main(String... args) {
- //
- // your logic here
- //
-
- Quarkus.run(CamelMainApplication.class, args); // <1>
- }
-}
-----
-<1> Start Quarkus and the Camel Quarkus runtime
-
-[NOTE]
-====
-It is recommended to perform very little logic in the Java Main.
-====
-
-Find more details about Camel Quarkus command line applications in this link:/blog/2020/07/command-line-utility-with-camel-quarkus/[blog post].
-
-=== XML Configuration
-
-In order to configure Camel routes, rests or templates in XML, you must add a Camel XML parser dependency to the classpath. E.g either `camel-quarkus-xml-io` or
-`camel-quarkus-xml-jaxb`. `camel-quarkus-xml-io` is preferred due to its lightweight implementation.
-
-With Camel Main, you can set a property that points to the location of resources XML files such as routes, xref:latest@manual::rest-dsl.adoc[REST DSL] and xref:latest@manual::route-template.adoc[Route templates]:
-
-[source,properties]
-----
-camel.main.routes-include-pattern = routes/routes.xml, file:src/main/routes/rests.xml, file:src/main/rests/route-template.xml
-----
-
-[NOTE]
-====
-Path globbing like `camel.main.routes-include-pattern = *./routes.xml` currently does not work in native mode.
-====
-
-
-.Route
-[source,xml]
-----
-<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xmlns="http://camel.apache.org/schema/spring"
- xsi:schemaLocation="
- http://camel.apache.org/schema/spring
- http://camel.apache.org/schema/spring/camel-spring.xsd">
-
- <route id="xml-route">
- <from uri="timer:from-xml?period=1000"/>
- <log message="Hello XML!"/>
- </route>
-
-</routes>
-----
-[NOTE]
-====
-Spring XML with `<beans>` or Blueprint XML with `<blueprint>` elements are not supported. The route XML should be in the simplified version like:
-====
-
-.Rest DSL
-[source,xml]
-----
-<rests xmlns="http://camel.apache.org/schema/spring">
- <rest id="greeting" path="/greeting">
- <get uri="/hello">
- <setBody>
- <constant>Hello World!</constant>
- </setBody>
- </get>
- </rest>
-</rests>
-----
-
-.Route Templates
-[source,xml]
-----
-<routeTemplates xmlns="http://camel.apache.org/schema/spring">
- <routeTemplate id="myTemplate">
- <templateParameter name="name"/>
- <templateParameter name="greeting"/>
- <templateParameter name="myPeriod" defaultValue="3s"/>
- <route>
- <from uri="timer:{{name}}?period={{myPeriod}}"/>
- <setBody><simple>{{greeting}} ${body}</simple></setBody>
- <log message="${body}"/>
- </route>
- </routeTemplate>
-</routeTemplates>
-----
diff --git a/docs/modules/ROOT/pages/user-guide/cdi.adoc b/docs/modules/ROOT/pages/user-guide/cdi.adoc
index 5393b2e..caf8ff7 100644
--- a/docs/modules/ROOT/pages/user-guide/cdi.adoc
+++ b/docs/modules/ROOT/pages/user-guide/cdi.adoc
@@ -41,6 +41,29 @@ you really need it.
TIP: Please refer to the https://quarkus.io/blog/quarkus-dependency-injection[Quarkus Dependency Injection guide] for more details.
+=== Accessing `CamelContext`
+
+To access `CamelContext` just inject it into your bean:
+
+[source,java]
+----
+import javax.inject.Inject;
+import javax.enterprise.context.ApplicationScoped;
+import java.util.stream.Collectors;
+import java.util.List;
+import org.apache.camel.CamelContext;
+
+@ApplicationScoped
+public static class MyBean {
+
+ @Inject
+ CamelContext context;
+
+ public List<String> listRouteIds() {
+ return context.getRoutes().stream().map(Route::getId).sorted().collect(Collectors.toList());
+ }
+}
+----
== CDI and the Camel Bean component
diff --git a/docs/modules/ROOT/pages/user-guide/command-mode.adoc b/docs/modules/ROOT/pages/user-guide/command-mode.adoc
new file mode 100644
index 0000000..481bffb
--- /dev/null
+++ b/docs/modules/ROOT/pages/user-guide/command-mode.adoc
@@ -0,0 +1,30 @@
+= Command Mode Applications
+
+`camel-quarkus-core` brings the option to write https://quarkus.io/guides/command-mode-reference[Quarkus Command Mode Applications] with control about when the Camel runtime should start:
+
+[source,java]
+----
+import io.quarkus.runtime.Quarkus;
+import io.quarkus.runtime.annotations.QuarkusMain;
+import org.apache.camel.quarkus.main.CamelMainApplication;
+
+@QuarkusMain
+public class Main {
+ public static void main(String... args) {
+ //
+ // your logic here
+ //
+
+ Quarkus.run(CamelMainApplication.class, args); // <1>
+ }
+}
+----
+<1> Start Quarkus and the Camel Quarkus runtime
+
+[NOTE]
+====
+It is recommended to perform very little logic in the Java Main.
+====
+
+Find more details about Camel Quarkus command line applications in this link:/blog/2020/07/command-line-utility-with-camel-quarkus/[blog post].
+
diff --git a/docs/modules/ROOT/pages/user-guide/configuration.adoc b/docs/modules/ROOT/pages/user-guide/configuration.adoc
new file mode 100644
index 0000000..cb51535
--- /dev/null
+++ b/docs/modules/ROOT/pages/user-guide/configuration.adoc
@@ -0,0 +1,137 @@
+= Configuration
+:page-aliases: user-guide/bootstrap.adoc
+
+Camel Quarkus automatically configures and deploys a Camel Context bean which by default is started/stopped according to
+the Quarkus Application lifecycle. The configuration step happens at build time during Quarkus' augmentation phase and
+it is driven by the Camel Quarkus extensions which can be tuned using Camel Quarkus specific `quarkus.camel.*`
+properties.
+
+[INFO]
+====
+`quarkus.camel.*` configuration properties are documented on the individual extension pages
+- see e.g. xref:reference/extensions/core.adoc[Camel Quarkus Core].
+====
+
+After the configuration is done, a minimal Camel Runtime is assembled and started in the
+https://quarkus.io/guides/writing-extensions#bootstrap-three-phases[RUNTIME_INIT] phase.
+
+
+== Configuring Camel components
+
+=== `application.properties`
+
+To configure components and other aspects of Apache Camel through properties,
+make sure that your application depends on `camel-quarkus-core` directly or transitively.
+Because most Camel Quarkus extensions depend on `camel-quarkus-core`, you typically do not need to add it explicitly.
+
+`camel-quarkus-core` brings functionalities from xref:{cq-camel-components}:others:main.adoc[Camel
+Main] to Camel Quarkus.
+
+In the example below, we set a specific `ExchangeFormatter` configuration on the `LogComponent` via
+`application.properties`:
+
+[source,properties]
+----
+camel.component.log.exchange-formatter = #class:org.apache.camel.support.processor.DefaultExchangeFormatter
+camel.component.log.exchange-formatter.show-exchange-pattern = false
+camel.component.log.exchange-formatter.show-body-type = false
+----
+
+
+=== CDI
+
+The same can be done programmatically using CDI:
+
+[source,java]
+----
+import javax.enterprise.context.ApplicationScoped;
+import javax.inject.Named;
+
+import org.apache.camel.component.log.LogComponent;
+import org.apache.camel.support.processor.DefaultExchangeFormatter;
+
+@ApplicationScoped
+public class Configurations {
+ /**
+ * Produces a {@link LogComponent} instance with a custom exchange formatter set-up.
+ */
+ @Named("log") // <1>
+ LogComponent log() {
+ DefaultExchangeFormatter formatter = new DefaultExchangeFormatter();
+ formatter.setShowExchangePattern(false);
+ formatter.setShowBodyType(false);
+
+ LogComponent component = new LogComponent();
+ component.setExchangeFormatter(formatter);
+
+ return component;
+ }
+}
+----
+<1> Camel uses the component URI scheme to look-up components from its registry, this requires you to add the `@Named` annotation to the method, otherwise the CDI container would create an anonymous bean and Camel would not be able to look it up.
+The `"log"` argument of the `@Named` annotation can be omitted as long as the name of the method is the same.
+
+In Camel Quarkus, the Camel components are discovered during the augmentation phase.
+Hence producing a new component as shown in the example above would invalidate any optimization that may have been made.
+
+As a better alternative you can use `@Inject` to obtain an instance of a component automatically created by Camel or you can observe one of the https://github.com/apache/camel-quarkus/tree/main/extensions-core/core/runtime/src/main/java/org/apache/camel/quarkus/core/events[events] fired by Camel Quarkus as shown in the following example, in which we use `@Observes` to be notified about components added to the Camel Context:
+
+[source,java]
+----
+import javax.enterprise.context.ApplicationScoped;
+import javax.enterprise.event.Observes;
+import org.apache.camel.quarkus.core.events.ComponentAddEvent;
+import org.apache.camel.component.log.LogComponent;
+
+@ApplicationScoped
+public static class EventHandler {
+ public void onComponentAdd(@Observes ComponentAddEvent event) {
+ if (event.getComponent() instanceof LogComponent) {
+ // do something with the log component
+ }
+ }
+}
+----
+
+== Camel Quarkus Core and Camel Main
+
+INFO: Before Camel Quarkus 1.8.0, `camel-quarkus-main` used to be a separate artifact.
+Since 1.8.0, all its functionality moved to `camel-quarkus-core`.
+
+== Configuration by convention
+
+In addition to support configuring Camel through properties, `camel-quarkus-core` allows you to use conventions to configure the Camel behavior.
+For example, if there is a single `ExchangeFormatter` instance in the CDI container, then it will automatically wire that bean to the `LogComponent`.
+
+
+`camel-quarkus-core` also brings the option to write https://quarkus.io/guides/command-mode-reference[Quarkus Command Mode Applications] with control about when the Camel runtime should start:
+
+[source,java]
+----
+import io.quarkus.runtime.Quarkus;
+import io.quarkus.runtime.annotations.QuarkusMain;
+import org.apache.camel.quarkus.main.CamelMainApplication;
+
+@QuarkusMain
+public class Main {
+ public static void main(String... args) {
+ //
+ // your logic here
+ //
+
+ Quarkus.run(CamelMainApplication.class, args); // <1>
+ }
+}
+----
+<1> Start Quarkus and the Camel Quarkus runtime
+
+[NOTE]
+====
+It is recommended to perform very little logic in the Java Main.
+====
+
+Find more details about Camel Quarkus command line applications in this link:/blog/2020/07/command-line-utility-with-camel-quarkus/[blog post].
+
+== What's next?
+
+We recommend to continue with xref:user-guide/cdi.adoc[CDI].
diff --git a/docs/modules/ROOT/pages/user-guide/defining-camel-routes.adoc b/docs/modules/ROOT/pages/user-guide/defining-camel-routes.adoc
new file mode 100644
index 0000000..6cc8743
--- /dev/null
+++ b/docs/modules/ROOT/pages/user-guide/defining-camel-routes.adoc
@@ -0,0 +1,141 @@
+= Defining Camel routes
+
+Camel Quarkus supports several domain specific languages (DSLs) to define Camel Routes.
+
+== Java DSL
+
+Extending `org.apache.camel.builder.RouteBuilder` and using the fluent builder methods available there
+is the most common way of defining Camel Routes.
+Here is an example from the https://github.com/apache/camel-quarkus-examples/tree/main/timer-log[timer-log] quicksstart:
+
+[source,java]
+----
+import org.apache.camel.builder.RouteBuilder;
+
+public class TimerRoute extends RouteBuilder {
+
+ @Override
+ public void configure() throws Exception {
+ from("timer:foo?period=1000")
+ .log("Hello World");
+ }
+}
+----
+
+=== Endpoint DSL
+
+Since Camel 3.0, you can use fluent builders also for defining Camel endpoints.
+The following is equivalent with the previous example:
+
+[source,java]
+----
+import org.apache.camel.builder.RouteBuilder;
+import static org.apache.camel.builder.endpoint.StaticEndpointBuilders.timer;
+
+public class TimerRoute extends RouteBuilder {
+
+ @Override
+ public void configure() throws Exception {
+ from(timer("foo").period(1000))
+ .log("Hello World");
+ }
+}
+----
+
+[NOTE]
+====
+Builder methods for all Camel components are available via `camel-quarkus-core`,
+but you still need to add the given component's extension as a dependency for the route to work properly.
+In case of the above example, it would be `camel-quarkus-timer`.
+====
+
+== XML DSL
+
+In order to configure Camel routes, rests or templates in XML, you must add a Camel XML parser dependency to the classpath.
+Since Camel Quarkus 1.8.0, `xref:reference/extensions/xml-io-dsl.adoc[camel-quarkus-xml-io-dsl]` is the best choice.
+
+With Camel Main, you can set a property that points to the location of resources XML files such as routes, xref:latest@manual::rest-dsl.adoc[REST DSL] and xref:latest@manual::route-template.adoc[Route templates]:
+
+[source,properties]
+----
+camel.main.routes-include-pattern = routes/routes.xml, file:src/main/routes/rests.xml, file:src/main/rests/route-template.xml
+----
+
+[NOTE]
+====
+Path globbing like `camel.main.routes-include-pattern = *./routes.xml` currently does not work in native mode.
+====
+
+
+.Route
+[source,xml]
+----
+<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns="http://camel.apache.org/schema/spring"
+ xsi:schemaLocation="
+ http://camel.apache.org/schema/spring
+ http://camel.apache.org/schema/spring/camel-spring.xsd">
+
+ <route id="xml-route">
+ <from uri="timer:from-xml?period=1000"/>
+ <log message="Hello XML!"/>
+ </route>
+
+</routes>
+----
+
+[WARN]
+====
+Spring XML with `<beans>` or Blueprint XML with `<blueprint>` elements are not supported.
+====
+
+The route XML should be in the simplified version like:
+
+.Rest DSL
+[source,xml]
+----
+<rests xmlns="http://camel.apache.org/schema/spring">
+ <rest id="greeting" path="/greeting">
+ <get uri="/hello">
+ <setBody>
+ <constant>Hello World!</constant>
+ </setBody>
+ </get>
+ </rest>
+</rests>
+----
+
+.Route Templates
+[source,xml]
+----
+<routeTemplates xmlns="http://camel.apache.org/schema/spring">
+ <routeTemplate id="myTemplate">
+ <templateParameter name="name"/>
+ <templateParameter name="greeting"/>
+ <templateParameter name="myPeriod" defaultValue="3s"/>
+ <route>
+ <from uri="timer:{{name}}?period={{myPeriod}}"/>
+ <setBody><simple>{{greeting}} ${body}</simple></setBody>
+ <log message="${body}"/>
+ </route>
+ </routeTemplate>
+</routeTemplates>
+----
+
+== Other route DSLs
+
+Since Camel Quarkus 1.8.0, you can also use
+xref:reference/extensions/java-joor-dsl.adoc[Java jOOR],
+xref:reference/extensions/groovy-dsl.adoc[Groovy],
+xref:reference/extensions/yaml-dsl.adoc[YAML],
+xref:reference/extensions/kotlin-dsl.adoc[Kotlin] or
+xref:reference/extensions/js-dsl.adoc[JavaScript] for defining Camel routes.
+
+These are mostly motivated by link:/camel-k/latest[Camel K] and its project-less approach to defining Camel routes.
+With Camel K, all you need to run an integration is a file where the routes are defined using one of the supported DSLs.
+With Camel Quarkus you still need a `pom.xml` file with the appropriate dependencies in addition to the route definition files.
+Except for YAML, these DSLs are supported only in JVM mode, because they load and compile the routes at runtime.
+
+== What's next?
+
+We recommend to continue with xref:user-guide/configuration.adoc[Configuration].
diff --git a/docs/modules/ROOT/pages/user-guide/dependency-management.adoc b/docs/modules/ROOT/pages/user-guide/dependency-management.adoc
new file mode 100644
index 0000000..c5bc0c5
--- /dev/null
+++ b/docs/modules/ROOT/pages/user-guide/dependency-management.adoc
@@ -0,0 +1,86 @@
+= Dependency management
+
+A specific Camel Quarkus release is supposed to work only with a specific Quarkus release.
+
+== Quarkus Universe BOM
+
+The easiest and most straightforward way to get the dependency versions right is to use https://code.quarkus.io/[code.quarkus.io].
+It will produce a project with the `io.quarkus:quarkus-universe-bom` set up in the `<depependencyManagement>` section
+of your `pom.xml` file.
+
+[INFO]
+====
+BOM stands for "Bill of Materials" - it is a `pom.xml` whose main purpose is to manage the versions of artifacts
+so that end users importing the BOM in their projects do not need to care which particular versions of the artifacts
+are supposed to work together. In other words, having a BOM imported in the `<depependencyManagement>` section
+of your `pom.xml` allows you to avoid specifying versions for the dependencies managed by the given BOM.
+====
+
+`quarkus-universe-bom` manages the artifacts from Quarkus, Camel Quarkus and other participating projects,
+such as Hazelcast, Cassandra, Kogito, Optaplanner, etc.
+
+This has the advantage that application developers do not need to care for the compatibility of the individual artifacts
+that may come from various independent projects.
+All artifacts managed by `quarkus-universe-bom` are supposed to work together flawlessly.
+
+Here is a stub of a `pom.xml` file generated by https://code.quarkus.io/[code.quarkus.io]:
+
+[source,xml,subs="attributes+"]
+----
+<project>
+ ...
+ <properties>
+ <quarkus.platform.version>{quarkus-version}</quarkus.platform.version>
+ ...
+ </properties>
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-universe-bom</artifactId>
+ <version>${quarkus.platform.version}</version>
+ <type>pom</type>
+ <scope>import</scope><!-- The BOM is imported in the <dependencyManagement> -->
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.camel.quarkus</groupId>
+ <artifactId>camel-quarkus-timer</artifactId>
+ <!-- No explicit version required here and below -->
+ </dependency>
+ <dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-resteasy</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-resteasy-jackson</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.camel.quarkus</groupId>
+ <artifactId>camel-quarkus-ftp</artifactId>
+ </dependency>
+ ...
+ </dependencies>
+ ...
+</project>
+----
+
+== Camel Quarkus BOM
+
+As long as you do not plan to use any dependencies beyond those from Quarkus and Camel Quarkus,
+you may consider switching to `org.apache.camel.quarkus:camel-quarkus-bom`.
+It manages all supported Camel artifacts and imports `io.quarkus:quarkus-bom`.
+
+== Combining with other BOMs
+
+When combining `camel-quarkus-bom` or `quarkus-universe-bom` with any other BOM,
+think carefully in which order you import them,
+because the order of imports defines the precedence.
+
+== What's next?
+
+We recommend to continue with xref:user-guide/defining-camel-routes.adoc[Defining routes].
diff --git a/docs/modules/ROOT/pages/user-guide/first-steps.adoc b/docs/modules/ROOT/pages/user-guide/first-steps.adoc
index 0e814f3..a56945a 100644
--- a/docs/modules/ROOT/pages/user-guide/first-steps.adoc
+++ b/docs/modules/ROOT/pages/user-guide/first-steps.adoc
@@ -1,7 +1,7 @@
= First steps
:page-aliases: first-steps.adoc
-This guide outlines various ways to create a Camel Quarkus project.
+This guide outlines various ways to create a new Camel Quarkus application.
== Prerequisites
@@ -17,9 +17,13 @@ This guide outlines various ways to create a Camel Quarkus project.
== code.quarkus.io
-Projects can be bootstrapped and generated at https://code.quarkus.io. All of the Camel Quarkus extensions can be found under the 'Integration' heading. Use the 'search' field to help with finding extensions that you are interested in.
+Projects can be generated at https://code.quarkus.io[code.quarkus.io].
+All of the Camel Quarkus extensions can be found under the 'Integration' heading.
+Use the 'search' field to help with finding extensions that you are interested in.
-Simply select the component extensions that you want to work with and click the 'Generate your application' button to download a basic skeleton project. There is also the option to push the project directly to GitHub.
+Simply select the component extensions that you want to work with
+and click the 'Generate your application' button to download a basic skeleton project.
+There is also the option to push the project directly to GitHub.
When the project archive download has completed successfully, unzip and import into your favorite IDE.
@@ -50,7 +54,17 @@ Quarkus has plugins for most of the popular development IDEs. They provide Quark
* https://plugins.jetbrains.com/plugin/13234-quarkus-tools[IntelliJ plugin]
* https://marketplace.visualstudio.com/items?itemName=redhat.vscode-quarkus[VSCode plugin]
-Check the plugin documentation to discover how to create projects for your preferred IDE.
+Check the documentation of the given plugin to discover how to create projects in your preferred IDE.
+
+=== Camel content assist
+
+The follwing plugins provide support for content assist when editing Camel routes and `application.properties`:
+
+* https://marketplace.visualstudio.com/items?itemName=redhat.vscode-apache-camel[VS Code Language support for Camel] - a part of the https://marketplace.visualstudio.com/items?itemName=redhat.apache-camel-extension-pack[Camel extension pack]
+* https://marketplace.eclipse.org/content/language-support-apache-camel[Eclipse Desktop Language Support for Camel] - a part of https://tools.jboss.org/[Jboss Tools] and https://developers.redhat.com/products/codeready-studio[CodeReady Studio]
+* https://plugins.jetbrains.com/plugin/9371-apache-camel-idea-plugin[Apache Camel IDEA plugin] (not always up to date)
+* Users of other https://microsoft.github.io/language-server-protocol/implementors/tools/[IDEs supporting Language Server Protocol]
+may choose to install and configure https://github.com/camel-tooling/camel-language-server[Camel Language Server] manually
== Example projects
@@ -101,6 +115,11 @@ The application has three compile dependencies:
They are managed within the `camel-quarkus-bom` that is imported in `<dependencyManagement>`.
+[INFO]
+====
+More about xref:user-guide/dependency-management.adoc[BOMs].
+====
+
There are only three classes in the application: `Routes` defines the Camel routes, whereas `Fruit` and `Legume` are entities.
The application is configured by properties defined within `src/main/resources/application.properties`. E.g. the `camel.context.name` is set there.
@@ -212,3 +231,8 @@ That's under 35 MB of RAM!
TIP: https://quarkus.io/guides/building-native-image-guide.html[Quarkus Native executable guide] contains more details
including
https://quarkus.io/guides/building-native-image-guide.html#creating-a-container[steps for creating a container image].
+
+== What's next?
+
+We recommend to continue with xref:user-guide/dependency-management.adoc[Dependency management].
+
diff --git a/docs/modules/ROOT/pages/user-guide/index.adoc b/docs/modules/ROOT/pages/user-guide/index.adoc
index 41fc441..cb080ee 100644
--- a/docs/modules/ROOT/pages/user-guide/index.adoc
+++ b/docs/modules/ROOT/pages/user-guide/index.adoc
@@ -4,7 +4,7 @@
This guide is for developers writing Camel applications on top of Quarkus.
-WARNING: Camel extensions for Quarkus is a new project and this guide is a work in progress.
+WARNING: Camel Quarkus is a new project and this guide is a work in progress.
https://github.com/apache/camel-quarkus/issues[Issue reports] and fixes are welcome.
== Which Camel components are supported on Quarkus?