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
commit 7bfc26c98bce99ee16caf61da97a388dfdf61d20
Author: Claus Ibsen <claus.ib...@gmail.com>
AuthorDate: Tue Oct 19 18:54:04 2021 +0200
CAMEL-16861: Cleanup and update EIP docs
---
.../main/docs/modules/eips/pages/throttle-eip.adoc | 65 +++++++++++++++++-----
1 file changed, 52 insertions(+), 13 deletions(-)
diff --git
a/core/camel-core-engine/src/main/docs/modules/eips/pages/throttle-eip.adoc
b/core/camel-core-engine/src/main/docs/modules/eips/pages/throttle-eip.adoc
index 544131c..5afd86a 100644
--- a/core/camel-core-engine/src/main/docs/modules/eips/pages/throttle-eip.adoc
+++ b/core/camel-core-engine/src/main/docs/modules/eips/pages/throttle-eip.adoc
@@ -5,7 +5,11 @@
:since:
:supportlevel: Stable
-The Throttler Pattern allows you to ensure that a specific endpoint does not
get overloaded, or that we don't exceed an agreed SLA with some external
service.
+How can I throttle messages to ensure that a specific endpoint does not get
overloaded, or we don’t exceed an agreed SLA with some external service?
+
+image::eip/MessagingAdapterIcon.gif[image]
+
+Use a Throttler that controls the rate how many or fast messages are flowing
to the endpoint.
== Options
@@ -13,44 +17,62 @@ The Throttler Pattern allows you to ensure that a specific
endpoint does not get
include::partial$eip-options.adoc[]
// eip options: END
-== Samples
+== Using Throttle
+
+The below example will throttle messages all messages received on seda:a
before being sent to mock:result
+ensuring that a maximum of 3 messages are sent during a running 10-seconds
window slot.
[source,java]
----
from("seda:a")
.throttle(3).timePeriodMillis(10000)
- .to("log:result", "mock:result");
+ .to("mock:result");
----
-So the above example will throttle messages all messages received on *seda:a*
before being sent to *mock:result* ensuring that a maximum of 3 messages are
sent in any 10 second window.
-Note that since `timePeriodMillis` defaults to 1000 milliseconds, just setting
the `maximumRequestsPerPeriod` has the effect of setting the maximum number of
requests per second. So to throttle requests at 100 requests per second between
two endpoints, it would look more like this...
+To use 10-seconds window we set the `timePeriodMillis` to ten-thousand. The
default value is 1000 (i.e. 1 second),
+meaning that setting just `throttle(3)` has the effect of setting the maximum
number of requests per second.
+
+To throttle by 50 requests per second, would look like this:
[source,java]
----
from("seda:a")
- .throttle(100)
+ .throttle(50)
.to("seda:b");
----
-For further examples of this pattern in use you could look at the junit test
case.
+And the examples in XML:
-And an example in XML
[source,xml]
----
<route>
<from uri="seda:a"/>
- <!-- throttle 3 messages per 10 sec -->
<throttle timePeriodMillis="10000">
<constant>3</constant>
</throttle>
- <to uri="log:result"/>
<to uri="mock:result"/>
</route>
----
-== Dynamically changing maximum requests per period
+And to throttle 50 message per second:
+
+[source,xml]
+----
+<route>
+ <from uri="seda:a"/>
+ <throttle>
+ <constant>50</constant>
+ </throttle>
+ <to uri="mock:result"/>
+</route>
+----
+
+=== Dynamically changing maximum requests per period
+
+TODO:
Since we use an Expression you can adjust this value at runtime, for example
you can provide a header with the value. At runtime Camel evaluates the
expression and converts the result to a `java.lang.Long` type. In the example
below we use a header from the message to determine the maximum requests per
period. If the header is absent, then the Throttler uses the old value. So that
allows you to only provide a header if the value is to be changed:
+
[source,xml]
----
<route>
@@ -64,9 +86,13 @@ Since we use an Expression you can adjust this value at
runtime, for example you
</route>
----
-== Asynchronous delaying
+=== Asynchronous delaying
-You can let the Throttler use non blocking asynchronous delaying, which means
Camel will use a scheduler to schedule a task to be executed in the future. The
task will then continue routing. This allows the caller thread to not block and
be able to service other messages, etc.
+You can let the Throttler use non-blocking asynchronous delaying,
+which means Camel will use a scheduler to schedule a task to be executed in
the future.
+The task will then continue routing. This allows the caller thread to not
block and be able to service other messages, etc.
+
+In Java DSL you enable asynchronous delaying using `asyncDelayed` as shown:
[source,java]
---------------------
@@ -74,3 +100,16 @@ from("seda:a")
.throttle(100).asyncDelayed()
.to("seda:b");
---------------------
+
+And in XML:
+
+[source,xml]
+----
+<route>
+ <from uri="seda:a"/>
+ <throttle timePeriodMillis="100" asyncDelayed="true">
+ <constant>100</constant>
+ </throttle>
+ <to uri="seda:b"/>
+</route>
+----
\ No newline at end of file
