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.