This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new aee44f97d4e8 CAMEL-16861: Update docs
aee44f97d4e8 is described below
commit aee44f97d4e86b2e882c76a113ad46f88662006c
Author: Claus Ibsen <[email protected]>
AuthorDate: Mon Feb 23 15:45:09 2026 +0100
CAMEL-16861: Update docs
---
.../modules/ROOT/pages/route-builder.adoc | 8 +-
.../modules/ROOT/pages/route-configuration.adoc | 79 +++++----
.../modules/ROOT/pages/route-controller.adoc | 181 +++++++++++++++++++--
3 files changed, 215 insertions(+), 53 deletions(-)
diff --git a/docs/user-manual/modules/ROOT/pages/route-builder.adoc
b/docs/user-manual/modules/ROOT/pages/route-builder.adoc
index dfafce02f213..5316030c25b0 100644
--- a/docs/user-manual/modules/ROOT/pages/route-builder.adoc
+++ b/docs/user-manual/modules/ROOT/pages/route-builder.adoc
@@ -1,14 +1,14 @@
= RouteBuilder
-The `RouteBuilder` is a base class which is derived from to create routing
rules using the DSL.
+The `RouteBuilder` is a base class which is derived from to create routing
rules using the Java DSL.
Instances of `RouteBuilder` are then added to the `CamelContext`.
== RouteBuilder example
-The following shows an example of a `RouteBuilder`:
+The following shows an example of a `RouteBuilder` in Java DSL:
[source,java]
--------------------------------------------------------------------------
+----
import org.apache.camel.builder.RouteBuilder;
/**
@@ -33,7 +33,7 @@ public class MyRouteBuilder extends RouteBuilder {
}
}
--------------------------------------------------------------------------
+----
In the `configure` method we can define Camel xref:routes.adoc[Routes].
diff --git a/docs/user-manual/modules/ROOT/pages/route-configuration.adoc
b/docs/user-manual/modules/ROOT/pages/route-configuration.adoc
index 69ef3b816ae4..64582998a63b 100644
--- a/docs/user-manual/modules/ROOT/pages/route-configuration.adoc
+++ b/docs/user-manual/modules/ROOT/pages/route-configuration.adoc
@@ -13,15 +13,15 @@ The route configuration is supported by all DSLs, so usable
by: Java, XML, Groov
In the route configuration, you can set up common strategies for:
- xref:error-handler.adoc[Error Handler]
-- xref:exception-clause.adoc[OnException]
-- xref:oncompletion.adoc[OnCompletion]
-- xref:components:eips:intercept.adoc[Intercept]
+- xref:exception-clause.adoc[OnException EIP]
+- xref:oncompletion.adoc[OnCompletion EIP]
+- xref:components:eips:intercept.adoc[Intercept EIP]
== Route Configuration Builder in Java DSL
With Java DSL you can use `RouteConfigurationBuilder` to specify the
configuration as shown below.
-The builder is similar to `RouteBuilder` so its use is familiar.
+The builder is similar to xref:route-builder.adoc[RouteBuilder] so its usage
is similar.
[source,java]
----
@@ -38,7 +38,7 @@ public class MyJavaErrorHandler extends
RouteConfigurationBuilder {
NOTE: The `RouteConfigurationBuilder` uses `configuration` as the method where
the configuration is coded.
This is on purpose, so as not to use the `configure` method which the regular
Java DSL `RouteBuilder`
-uses for coding Camel routes.
+uses for coding Camel routes in Java DSL.
In the example above, then there is only one route configuration that has been
assigned the ID `_javaError_`.
This ID allows us to refer to this configuration later when you want to assign
which routes are using the configuration.
@@ -120,15 +120,15 @@ context.addRoutes(new MyJavaRouteBuilder());
----
If you use Spring Boot, then your Camel routes and route configurations can be
auto-discovered
-by the spring boot component scanning. This requires adding the `@Component`
annotation to the class.
+by the Spring Boot package scanning. This requires adding the `@Component`
annotation to the class.
-See the example
https://github.com/apache/camel-spring-boot-examples/tree/main/routes-configuration[camel-spring-boot-examples/routes-configuration].
+See more in this Spring Boot example
https://github.com/apache/camel-spring-boot-examples/tree/main/routes-configuration[Routes
Configuration Example].
=== Route configuration with Endpoint DSL
The xref:Endpoint-dsl.adoc[Endpoint DSL] can also be used for route
configurations.
-This requires adding `camel-endpointdsl` to the classpath, and then using
+This requires adding `camel-endpointdsl` JAR to the classpath, and then using
`org.apache.camel.builder.endpoint.EndpointRouteConfigurationBuilder`,
which offers the _type safe_ DSL for Camel endpoints.
@@ -241,10 +241,10 @@ When using YAML DSL, then you can code your route
configurations in YAML files a
[source,yaml]
----
-- route-configuration:
+- routeConfiguration:
id: "yamlError"
- on-exception:
- - on-exception:
+ onException:
+ - onException:
handled:
constant: "true"
exception:
@@ -260,19 +260,19 @@ And in the YAML routes you can assign which
configurations to use:
----
- route:
# refer to the route configuration by the id to use for this route
- route-configuration-id: "yamlError"
+ routeConfigurationId: "yamlError"
from:
uri: "timer:yaml?period=3s"
steps:
- - set-body:
+ - setBody:
simple: "Timer fired ${header.CamelTimerCounter} times"
- to:
uri: "log:yaml"
parameters:
- show-body-type: false
- show-exchange-pattern: false
- - throw-exception:
- exception-type: "java.lang.IllegalArgumentException"
+ showBodyType: false
+ showExchangePattern: false
+ - throwException:
+ exceptionType: "java.lang.IllegalArgumentException"
message: "Error from yaml"
----
@@ -281,7 +281,7 @@ In this example, the route is assigned the `_yamlError_`
route configuration by
== Mixing DSLs
Routes and route configuration are not required to use the same language. For
example, you can code
-route configurations in Java, and then use XML DSL for the routes, and they
would work together.
+route configurations in Java, and then use YAML DSL for the routes, and they
would work together.
== Route Configuration in classic Spring XML
@@ -334,24 +334,25 @@ If you set `startup-summary-level=verbose` then Camel
will log for each route wh
This option can be configured via Java API and also in
`application.properties` for Camel on Spring Boot, Quarkus, and Camel
standalone via `camel-main`
+[tabs]
+====
+
+Java::
++
[source,java]
----
camelContext.setStartupSummaryLevel(StartupSummaryLevel.Verbose);
----
-And with Spring Boot:
-
-[source,properties]
-----
-camel.spring-boot.startup-summary-level = verbose
-----
-
-And in Camel Main / Quarkus:
-
+Application Properties::
++
+For example with Spring Boot, Quarkus or Camel Standalone
++
[source,properties]
----
camel.main.startup-summary-level = verbose
----
+====
== Route Precondition
@@ -359,6 +360,11 @@ The route configurations can be included or not according
to the result of a tes
In the next example, the route configuration is only included if the parameter
`activate` has been set to `true`.
+[tabs]
+====
+
+Java::
++
[source,java]
----
routeConfiguration().precondition("{{activate}}")
@@ -367,8 +373,8 @@ routeConfiguration().precondition("{{activate}}")
.log("WARN: ${exception.message}");
----
-And the same example using XML DSL:
-
+XML::
++
[source,xml]
----
<routeConfiguration precondition="{{activate}}">
@@ -382,14 +388,14 @@ And the same example using XML DSL:
</routeConfiguration>
----
-And in YAML DSL:
-
+YAML::
++
[source,yaml]
----
-- route-configuration:
+- routeConfiguration:
precondition: "{{activate}}"
- on-exception:
- - on-exception:
+ onException:
+ - onException:
exception:
- "java.lang.IllegalArgumentException"
handled:
@@ -398,11 +404,12 @@ And in YAML DSL:
- log:
message: "YAML WARN ${exception.message}"
----
+====
== More Information
See these examples:
--
https://github.com/apache/camel-examples/tree/main/routes-configuration[camel-examples/examples/routes-configuration]
--
https://github.com/apache/camel-spring-boot-examples/tree/main/routes-configuration[camel-spring-boot-examples/routes-configuration/]
+-
https://github.com/apache/camel-examples/tree/main/routes-configuration[Standalone
Routes Configuration Example]
+-
https://github.com/apache/camel-spring-boot-examples/tree/main/routes-configuration[Spring
Boot Routes Configuration Example]
diff --git a/docs/user-manual/modules/ROOT/pages/route-controller.adoc
b/docs/user-manual/modules/ROOT/pages/route-controller.adoc
index 1efe37ba3627..3db43a87dbce 100644
--- a/docs/user-manual/modules/ROOT/pages/route-controller.adoc
+++ b/docs/user-manual/modules/ROOT/pages/route-controller.adoc
@@ -30,15 +30,54 @@ that have failed to startup, by taking over and attempting
to restart these rout
Given the routes below:
+[tabs]
+====
+
+Java::
++
[source,java]
----
from("file:foo/cake")
- to("log:cake");
+ .to("log:cake");
from("salesforce:cheese")
- to("log:cheese");
+ .to("log:cheese");
+----
+
+XML::
++
+[source,xml]
+----
+<route>
+ <from uri="file:foo/cake"/>
+ <to uri="log:cake"/>
+</route>
+
+<route>
+ <from uri="salesforce:cheese"/>
+ <to uri="log:cheese"/>
+</route>
----
+YAML::
++
+[source,yaml]
+----
+- route:
+ from:
+ uri: file:foo/cake
+ steps:
+ - to:
+ uri: log:cake
+- route:
+ from:
+ uri: salesforce:cheese
+ steps:
+ - to:
+ uri: log:cheese
+----
+====
+
Then the two routes may fail on startup. However, the first route with the
file component
would very likely always start up as it is just using the file system that is
reliable.
@@ -54,15 +93,54 @@ settings for backoff between restarting routes.
If we take the same example again:
+[tabs]
+====
+
+Java::
++
[source,java]
----
from("file:foo/cake")
- to("log:cake");
+ .to("log:cake");
from("salesforce:cheese")
- to("log:cheese");
+ .to("log:cheese");
----
+XML::
++
+[source,xml]
+----
+<route>
+ <from uri="file:foo/cake"/>
+ <to uri="log:cake"/>
+</route>
+
+<route>
+ <from uri="salesforce:cheese"/>
+ <to uri="log:cheese"/>
+</route>
+----
+
+YAML::
++
+[source,yaml]
+----
+- route:
+ from:
+ uri: file:foo/cake
+ steps:
+ - to:
+ uri: log:cake
+- route:
+ from:
+ uri: salesforce:cheese
+ steps:
+ - to:
+ uri: log:cheese
+----
+====
+
Then we can tell Camel to use the supervising route controller to let Camel
attempt to
recover starting the salesforce route.
@@ -70,6 +148,11 @@ recover starting the salesforce route.
Enabling and configuring supervising route controller from Java:
+[tabs]
+====
+
+Java::
++
[source,java]
-----
CamelContext camel = ...
@@ -80,9 +163,10 @@ src.setInitialDelay(1000);
src.setThreadPoolSize(2);
-----
-If you use Camel with Spring Boot or Camel Main, you can also enable
supervising
-from `application.properties`:
-
+Application Properties::
++
+When using Spring Boot, Quarkus or Camel JBang
++
[source,properties]
----
camel.routecontroller.enabled = true
@@ -93,9 +177,12 @@ camel.routecontroller.backoffMaxAttempts = 3
camel.routecontroller.initialDelay = 1000
camel.routecontroller.threadPoolSize = 2
----
+====
+Spring XML::
++
And for users with Spring <beans> you can do as follows:
-
++
[source,xml]
----
<camelContext>
@@ -118,7 +205,7 @@ And for users with Spring <beans> you can do as follows:
You can configure the `SupervisingRouteController` using the following options:
[width="100%",cols="10%,20%,70%",options="header",]
-|=======================================================================
+|===
| Option | Default | Description
| Enabled | `false` | To enable using supervising route controller which
allows Camel to start up, and then, the controller takes care of starting the
routes in a safe manner. This can be used when you want to startup Camel
despite a route may otherwise fail fast during startup and cause Camel to fail
to startup as well. By delegating the route startup to the supervising route
controller then its manages the startup using a background thread. The
controller allows to be configured with v [...]
| InitialDelay | | Initial delay in milliseconds before the route controller
starts, after CamelContext has been started.
@@ -132,7 +219,7 @@ You can configure the `SupervisingRouteController` using
the following options:
| ThreadPoolSize | `1` | The number of threads used by the route controller
scheduled thread pool that are used for restarting routes. The pool uses 1
thread by default, but you can increase this to allow the controller to
concurrently attempt to restart multiple routes in case more than one route has
problems starting.
| UnhealthyOnExhausted | `true` | Whether to mark the route as unhealthy
(down) when all restarting attempts (backoff) have failed and the route is not
successfully started and the route manager is giving up. If setting this to
`false` will make health checks ignore this problem and allow to report the
Camel application as UP.
| UnhealthyOnRestarting | `true` | Whether to mark the route as unhealthy
(down) when the route failed to initially start, and is being controlled for
restarting (backoff). If setting this to false will make health checks ignore
this problem and allow reporting the Camel application as UP.
-|=======================================================================
+|===
IMPORTANT: The `UnhealthyOnExhausted` and `UnhealthyOnRestarting` options are
default `false` in Camel 4.6 or older.
@@ -148,27 +235,95 @@ This can be done by filtering the route from the
supervising with the include/ex
Given the routes below:
+[tabs]
+====
+
+Java::
++
[source,java]
----
from("file:foo/cake")
- to("log:cake");
+ .to("log:cake");
from("salesforce:cheese")
- to("log:cheese");
+ .to("log:cheese");
from("aws-s3:foo")
- .to("log:foo")
+ .to("log:foo");
+----
+XML::
++
+[source,xml]
+----
+<route>
+ <from uri="file:foo/cake"/>
+ <to uri="log:cake"/>
+</route>
+
+<route>
+ <from uri="salesforce:cheese"/>
+ <to uri="log:cheese"/>
+</route>
+
+<route>
+ <from uri="aws-s3:foo"/>
+ <to uri="log:foo"/>
+</route>
----
+YAML::
++
+[source,yaml]
+----
+- route:
+ from:
+ uri: file:foo/cake
+ steps:
+ - to:
+ uri: log:cake
+- route:
+ from:
+ uri: salesforce:cheese
+ steps:
+ - to:
+ uri: log:cheese
+- route:
+ from:
+ uri: aws-s3:foo
+ steps:
+ - to:
+ uri: log:foo
+----
+====
+
Then suppose we should fail fast if any AWS route fails to startup. This can
be done
by excluding by pattern `aws*` (uri or route id)
+[tabs]
+====
+
+Java::
++
[source,java]
+----
+CamelContext camel = ...
+SupervisingRouteController src = camel.getRouteController().supervise();
+src.setBackOffDelay(5000);
+src.setExcludeRoutes("aws*");
+----
+
+Application Properties::
++
+When using Spring Boot, Quarkus or Camel JBang
++
+[source,properties]
-----
camel.routecontroller.excludeRoutes = aws*
-----
+====
+
== JMX management
The route controllers are manageable in JMX, where you can find their MBean
under the `services` node.
