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 f6924997c515 docs: user manual - stream caching is on by default, 
requestBody rethrows, onCompletion runs inline, and other corrections (#30074)
f6924997c515 is described below

commit f6924997c515bc989e773753dbc3fd6bf73d7343
Author: Federico Mariani <[email protected]>
AuthorDate: Sun Nov 15 23:04:58 2026 +0100

    docs: user manual - stream caching is on by default, requestBody rethrows, 
onCompletion runs inline, and other corrections (#30074)
    
    * docs: user manual - stream caching is on by default, requestBody reth…
    
    …rows, onCompletion runs inline, and other corrections
    
    - stream-caching: enabled by default, spooling needs spoolEnabled=true, and 
how
      to read the body twice in one processor (getBodyAndResetStreamCache).
    - bean-binding: no "must be void" rule for an Exchange parameter; unquoted
      text, quoted ${...} and name vs name() overload rules; XML/YAML tabs.
    - producertemplate: sendBody/requestBody throw CamelExecutionException.
    - oncompletion: runs synchronously unless 
parallelProcessing/executorService.
    - using-propertyplaceholder: {{key}} works on any XML attribute; the prop:
      namespace was removed in 3.1.
    - route policies: timeUnit (not routeStopTimeUnit), java.util.Date in XML,
      noAutoStartup, Quartz cron format, policies never create messages, and a
      ThrottlingExceptionRoutePolicy section.
    - advice-with/testing/mock: @UseAdviceWith only with @CamelSpringTest or
      @CamelSpringBootTest, testConfiguration().withUseAdviceWith(true), the
      org.apache.camel.component.mock.InterceptSendToMockEndpointStrategy class
      name, DataSet Test link and JUnit 6 link texts.
    
    * docs: escape placeholders in inline code and wrap the bean-binding YA…
    
    …ML example in a route
    
    - Write {{greeting}}, {{key}} and {{stop}} inside inline code as +...+ so
      asciidoctor does not read them as attribute references.
    - The YAML tab of the bean-binding example is a route, so the doc samples
      validator of camel-jbang-core accepts it.
    - Split two long sentences (bean-binding, onCompletion) and word the
      CamelExecutionException getters as "returns".
    
    
    Co-Authored-By: Claude <[email protected]>
---
 .../apache/camel/catalog/docs/mock-component.adoc  |  6 +-
 .../camel-mock/src/main/docs/mock-component.adoc   |  6 +-
 .../modules/ROOT/pages/advice-with.adoc            | 25 +++++-
 .../modules/ROOT/pages/bean-binding.adoc           | 41 +++++++++-
 .../ROOT/pages/cronscheduledroutepolicy.adoc       | 60 +++++++++-----
 .../modules/ROOT/pages/oncompletion.adoc           | 13 +--
 .../modules/ROOT/pages/producertemplate.adoc       | 30 ++++---
 .../modules/ROOT/pages/route-policy.adoc           | 92 +++++++++++++++++++++-
 .../ROOT/pages/simplescheduledroutepolicy.adoc     | 40 +++++++---
 .../modules/ROOT/pages/stream-caching.adoc         | 37 ++++++++-
 docs/user-manual/modules/ROOT/pages/testing.adoc   |  6 +-
 .../ROOT/pages/using-propertyplaceholder.adoc      | 61 ++------------
 12 files changed, 294 insertions(+), 123 deletions(-)

diff --git 
a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/mock-component.adoc
 
b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/mock-component.adoc
index 64bc62fa32d0..96715f4f3271 100644
--- 
a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/mock-component.adoc
+++ 
b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/mock-component.adoc
@@ -60,7 +60,7 @@ Expression.
 
 [NOTE]
 ====
-There is also the xref:others:test-junit5.adoc[Test endpoint], which is a
+There is also the xref:dataset-test-component.adoc[DataSet Test] endpoint, 
which is a
 Mock endpoint, but which uses a second endpoint to provide the list of
 expected message bodies and automatically sets up the Mock endpoint
 assertions. In other words, it's a Mock endpoint that automatically sets
@@ -436,7 +436,7 @@ 
include::{examplesdir}/components/camel-spring-parent/camel-spring-xml/src/test/
 
 Then we create a new XML file as follows, where we include the
 `camel-route.xml` file and define a spring bean with the class
-`org.apache.camel.impl.InterceptSendToMockEndpointStrategy` which tells
+`org.apache.camel.component.mock.InterceptSendToMockEndpointStrategy` which 
tells
 Camel to mock all endpoints:
 
 [source,xml]
@@ -453,7 +453,7 @@ in the constructor for the bean:
 
 [source,xml]
 ----
-<bean id="mockAllEndpoints" 
class="org.apache.camel.impl.InterceptSendToMockEndpointStrategy">
+<bean id="mockAllEndpoints" 
class="org.apache.camel.component.mock.InterceptSendToMockEndpointStrategy">
     <constructor-arg index="0" value="log*"/>
 </bean>
 ----
diff --git a/components/camel-mock/src/main/docs/mock-component.adoc 
b/components/camel-mock/src/main/docs/mock-component.adoc
index 64bc62fa32d0..96715f4f3271 100644
--- a/components/camel-mock/src/main/docs/mock-component.adoc
+++ b/components/camel-mock/src/main/docs/mock-component.adoc
@@ -60,7 +60,7 @@ Expression.
 
 [NOTE]
 ====
-There is also the xref:others:test-junit5.adoc[Test endpoint], which is a
+There is also the xref:dataset-test-component.adoc[DataSet Test] endpoint, 
which is a
 Mock endpoint, but which uses a second endpoint to provide the list of
 expected message bodies and automatically sets up the Mock endpoint
 assertions. In other words, it's a Mock endpoint that automatically sets
@@ -436,7 +436,7 @@ 
include::{examplesdir}/components/camel-spring-parent/camel-spring-xml/src/test/
 
 Then we create a new XML file as follows, where we include the
 `camel-route.xml` file and define a spring bean with the class
-`org.apache.camel.impl.InterceptSendToMockEndpointStrategy` which tells
+`org.apache.camel.component.mock.InterceptSendToMockEndpointStrategy` which 
tells
 Camel to mock all endpoints:
 
 [source,xml]
@@ -453,7 +453,7 @@ in the constructor for the bean:
 
 [source,xml]
 ----
-<bean id="mockAllEndpoints" 
class="org.apache.camel.impl.InterceptSendToMockEndpointStrategy">
+<bean id="mockAllEndpoints" 
class="org.apache.camel.component.mock.InterceptSendToMockEndpointStrategy">
     <constructor-arg index="0" value="log*"/>
 </bean>
 ----
diff --git a/docs/user-manual/modules/ROOT/pages/advice-with.adoc 
b/docs/user-manual/modules/ROOT/pages/advice-with.adoc
index bea3e3f3f3a4..37921b27091a 100644
--- a/docs/user-manual/modules/ROOT/pages/advice-with.adoc
+++ b/docs/user-manual/modules/ROOT/pages/advice-with.adoc
@@ -101,12 +101,25 @@ This is solved by following the following steps:
 2. Advice the routes in your unit test methods
 3. Start Camel after you have _adviced_ the routes
 
-When using xref:components:others:test-junit5.adoc[camel-test-junit5] for unit 
testing, then you can tell Camel that advice is in use by either
-overriding the `isUsedAdviceWith` method from `CamelTestSupport` as shown:
+When your test class extends `CamelTestSupport` from 
xref:components:others:test-junit5.adoc[camel-test-junit5],
+or `CamelSpringTestSupport` from 
xref:components:others:test-spring-junit5.adoc[camel-test-spring-junit5],
+you tell Camel that advice is in use with 
`testConfiguration().withUseAdviceWith(true)`, for example in the constructor:
 
 ._Java-only: enabling AdviceWith in CamelTestSupport_
 [source,java]
 ----
+public class MyAdviceWithTest extends CamelTestSupport {
+    public MyAdviceWithTest() {
+        testConfiguration().withUseAdviceWith(true); // turn on advice with
+    }
+}
+----
+
+Overriding the deprecated `isUseAdviceWith` method also works:
+
+._Java-only: enabling AdviceWith by overriding isUseAdviceWith_
+[source,java]
+----
 public class MyAdviceWithTest extends CamelTestSupport {
     @Override
     public boolean isUseAdviceWith() {
@@ -115,13 +128,17 @@ public class MyAdviceWithTest extends CamelTestSupport {
 }
 ----
 
-Or when using 
xref:components:others:test-spring-junit5.adoc[camel-test-spring-junit5] for 
unit testing you can use the `@UseAdviceWith` annotation as shown:
+When your test class uses the `@CamelSpringTest` or `@CamelSpringBootTest` 
annotation from
+xref:components:others:test-spring-junit5.adoc[camel-test-spring-junit5], you 
use the `@UseAdviceWith` annotation instead.
+A test class that extends `CamelSpringTestSupport` ignores this annotation.
 
 ._Java-only: enabling AdviceWith using @UseAdviceWith annotation_
 [source,java]
 ----
+@CamelSpringTest
+@ContextConfiguration
 @UseAdviceWith
-public class MyAdviceWithTest extends CamelSpringTestSupport {
+public class MyAdviceWithTest {
 }
 ----
 
diff --git a/docs/user-manual/modules/ROOT/pages/bean-binding.adoc 
b/docs/user-manual/modules/ROOT/pages/bean-binding.adoc
index 783985a33673..239256027f83 100644
--- a/docs/user-manual/modules/ROOT/pages/bean-binding.adoc
+++ b/docs/user-manual/modules/ROOT/pages/bean-binding.adoc
@@ -178,9 +178,7 @@ public class Bar {
 }
 ----
 
-Or the Exchange example. Notice that the return type must be *void* when
-there is only a single parameter of the type
-`org.apache.camel.Exchange`:
+Or the Exchange example:
 
 ._Java-only: bean class with Exchange parameter_
 [source,java]
@@ -231,6 +229,18 @@ xref:components:languages:simple-language.adoc[Simple] 
tokens. Notice the tokens
 * The value ends with `.class` then it's a type declaration instead - see the
 next section about specifying types for overloaded methods.
 
+Any other value is also evaluated with the 
xref:components:languages:simple-language.adoc[Simple] language,
+so a word without quotes is passed as that text: `echo(World)` passes the 
String `World`.
+It is not a Java variable. To pass a value known when you build the route, 
concatenate it into the method option,
+or use a property placeholder such as `+echo({{greeting}})+`.
+
+Do not put quotes around a Simple expression when the parameter is not a 
String.
+For example, `+'${header.order}'+` passes the header as text, and the call 
fails when that text cannot be converted
+to the parameter type. Write `+${header.order}+` to pass the header object 
itself.
+
+When a method is overloaded, such as `refresh()` and `refresh(Writer)`, the 
name alone (`refresh`) selects the overload
+with a parameter and binds the message body to it. Write `refresh()` to call 
the overload without parameters.
+
 When invoking a xref:components:eips:bean-eip.adoc[Bean] you can instruct 
Camel to invoke a
 specific method by providing the method name:
 
@@ -267,12 +277,35 @@ Camel figure this out. The second parameter has a fixed 
value of `true`.
 Instead of the wildcard symbol, we can instruct Camel to use the message
 body as shown:
 
-._Java-only: bean binding with Simple expression parameter_
+[tabs]
+====
+Java::
++
 [source,java]
 ----
 .bean(OrderService.class, "doSomething(${body}, true)")
 ----
 
+XML::
++
+[source,xml]
+----
+<bean beanType="com.foo.OrderService" method="doSomething(${body}, true)"/>
+----
+
+YAML::
++
+[source,yaml]
+----
+- from:
+    uri: direct:start
+    steps:
+      - bean:
+          beanType: com.foo.OrderService
+          method: "doSomething(${body}, true)"
+----
+====
+
 The syntax of the parameters is using the 
xref:components:languages:simple-language.adoc[Simple]
 language so we have to use `${ }` placeholders in the body to
 refer to the message body.
diff --git a/docs/user-manual/modules/ROOT/pages/cronscheduledroutepolicy.adoc 
b/docs/user-manual/modules/ROOT/pages/cronscheduledroutepolicy.adoc
index 8ae6fdcb37e4..4458dcee0a11 100644
--- a/docs/user-manual/modules/ROOT/pages/cronscheduledroutepolicy.adoc
+++ b/docs/user-manual/modules/ROOT/pages/cronscheduledroutepolicy.adoc
@@ -43,8 +43,8 @@ Expression for route stop
 |routeStopGracePeriod |int |10000 |the time period to wait before
 initiating graceful route stop
 
-|routeStopTimeUnit |long |TimeUnit.MILLISECONDS |the time unit for the
-grace period expressed as `java.util.concurrent.TimeUnit`
+|timeUnit |`java.util.concurrent.TimeUnit` |MILLISECONDS |the time unit for the
+grace period
 |===
 
 === Suspending a route
@@ -65,10 +65,20 @@ Cron Expression for route suspension
 Cron Expression for route resumption
 |===
 
+=== Cron expression format
+
+The cron expressions use the Quartz format, which starts with seconds:
+`seconds minutes hours day-of-month month day-of-week [year]`.
+One of `day-of-month` and `day-of-week` must be `?`.
+For example, `0 0 8 ? * MON-FRI` is at 8:00 from Monday to Friday.
+A Unix cron expression with five fields, such as `* * * * *`, is invalid, and 
Camel fails to start.
+See xref:components::quartz-component.adoc#_using_cron_triggers[Using Cron 
Triggers] in the Quartz component.
+
 == Configuring the route policy
 
 Once the `org.apache.camel.routepolicy.quartz.CronScheduledRoutePolicy`
-is created it can be wired into the Camel route as follows:
+is created it can be wired into the Camel route as follows. In this example, 
the route that consumes
+from a JMS queue is started at 8:00 and stopped at 18:00 every day:
 
 [tabs]
 ====
@@ -77,26 +87,28 @@ Java::
 +
 [source,java]
 ----
-CronScheduledRoutePolicy startPolicy = new CronScheduledRoutePolicy();
-startPolicy.setRouteStartTime("*/3 * * * * ?");
-                
-from("direct:start")
-    .routeId("testRoute").routePolicy(startPolicy).noAutoStartup()
-    .to("mock:success");
+CronScheduledRoutePolicy policy = new CronScheduledRoutePolicy();
+policy.setRouteStartTime("0 0 8 * * ?");
+policy.setRouteStopTime("0 0 18 * * ?");
+
+from("jms:queue:orders")
+    .routeId("orders").routePolicy(policy).noAutoStartup()
+    .to("log:orders");
 ----
 
 Spring XML::
 +
 [source,xml]
 ----
-<bean id="startPolicy" 
class="org.apache.camel.routepolicy.quartz.CronScheduledRoutePolicy">
-    <property name="routeStartTime" value="*/3 * * * * ?"/>
+<bean id="policy" 
class="org.apache.camel.routepolicy.quartz.CronScheduledRoutePolicy">
+    <property name="routeStartTime" value="0 0 8 * * ?"/>
+    <property name="routeStopTime" value="0 0 18 * * ?"/>
 </bean>
-    
+
 <camelContext xmlns="http://camel.apache.org/schema/spring";>
-    <route id="testRoute" routePolicyRef="startPolicy" autoStartup="false">
-        <from uri="direct:start"/>
-        <to uri="mock:success"/>
+    <route id="orders" routePolicyRef="policy" autoStartup="false">
+        <from uri="jms:queue:orders"/>
+        <to uri="log:orders"/>
     </route>
 </camelContext>
 ----
@@ -106,19 +118,20 @@ YAML::
 [source,yaml]
 ----
 - beans:
-  - name: startPolicy
+  - name: policy
     type: org.apache.camel.routepolicy.quartz.CronScheduledRoutePolicy
     properties:
-      routeStartTime: "*/3 * * * * ?"
+      routeStartTime: "0 0 8 * * ?"
+      routeStopTime: "0 0 18 * * ?"
 - route:
-    id: testRoute
+    id: orders
     autoStartup: "false"
-    routePolicyRef: startPolicy
+    routePolicyRef: policy
     from:
-      uri: direct:start
+      uri: jms:queue:orders
       steps:
         - to:
-            uri: mock:success
+            uri: log:orders
 ----
 ====
 
@@ -126,6 +139,11 @@ IMPORTANT: Notice how the route to be scheduled *MUST* be 
configured to not
 xref:configuring-route-startup-ordering-and-autostartup.adoc[auto-startup], to 
let
 the route scheduler take control of starting and stopping the route 
accordingly.
 
+NOTE: A route policy only starts, stops, suspends or resumes the route. It 
never creates or sends a message:
+while the route is started, its consumer (such as JMS or file) takes the 
messages.
+To run a task at a given time, use the 
xref:components::quartz-component.adoc[Quartz],
+xref:components::timer-component.adoc[Timer] or 
xref:components::scheduler-component.adoc[Scheduler] component instead.
+
 === Dependency
 
 Maven users will need to add a camel-quartz dependency to their
diff --git a/docs/user-manual/modules/ROOT/pages/oncompletion.adoc 
b/docs/user-manual/modules/ROOT/pages/oncompletion.adoc
index f7d3301e9c3d..1ef792259457 100644
--- a/docs/user-manual/modules/ROOT/pages/oncompletion.adoc
+++ b/docs/user-manual/modules/ROOT/pages/oncompletion.adoc
@@ -35,12 +35,13 @@ headers, or send to a log to log the response message, etc.
 === onCompletion with route scope
 
 The OnCompletion EIP allows you to add custom routes/processors when
-the original Exchange is complete. Camel spins off a
-copy of the Exchange and routes it in a separate
-thread, similar to a Wire Tap. This allows the
-original thread to continue while the onCompletion route is running
-concurrently. We chose this model as we did not want the
-onCompletion route to interfere with the original route.
+the original Exchange is complete. In the default `AfterConsumer` mode, Camel 
spins off a
+copy of the Exchange, so the onCompletion route does not interfere with the 
original route.
+
+By default, the onCompletion route runs synchronously, in the thread that 
completes the original Exchange,
+after it is complete. In `BeforeConsumer` mode, it runs before the consumer 
writes the response.
+To run it in a separate thread, concurrently with the original thread, set 
`parallelProcessing`
+or `executorService` (see <<Using onCompletion with or without thread pool>>).
 
 === Multiple onCompletions
 
diff --git a/docs/user-manual/modules/ROOT/pages/producertemplate.adoc 
b/docs/user-manual/modules/ROOT/pages/producertemplate.adoc
index 752981add80d..ddb136065007 100644
--- a/docs/user-manual/modules/ROOT/pages/producertemplate.adoc
+++ b/docs/user-manual/modules/ROOT/pages/producertemplate.adoc
@@ -119,15 +119,27 @@ Object result = FluentProducerTemplate.on(context)
 You have sent an Exchange to Camel, but it fails during processing caused
 by a thrown Exception. How do I retrieve this Exception?
 
-If you are using CamelTemplate (or CamelProducer), then it is common to
-use the sendBody/requestBody methods that returns the exchange body
-response *only*. So if there was a thrown exception during processing
-Camel is not rethrowing this Exception. To remedy this you can use the
-plain send/request methods that accepts an Exchange object and returns
-an Exchange object.
-
-From the returned Exchange you can test if it has failed and get the caused
-exception. This is illustrated in the code sample:
+The `sendBody` and `requestBody` methods (and their variants with headers) 
return the body *only*.
+When processing fails, they throw a `CamelExecutionException`:
+
+* `getCause()` returns the exception that caused the exchange to fail. An EIP 
such as
+xref:components:eips:multicast-eip.adoc[Multicast] can wrap it in another 
exception, so use
+`ObjectHelper.getException(MyException.class, e)` to find it in the cause 
chain.
+* `getExchange()` returns the failed exchange.
+
+._Java-only: catching the exception thrown by requestBody_
+[source,java]
+----
+try {
+    template.requestBody("direct:input", "Hello Paris");
+} catch (CamelExecutionException e) {
+    IllegalArgumentException cause = 
ObjectHelper.getException(IllegalArgumentException.class, e);
+}
+----
+
+The `send` and `request` methods that take an `Exchange` or a `Processor` do 
not throw.
+They return the exchange: test if it has failed and get the caused exception 
from it.
+This is illustrated in the code sample:
 
 ._Java-only: retrieving a thrown exception from the returned Exchange_
 [source,java]
diff --git a/docs/user-manual/modules/ROOT/pages/route-policy.adoc 
b/docs/user-manual/modules/ROOT/pages/route-policy.adoc
index d852695212d9..e2de7ae70fea 100644
--- a/docs/user-manual/modules/ROOT/pages/route-policy.adoc
+++ b/docs/user-manual/modules/ROOT/pages/route-policy.adoc
@@ -94,6 +94,94 @@ is based its metrics on number of in flight exchanges whereas
 xref:components:eips:throttle-eip.adoc[Throttler] EIP is based on number o
 messages per time unit.
 
+== `ThrottlingExceptionRoutePolicy`
+
+The *`ThrottlingExceptionRoutePolicy`* works like a circuit breaker on the 
route consumer:
+
+* When `failureThreshold` exchanges fail within `failureWindow`, the circuit 
opens: the policy suspends the consumer
+(or stops it, if it cannot be suspended). The consumer takes no new messages; 
with a queue, such as JMS, they wait in
+the queue.
+* After `halfOpenAfter`, the circuit is half open: the policy resumes the 
consumer, and the next exchange decides.
+A success closes the circuit, a failure opens it again.
+* With a `halfOpenHandler`, the policy calls the handler instead of resuming 
the consumer, and closes the circuit
+when the handler returns `true`.
+
+The circuit closes by itself, so you do not need to resume the route.
+
+The throttling exception route policy has the following options:
+
+[width="100%",cols="10%,10%,80%",options="header",]
+|===
+|Option |Default |Description
+|`failureThreshold` |`50` |How many failed exchanges within the 
`failureWindow` open the circuit.
+|`failureWindow` |`60000` |The sliding window (in millis) in which the 
failures are counted.
+|`halfOpenAfter` |`30000` |How long (in millis) the circuit stays open before 
it is half open. Must be greater than 0.
+|`exceptions` | |Only the exceptions of these types count as a failure (FQN 
class names separated by comma). By default, any exception counts.
+|`keepOpen` |`false` |Whether to always keep the circuit open (it never 
closes). This is only intended for development and testing.
+|`halfOpenHandler` | |A custom 
`org.apache.camel.throttling.ThrottlingExceptionHalfOpenHandler` that checks 
whether the circuit can be closed, instead of resuming the consumer.
+|`stateLoggingLevel` |`DEBUG` |The logging level used for logging the state 
changes.
+|===
+
+For example, to stop consuming from a JMS queue when 5 exchanges fail with a 
`java.net.ConnectException` within a minute,
+and to try again after 10 seconds:
+
+[tabs]
+====
+
+Java::
++
+[source,java]
+----
+ThrottlingExceptionRoutePolicy policy = new ThrottlingExceptionRoutePolicy();
+policy.setFailureThreshold(5);
+policy.setFailureWindow(60000);
+policy.setHalfOpenAfter(10000);
+policy.setExceptions("java.net.ConnectException");
+
+from("jms:queue:orders")
+    .routePolicy(policy)
+    .to("http://orders-service/orders";);
+----
+
+XML::
++
+[source,xml]
+----
+<bean id="ordersPolicy" 
class="org.apache.camel.throttling.ThrottlingExceptionRoutePolicy">
+    <property name="failureThreshold" value="5"/>
+    <property name="failureWindow" value="60000"/>
+    <property name="halfOpenAfter" value="10000"/>
+    <property name="exceptions" value="java.net.ConnectException"/>
+</bean>
+
+<route routePolicyRef="ordersPolicy">
+    <from uri="jms:queue:orders"/>
+    <to uri="http://orders-service/orders"/>
+</route>
+----
+
+YAML::
++
+[source,yaml]
+----
+- beans:
+  - name: ordersPolicy
+    type: org.apache.camel.throttling.ThrottlingExceptionRoutePolicy
+    properties:
+      failureThreshold: 5
+      failureWindow: 60000
+      halfOpenAfter: 10000
+      exceptions: java.net.ConnectException
+- route:
+    routePolicyRef: ordersPolicy
+    from:
+      uri: jms:queue:orders
+      steps:
+        - to:
+            uri: http://orders-service/orders
+----
+====
+
 == ScheduledRoutePolicy
 
 See xref:scheduledroutepolicy.adoc[Scheduled Route Policy] for scheduling 
based route policy.
@@ -120,7 +208,7 @@ from("seda:foo")
 
 XML::
 +
-In XML you configure using the `routePolictRef` attribute on `<route>` as 
shown:
+In XML you configure using the `routePolicyRef` attribute on `<route>` as 
shown:
 +
 [source,xml]
 ----
@@ -134,7 +222,7 @@ In XML you configure using the `routePolictRef` attribute 
on `<route>` as shown:
 
 YAML::
 +
-In YAML you configure using the `routePolictRef` attribute on `route` node as 
shown:
+In YAML you configure using the `routePolicyRef` attribute on `route` node as 
shown:
 +
 [source,yaml]
 ----
diff --git 
a/docs/user-manual/modules/ROOT/pages/simplescheduledroutepolicy.adoc 
b/docs/user-manual/modules/ROOT/pages/simplescheduledroutepolicy.adoc
index d337fac3133d..10532826604a 100644
--- a/docs/user-manual/modules/ROOT/pages/simplescheduledroutepolicy.adoc
+++ b/docs/user-manual/modules/ROOT/pages/simplescheduledroutepolicy.adoc
@@ -50,8 +50,8 @@ trigger the next attempt to stop the route
 |routeStopGracePeriod |int |10 seconds |the time period to wait before
 initiating graceful route stop
 
-|routeStopTimeUnit |long |TimeUnit.MILLISECONDS |the time unit for the
-grace period expressed as java.util.concurrent.TimeUnit
+|timeUnit |java.util.concurrent.TimeUnit |MILLISECONDS |the time unit for the
+grace period
 |=======================================================================
 
 * Suspending a route
@@ -103,17 +103,19 @@ policy.setRouteStartDate(new Date(startTime));
 policy.setRouteStartRepeatCount(1);
 policy.setRouteStartRepeatInterval(3000);
 
-from("direct:start")
+from("file:inbox")
    .routeId("test")
    .routePolicy(policy)
-   .to("mock:success");
+   .noAutoStartup()
+   .to("log:inbox");
 ----
 
 XML::
 +
 [source,xml]
 ----
-<bean id="date" class="org.apache.camel.routepolicy.quartz.SimpleDate"/>
+<!-- the date and time when the bean is created -->
+<bean id="date" class="java.util.Date"/>
 
 <bean id="startPolicy" 
class="org.apache.camel.routepolicy.quartz.SimpleScheduledRoutePolicy">
     <property name="routeStartDate" ref="date"/>
@@ -122,9 +124,9 @@ XML::
 </bean>
 
 <camelContext xmlns="http://camel.apache.org/schema/spring";>
-    <route id="myroute" routePolicyRef="startPolicy">
-        <from uri="direct:start"/>
-        <to uri="mock:success"/>
+    <route id="myroute" routePolicyRef="startPolicy" autoStartup="false">
+        <from uri="file:inbox"/>
+        <to uri="log:inbox"/>
     </route>
 </camelContext>
 ----
@@ -133,17 +135,35 @@ YAML::
 +
 [source,yaml]
 ----
+- beans:
+  - name: startPolicy
+    type: org.apache.camel.routepolicy.quartz.SimpleScheduledRoutePolicy
+    properties:
+      # the date and time when the bean is created
+      routeStartDate: "#class:java.util.Date"
+      routeStartRepeatCount: 1
+      routeStartRepeatInterval: 3000
 - route:
     id: myroute
+    autoStartup: "false"
     routePolicyRef: startPolicy
     from:
-      uri: direct:start
+      uri: file:inbox
       steps:
         - to:
-            uri: mock:success
+            uri: log:inbox
 ----
 ====
 
+IMPORTANT: The route to be scheduled *MUST* be configured to not
+xref:configuring-route-startup-ordering-and-autostartup.adoc[auto-startup], to 
let
+the route scheduler take control of starting and stopping the route 
accordingly.
+
+NOTE: A route policy only starts, stops, suspends or resumes the route. It 
never creates or sends a message:
+while the route is started, its consumer (such as JMS or file) takes the 
messages.
+To run a task at a given time, use the 
xref:components::quartz-component.adoc[Quartz],
+xref:components::timer-component.adoc[Timer] or 
xref:components::scheduler-component.adoc[Scheduler] component instead.
+
 == Dependency
 
 Maven users will need to add a `camel-quartz` dependency to their
diff --git a/docs/user-manual/modules/ROOT/pages/stream-caching.adoc 
b/docs/user-manual/modules/ROOT/pages/stream-caching.adoc
index 89188feb1f47..2e2c5471aae1 100644
--- a/docs/user-manual/modules/ROOT/pages/stream-caching.adoc
+++ b/docs/user-manual/modules/ROOT/pages/stream-caching.adoc
@@ -2,6 +2,8 @@
 
 While stream types (like `StreamSource`, `InputStream` and `Reader`) are 
commonly used in messaging for performance reasons, they also have an important 
drawback: they can only be read once. In order to be able to work with message 
content multiple times, the stream needs to be cached.
 
+Stream caching is enabled by default. You can turn it off on the 
`CamelContext` or on a single route.
+
 Streams are cached in memory. However, for large stream messages, you can set 
`spoolEnabled=true`
 and then large message (over 128 KB) will be cached in a temporary file 
instead.
 Camel itself will handle deleting the temporary file once the cached stream is 
no longer necessary.
@@ -23,6 +25,10 @@ A number of Camel components supports and use streaming 
types out of the
 box. For example the HTTP related components, CXF, etc.
 
 Camel comes with Stream Caching that caches the stream, so it can be 
re-readable.
+It is enabled by default, so a body can still be empty when:
+
+* stream caching is turned off on the route or on the `CamelContext`;
+* your own code reads the body twice within the same processor or bean (see 
<<Reading the body more than once in your own code>>).
 
 [IMPORTANT]
 ====
@@ -111,14 +117,14 @@ context.getStreamCachingStrategy().setBufferSize(16 * 
1024);
 // context.getStreamCachingStrategy().setSpoolCipher("RC4");
 ----
 
-And remember to enable Stream caching on the `CamelContext`:
+Stream caching is enabled by default. To turn it off on the `CamelContext`:
 
 [source,java]
 ----
-context.setStreamCaching(true);
+context.setStreamCaching(false);
 ----
 
-or on routes:
+or on routes (here it is turned on for a single route, when it is off on the 
`CamelContext`):
 
 [tabs]
 ====
@@ -192,7 +198,7 @@ In xref:spring-xml-extensions.adoc[Spring XML] you can 
enable stream caching on
 
 == Using spoolUsedHeapMemoryThreshold
 
-By default, stream caching will spool only big payloads (128 KB or bigger) to 
disk. However you can also set the `spoolUsedHeapMemoryThreshold` option which 
is a percentage of used heap memory. This can be used to also spool to disk 
when running low on memory.
+When `spoolEnabled` is `true`, stream caching spools only big payloads (128 KB 
or bigger) to disk. By default, `spoolEnabled` is `false` and nothing is 
spooled. You can also set the `spoolUsedHeapMemoryThreshold` option which is a 
percentage of used heap memory. This can be used to also spool to disk when 
running low on memory.
 
 For example with:
 
@@ -380,6 +386,29 @@ from("direct:start")
     .to("log:cached");
 ----
 
+== Reading the body more than once in your own code
+
+Camel resets the stream cache before and after each step of the route (for 
example a processor, a bean or a `to`).
+It does not reset it within a step. When a processor or a bean reads a 
streaming body twice, the second read is empty.
+The next step reads the whole body again.
+
+Read the body once into a variable, or reset the stream cache before reading 
it again:
+
+[source,java]
+----
+public void process(Exchange exchange) {
+    // resets the stream cache, then converts the body
+    String first = ExchangeHelper.getBodyAndResetStreamCache(exchange, 
String.class);
+    String second = ExchangeHelper.getBodyAndResetStreamCache(exchange, 
String.class);
+
+    // or reset the stream cache yourself
+    MessageHelper.resetStreamCache(exchange.getMessage());
+}
+----
+
+The same applies to the original message 
(`exchange.getUnitOfWork().getOriginalInMessage()`): when the incoming body
+is a stream, its body is a `StreamCache`. Call 
`MessageHelper.resetStreamCache` on it before reading its body.
+
 == How do I enable streams when debug logging messages in Camel
 
 When you run Camel with `DEBUG` level as logging, it will log the
diff --git a/docs/user-manual/modules/ROOT/pages/testing.adoc 
b/docs/user-manual/modules/ROOT/pages/testing.adoc
index 2a35a1029b75..05495c79ca46 100644
--- a/docs/user-manual/modules/ROOT/pages/testing.adoc
+++ b/docs/user-manual/modules/ROOT/pages/testing.adoc
@@ -23,9 +23,9 @@ The following modules are supported:
 |xref:components:others:test-main-junit5.adoc[camel-test-main-junit5] | *JUnit 
5*: Used for testing Camel in Camel Main mode
 |xref:components:others:test-spring-junit5.adoc[camel-test-spring-junit5] | 
*JUnit 5*: Used for testing Camel with Spring / Spring Boot
 
-|xref:components:others:test-junit6.adoc[camel-test-junit5] |*JUnit 6*: Used 
for testing Camel in standalone mode (or without Spring)
-|xref:components:others:test-main-junit6.adoc[camel-test-main-junit5] | *JUnit 
6*: Used for testing Camel in Camel Main mode
-|xref:components:others:test-spring-junit6.adoc[camel-test-spring-junit5] | 
*JUnit 6*: Used for testing Camel with Spring / Spring Boot
+|xref:components:others:test-junit6.adoc[camel-test-junit6] |*JUnit 6*: Used 
for testing Camel in standalone mode (or without Spring)
+|xref:components:others:test-main-junit6.adoc[camel-test-main-junit6] | *JUnit 
6*: Used for testing Camel in Camel Main mode
+|xref:components:others:test-spring-junit6.adoc[camel-test-spring-junit6] | 
*JUnit 6*: Used for testing Camel with Spring / Spring Boot
 
 |xref:test-infra.adoc[camel-test-infra] | *Camel Test Infra*: Camel Test Infra 
is a set of modules that leverage modern JUnit 5 features to abstract the 
provisioning and execution of test infrastructure. Among other things, it 
provides abstraction of the infrastructure (based on Test Containers - being 
the de-facto successor of the camel-testcontainers components) as well as JUnit 
5 extensions for the Camel Context itself.
 |xref:camel-jbang-test.adoc[camel-jbang-test] | *Camel CLI Test Plugin*: A 
Camel CLI plugin to help writing automated tests during prototyping with JBang. 
The tests are able to start the Camel integration and verify its logic from the 
very beginning. The test plugin does not require any project setup so you can 
just start writing and executing automated tests.
diff --git a/docs/user-manual/modules/ROOT/pages/using-propertyplaceholder.adoc 
b/docs/user-manual/modules/ROOT/pages/using-propertyplaceholder.adoc
index c2e02fc989a5..904baa714554 100644
--- a/docs/user-manual/modules/ROOT/pages/using-propertyplaceholder.adoc
+++ b/docs/user-manual/modules/ROOT/pages/using-propertyplaceholder.adoc
@@ -595,69 +595,19 @@ This means Camel has special features that apply only to 
Spring XML.
 
 === Using property placeholders for any kind of attribute in Spring XML files
 
-Previously it was only the `xs:string` type attributes in the XML DSL
-that support placeholders. For example often a timeout attribute would
-be a `xs:int` type, and thus you cannot set a string value as the
-placeholder key. This is now possible using a special
-placeholder namespace.
+Every attribute of the XML DSL is a string, so you can use a `+{{key}}+` 
placeholder in any attribute,
+also for an option that is a boolean or a number.
 
-In the example below we use the `prop` prefix for the namespace
-`\http://camel.apache.org/schema/placeholder`. Now we can use `prop:` as prefix
-to configure any kind of XML attributes in Spring XML files.
-
-In the example below we want to use a placeholder for the `stopOnException` 
option in
-the xref:components:eips:multicast-eip.adoc[Multicast] EIP. The 
`stopOnException` is a `xs:boolean` type,
-so we cannot configure this as:
+In the example below we use a placeholder for the `stopOnException` option of 
the
+xref:components:eips:multicast-eip.adoc[Multicast] EIP:
 
 [source,xml]
 ----
 <multicast stopOnException="{{stop}}">
-   ...
-</multicast>
-----
-
-Instead, we must use the `prop:` namespace, so we must add this namespace
-in the top of the XML file in the `<beans>` tag.
-
-To configure the option we must then use the `prop:optionName` as shown below:
-
-[source,xml]
-----
-<multicast prop:stopOnException="stop">
   ...
 </multicast>
 ----
 
-The complete example is below:
-
-.Spring XML
-[source,xml]
-----
-<beans xmlns="http://www.springframework.org/schema/beans"; 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
-       xmlns:prop="http://camel.apache.org/schema/placeholder";
-       xsi:schemaLocation="
-           http://www.springframework.org/schema/beans 
http://www.springframework.org/schema/beans/spring-beans.xsd
-           http://camel.apache.org/schema/spring 
http://camel.apache.org/schema/spring/camel-spring.xsd";>
-
-    <bean id="damn" class="java.lang.IllegalArgumentException">
-        <constructor-arg index="0" value="Damn"/>
-    </bean>
-
-    <camelContext xmlns="http://camel.apache.org/schema/spring";>
-        <propertyPlaceholder id="properties" 
location="classpath:myprop.properties"/>
-        <route>
-            <from uri="direct:start"/>
-            <!-- use prop namespace, to define a property placeholder, which 
maps to option stopOnException={{stop}} -->
-            <multicast prop:stopOnException="stop">
-                <to uri="mock:a"/>
-                <throwException ref="damn"/>
-                <to uri="mock:b"/>
-            </multicast>
-        </route>
-    </camelContext>
-</beans>
-----
-
 In our properties file we have the value defined as:
 
 [source,properties]
@@ -665,6 +615,9 @@ In our properties file we have the value defined as:
 stop = true
 ----
 
+NOTE: The `prop:` placeholder namespace 
(`\http://camel.apache.org/schema/placeholder`) was removed in Camel 3.1
+(see xref:camel-3x-upgrade-guide-3_1.adoc#_property_placeholders[Property 
Placeholders]). An attribute such as `prop:stopOnException="stop"` fails the 
XML schema validation. Use `+stopOnException="{{stop}}"+` instead.
+
 === Bridging Camel property placeholders with Spring XML files
 
 NOTE: If you are using Spring Boot then this does not apply.

Reply via email to