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 c51db5b4cbf6 CAMEL-16861: Update docs
c51db5b4cbf6 is described below
commit c51db5b4cbf6628f5ef9dc132524258c8f155382
Author: Claus Ibsen <[email protected]>
AuthorDate: Fri Feb 20 17:23:53 2026 +0100
CAMEL-16861: Update docs
---
.../modules/ROOT/pages/getting-started.adoc | 15 ++-
.../modules/ROOT/pages/graceful-shutdown.adoc | 62 ++++++++---
.../modules/ROOT/pages/health-check.adoc | 117 ++++++++++++---------
.../modules/ROOT/pages/http-session-handling.adoc | 17 ++-
4 files changed, 139 insertions(+), 72 deletions(-)
diff --git a/docs/user-manual/modules/ROOT/pages/getting-started.adoc
b/docs/user-manual/modules/ROOT/pages/getting-started.adoc
index 6ad2080e3272..c34c6ce99282 100644
--- a/docs/user-manual/modules/ROOT/pages/getting-started.adoc
+++ b/docs/user-manual/modules/ROOT/pages/getting-started.adoc
@@ -13,7 +13,6 @@ And some more alternative methods:
- Using Maven Archetypes
- Cloning an existing example to modify
-
== Using online Project generators
You can use https://start.spring.io/[Spring Boot Initializer] which is the
Spring Boot
@@ -36,7 +35,7 @@ Once JBang is installed, you should be able to make sure it
works by calling the
[source,bash]
----
$ jbang version
-0.132.1
+0.137.0
----
After this then install Camel into JBang as follows:
@@ -51,8 +50,8 @@ Then you can check that Camel is installed and working by
executing:
[source,bash]
----
$ camel version
-JBang version: 0.132.1
-Camel JBang version: 4.16.0
+JBang version: 0.137.0
+Camel JBang version: 4.18.0
----
*Step 2*
@@ -96,6 +95,7 @@ Make sure to check out the xref:camel-jbang.adoc[Camel JBang]
documentation, for
of the Camel CLI. You will also find information how you can _export_ what you
have built
with the Camel CLI into a vanilla Camel Spring Boot or Camel Quarkus project.
+
== Alternative ways of getting started with Camel
=== Adding Camel to an existing project
@@ -118,6 +118,8 @@ Among others the following are open source and provide
support for official Apac
- https://github.com/apache/camel-karavan[Apache Camel Karavan] - Has an
https://karavan.space/[online UI designer] that runs in a web browser.
- https://kaoto.io/[Kaoto] - Has also an
https://kaotoio.github.io/kaoto/[online UI designer] that runs in a web browser.
+Both Camel Karavan and Kaoto can be installed as Visual Studio plugins
directly in this IDE.
+
=== Using Maven Archetypes
Apache Camel comes with a set of xref:camel-maven-archetypes.adoc[Camel Maven
Archetypes],
@@ -128,3 +130,8 @@ you can use to create a new Camel project.
There are tons of Camel examples hosted on GitHub that you can clone and
modify,
such as https://github.com/apache/camel-spring-boot-examples[Camel Spring Boot
examples].
+== See Also
+
+To get familiar and learn the basic concepts of Apache Camel, then its
recommend to check out xref:architecture.adoc[Architecture]
+and follow the links from that page.
+
diff --git a/docs/user-manual/modules/ROOT/pages/graceful-shutdown.adoc
b/docs/user-manual/modules/ROOT/pages/graceful-shutdown.adoc
index fa1e13d247d8..6e71d6ae70e0 100644
--- a/docs/user-manual/modules/ROOT/pages/graceful-shutdown.adoc
+++ b/docs/user-manual/modules/ROOT/pages/graceful-shutdown.adoc
@@ -1,9 +1,9 @@
= Graceful Shutdown
Camel supports a pluggable shutdown strategy using
-`org.apache.camel.spi.ShutdownStrategy`. Its responsible for shutting
+`org.apache.camel.spi.ShutdownStrategy`. It's responsible for shutting
down routes in a graceful manner. The other resources will still be
-handled by xref:camelcontext.adoc[CamelContext] to shutdown. This leaves
+handled by xref:camelcontext.adoc[CamelContext] to shut down. This leaves
the problem at hand with properly shutting down all the routes reliably
to the `ShutdownStrategy`.
@@ -13,12 +13,11 @@ doing that.
== Default Shutdown Strategy
-The default strategy (`DefaultShutdownStrategy`) will gracefully shutdown
routes:
+The default strategy (`DefaultShutdownStrategy`) will gracefully shut down
routes:
* in the reverse order they were started
-* let pending and current in flight exchanges run to completion before
-shutting down
-* using a timeout of 45 seconds which then forces a _hard_ shutdown
+* let pending and current in flight exchanges run to completion before
shutting down
+* using a timeout of 45 seconds (can be configured) which then forces a _hard_
shutdown
The settings are configurable, so you can change the timeout, and
whether in case of timeout to force a _hard_ shutdown or ignore.
@@ -40,24 +39,40 @@ When shutting down the strategy will output to log the
progress:
---------------------------------
Notice how the strategy waits while there are inflight exchanges still being
-processed before it shutdown the routes and after that Camel itself.
+processed before it shut down the routes and after that Camel itself.
=== Suppressing logging due to timeout not allowing all inflight messages to
complete
If a graceful shutdown could not shutdown cleanly within the given
timeout period, then Camel performs a more aggressive shutdown (hard) by
forcing routes and thread pools etc to shut down, and the routing
-engine will reject continue processing xref:exchange.adoc[Exchange]s. If
-this happens you may see WARN logs about xref:exchange.adoc[Exchange]s
+engine will reject continue processing xref:exchange.adoc[Exchange](s). If
+this happens you may see WARN logs about xref:exchange.adoc[Exchange](s)
being rejected and other failures due the forced shutdown.
If you do not want to see these logs, you can suppress this by setting
-the option suppressLoggingOnTimeout to true.
+the option `suppressLoggingOnTimeout` to true.
+
+[tabs]
+====
+
+Java::
++
[source,java]
----------------------------------
+----
context.getShutdownStrategy().setSuppressLoggingOnTimeout(true);
----------------------------------
+----
+
+Application Properties::
++
+Or in `application.properties`:
++
+[source,properties]
+----
+camel.main.shutdownSuppressLoggingOnTimeout = true
+----
+====
Notice that suppression is _a best effort_ attempt and there may still be some
logging from 3rd party libraries, which Camel cannot control.
@@ -66,7 +81,7 @@ logging from 3rd party libraries, which Camel cannot control.
If a graceful shutdown could not shutdown cleanly within the given
timeout period, then Camel performs a more aggressive shutdown by
-forcing routes and thread pools etc to shut down. When the timeout
+forcing routes and thread pools etc. to shut down. When the timeout
happens, then Camel logs information about the current inflight
exchanges, which shows from which route the exchange origins, and where
it currently is being routed. For example the logging below, shows that
@@ -91,11 +106,26 @@ duration=2017]
If you do not want to see these logs, you can turn this off by setting
the option logInflightExchangesOnTimeout to false.
+[tabs]
+====
+
+Java::
++
[source,java]
---------------------------------
context.getShutdownStrategy().setLogInflightExchangesOnTimeout(false);
---------------------------------
+Application Properties::
++
+Or in `application.properties`:
++
+[source,properties]
+----
+camel.main.logInflightExchangesOnTimeout = false
+----
+====
+
=== JMX managed
The `ShutdownStrategy` is JMX aware, so you can manage it from a
@@ -161,7 +191,7 @@ It is possible to stop (will do a gracefully shut down) an
individual route usin
camelContext.getRouteController().stopRoute(routeId);
----
-Routes can also be stopped via JMX.
+TIP: Routes can also be stopped via JMX or external tools such as
https://hawt.io/[Hawtio].
=== Stopping and marking routes as failed due to an exception
@@ -180,7 +210,7 @@ NOTE: The Camel xref:health-check.adoc[Health Check] detect
the route as failed
If the route is manually stopped, then the route is not marked as failed,
and the xref:health-check.adoc[Health Check] will report the status as UNKNOWN.
-Routes can also be stopped and failed via JMX.
+TIP: Routes can also be stopped and failed via JMX or external tools such as
https://hawt.io/[Hawtio].
== Implementing custom component or ShutdownStrategy
@@ -196,7 +226,7 @@ on the `CamelContext` using the `setShutdownStrategy`
method.
=== ShutdownAware
The interface `org.apache.camel.spi.ShutdownAware` is an optional
-interface consumers can implement to have fine grained control during
+interface consumers can implement to have fine-grained control during
shutdown. The `ShutdownStrategy` must be able to deal with consumers
which implement this interface. This interface was introduced to cater
for in memory consumers such as xref:components::seda-component.adoc[SEDA]
which potentially
diff --git a/docs/user-manual/modules/ROOT/pages/health-check.adoc
b/docs/user-manual/modules/ROOT/pages/health-check.adoc
index c0c4c77d1973..f041a8ebfa88 100644
--- a/docs/user-manual/modules/ROOT/pages/health-check.adoc
+++ b/docs/user-manual/modules/ROOT/pages/health-check.adoc
@@ -44,7 +44,7 @@ is named foo, then the ID is `consumer:foo`.
Readiness and Liveness probes serve distinct purposes. Readiness indicates
whether the application is ready to serve requests or traffic.
Liveness probes indicates whether the application is alive and functioning. A
health check is by default usable for both readiness and liveness checks.
-To check wether a health check is usable for readiness or livesness:
+To check weather a health check is usable for readiness or liveness:
[source,java]
----
@@ -67,14 +67,18 @@ public boolean isReadiness() {
== Configuring health-check
-Camel supports via `camel-main` to configure health-checks from configuration
files. This is possible for runtimes that leverage `camel-main`
-such as Camel on Spring Boot, or Camel K.
+Camel supports to configure health checks from configuration files.
Camel will automatically enable `context`, `routes`, `consumers`, `producers`
and `registry` health-checks if `camel-health` is detected on the classpath.
They are all enabled by default (except for `producers` which is disabled).
However, you can configure them, for example to turn them off:
+[tabs]
+====
+
+Application Properties::
++
[source,properties]
----
# global option to turn health-check off (will not install health-check)
@@ -86,8 +90,9 @@ camel.health.routesEnabled=false
camel.health.consumersEnabled=false
camel.health.registryEnabled=false
----
+====
-The same can also be done programmatically using the Camel health api:
+The same can also be done programmatically in Java using the Camel health API:
[source,java]
----
@@ -102,22 +107,24 @@ if (consumersHealthCheckRepository != null) {
Once you have the health check exposed as a service and the application is up
and running, you can check it by accessing the related endpoint:
-[source, console]
+[source,bash]
----
$ curl http://localhost:9876/observe/health
{
- "status": "UP"
-,
+ "status": "UP",
"checks": [
{
"name": "context",
- "status": "UP" },
+ "status": "UP"
+ },
{
"name": "route:route1",
- "status": "UP" },
+ "status": "UP"
+ },
{
"name": "consumer:route1",
- "status": "UP" }
+ "status": "UP"
+ }
]
}
----
@@ -126,12 +133,11 @@ NOTE: the port and the path can change depending on the
runtime used and the con
When you're running on certain runtimes you will get more information by
default. This is also possible in the `camel-main` runtime provider. However,
you'll need to specify that as a request parameter:
-[source, console]
+[source,bash]
----
$ curl http://localhost:9876/observe/health?data=true
{
- "status": "UP"
-,
+ "status": "UP",
"checks": [
{
"name": "context",
@@ -155,83 +161,101 @@ $ curl http://localhost:9876/observe/health?data=true
...
----
-=== Configuring initial state
+=== Configuring Initial State
-The initial state of health-checks (readiness). There are the following
states: UP, DOWN, UNKNOWN.
+The initial state of health checks (readiness). There are the following
states: UP, DOWN, UNKNOWN.
By default, the state is DOWN, is regarded as being pessimistic/careful. This
means that the overall health
checks may report as DOWN during startup and then only if everything is up and
running flip to being UP.
Setting the initial state to UP, is regarded as being optimistic. This means
that the overall health checks may
-report as UP during startup and then if a consumer or other service is in fact
un-healthy, then the health-checks
+report as UP during startup and then if a consumer or other service is in fact
unhealthy, then the health checks
can flip being DOWN.
-Setting the state to UNKNOWN means that some health-check would be reported in
unknown state, especially during
+Setting the state to UNKNOWN means that some health check would be reported in
unknown state, especially during
early bootstrap where a consumer may not be fully initialized or validated a
connection to a remote system.
This option allows to pre-configure the state for different modes.
=== Excluding health-checks
-By default, all enabled health-checks are invoked by Camel when check the
health status.
+By default, all enabled health checks are invoked by Camel when check the
health status.
It is possible to specify checks that should be excluded, for example a
specific route by the route-id.
+[tabs]
+====
+
+Application Properties::
++
[source,properties]
----
camel.health.exclude-pattern = myroute
----
-
++
You can specify multiple patterns (and use wildcards) such as:
-
++
[source,properties]
----
camel.health.exclude-pattern = myroute,foo,bar*
----
+====
==== Routes that are not automatically started
If a route is configured to not to automatically start (`autoStartup=false`),
then the route and its corresponding consumer health checks is always up as it
is externally managed.
-=== Turning off consumer level health-checks
+=== Turning off consumer level Health Checks
-If routes health check is enabled then they will execute consumer
health-checks as well
+If routes health check is enabled then they will execute consumer health
checks as well
as part of an aggregated response.
The consumer checks can be turned off, to only use the route level checks
(status of the route)
+[tabs]
+====
+
+Application Properties::
++
[source,properties]
----
camel.health.consumersEnabled=false
----
-
++
You can also turn off individual consumers by prefixing the ID with
`consumer:` and the route id:
-
++
[source,properties]
----
camel.health.exclude-pattern = consumer:myroute*
----
+====
which will turn off checks for all consumers on routes that starts with
`myroute` in the route ID.
Or you can turn off producer based health checks by their component name:
+[tabs]
+====
+
+Application Properties::
++
[source,properties]
----
camel.health.exclude-pattern = producer:kafka*
----
-
++
Or all AWS producer health-checks
-
++
[source,properties]
----
camel.health.exclude-pattern = producer:aws*
----
+====
-=== Turning on producer level health-checks
+=== Turning on producer level Health Checks
-Only consumer based health-checks is enabled by default.
+Only consumer based health checks is enabled by default.
Some components (in particular AWS) provides also health checks for producers.
These health checks can be enabled via:
@@ -243,7 +267,7 @@ camel.health.producersEnabled=true
=== Turning off health checks from components
-Some Camel components comes with health-checks.
+Some Camel components comes with health checks.
For example to turn off both consumer and producer health checks from Kafka:
@@ -260,7 +284,7 @@ TIP: You can turn of either consumer, producer or both.
The health check is manageable via JMX (requires `camel-management` JAR on the
classpath).
You can find the `DefaultHealthCheck` MBean under the `health` node in the
Camel JMX tree.
-This MBean allows at runtime to manage health-checks where you can enable and
disable checks based on their IDs.
+This MBean allows at runtime to manage health checks where you can enable and
disable checks based on their IDs.
As well have the latest status whether the overall health check is healthy or
not.
The MBean also allows invoking health checks based on IDs (or all of them).
@@ -308,7 +332,7 @@ There are a limited number of health checks provided by
Camel out of the box,
so you may need to write your own check which you can do by implementing the
_HealthCheck_ interface
or by extending _AbstractHealthCheck_ which provides some useful methods.
-To make the health-check discoverable you should annotate the class with
`@HealthCheck` and
+To make the health check discoverable you should annotate the class with
`@HealthCheck` and
the _name_-check syntax.
[source,java]
@@ -352,36 +376,35 @@ Then the
xref:camel-component-maven-plugin.adoc[camel-component-maven-plugin] ca
used to automatic generated service loader file in
`META-INF/services/org/apache/camel/health-checks` that Camel uses
to discover the custom health checks.
-You must also enable loading custom health check by setting (Camel Main, Camel
K, or Camel Quarkus):
+You must also enable loading custom health check by setting:
+
+[tabs]
+====
+Application Properties::
++
[source,properties]
----
camel.main.load-health-checks = true
----
-And in Spring Boot:
-
-[source,properties]
+Java::
++
+[source,java]
----
-camel.springboot.load-health-checks = true
+CamelContext context = ...
+context.setLoadHealthChecks(true);
----
-And if you use the classic Spring XML, you can enable this on `<camelContext>`
as shown:
-
+Spring XML::
++
[source,xml]
----
<camelContext loadHealthChecks="true">
...
</camelContext>
----
-
-And of course you can also enable loading health checks from Java via
`CamelContext`:
-
-[source,java]
-----
-CamelContext context = ...
-context.setLoadHealthChecks(true);
-----
+====
TIP: The example `main-health` has a custom health check which is loadable.
@@ -398,7 +421,7 @@ or something else.
== Writing custom Health Check for Camel components
-You can implement custom health checks in Camel components (currently only for
consumers).
+You can implement custom health checks in Camel components .
To do this, you implement the interface `HealthCheckAware` on your consumer
class, which should
return the custom health check in the getter method.
diff --git a/docs/user-manual/modules/ROOT/pages/http-session-handling.adoc
b/docs/user-manual/modules/ROOT/pages/http-session-handling.adoc
index 716abc113fa7..595ae530b211 100644
--- a/docs/user-manual/modules/ROOT/pages/http-session-handling.adoc
+++ b/docs/user-manual/modules/ROOT/pages/http-session-handling.adoc
@@ -1,6 +1,7 @@
= HTTP Session Handling
Several Camel components can use HTTP as the underlying transport protocol.
+
In general HTTP calls are stateless in nature, however some servers allow
maintaining state via cookies. Cookies are often used to maintain a server
session (e.g. via a session cookie called "JSESSIONID" with servers
implementing
@@ -71,8 +72,13 @@ all invocations will share a session. For the third route
the first, and the sec
within the route share a session, but different (even parallel) invocations of
the route will
not share a session.
+[tabs]
+====
+
+Spring XML::
++
[source,xml]
------------------------------------------------------------
+----
<cxf:rsClient id="rsClientProxy"
address="http://127.0.0.1:8080/CxfRsProducerSessionTest/";
serviceClass="org.apache.camel.component.cxf.jaxrs.testbean.EchoService"
loggingFeatureEnabled="true" />
@@ -100,7 +106,8 @@ not share a session.
<bean id="instanceCookieHandler"
class="org.apache.camel.http.common.cookie.InstanceCookieHandler"/>
<bean id="exchangeCookieHandler"
class="org.apache.camel.http.common.cookie.ExchangeCookieHandler"/>
------------------------------------------------------------
+----
+====
Both `CookieHandler` implementations support setting a CookiePolicy to control
the policy for storing
cookies. Default is `CookiePolicy.ACCEPT_ORIGINAL_SERVER`.
@@ -120,8 +127,8 @@ As a workaround, you can call a
`cookieHandler.getCookieStore()` e.g. by setting
If you want to develop a HTTP based component that is supposed to participate
in a session
you have to add the following parts to your code:
-. Include a build reference to camel-http-common (if it is not already there)
-. Add a cookieHandler parameter to the endpoint class (together with getter
and setter)
+. Include a build reference to `camel-http-base` (if it is not already there)
+. Add a `cookieHandler` parameter to the endpoint class (together with getter
and setter)
. Before your code does the HTTP call, if a cookie handler is set on the
endpoint
perform a `cookieHandler.loadCookies(exchange, uri)` call. It will return a
`Map<String, List<String>>` containing the headers that need to be sent to the
server.
@@ -133,4 +140,4 @@ perform a `cookieHandler.storeCookies(exchange, uri, m)`
call. `m` is a
NOTE: Some APIs provide more direct support for cookie handling. In this case
it might be easier
to get the underlying `java.net.CookieStore` with a
`cookeManager.getCookieStore(exchange)` call
-and handle the cookies using the cookie interface provided by the underlying
library.
\ No newline at end of file
+and handle the cookies using the cookie interface provided by the underlying
library.
