Throttler

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.

Options

Name Default Value Description
maximumRequestsPerPeriod   Maximum number of requests per period to throttle. This option must be provided and a positive number. Notice, in the XML DSL, from Camel 2.8 onwards this option is configured using an Expression instead of an attribute.
timePeriodMillis 1000 The time period in millis, in which the throttler will allow at most maximumRequestsPerPeriod number of messages.
asyncDelayed false Camel 2.4: If enabled then any messages which is delayed happens asynchronously using a scheduled thread pool.
executorServiceRef   Camel 2.4: Refers to a custom Thread Pool to be used if asyncDelay has been enabled.
callerRunsWhenRejected true Camel 2.4: Is used if asyncDelayed was enabled. This controls if the caller thread should execute the task if the thread pool rejected the task.

Examples

Using the Fluent Builders

from("seda:a").throttle(3).timePeriodMillis(10000).to("log:result", "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 typically you would often use the default time period of a second. So to throttle requests at 100 requests per second between two endpoints it would look more like this...

from("seda:a").throttle(100).to("seda:b");

For further examples of this pattern in use you could look at the junit test case

Using the Spring XML Extensions

Camel 2.7.x or older

<route>
  <from uri="seda:a" />
  <throttle maximumRequestsPerPeriod="3" timePeriodMillis="10000">
    <to uri="mock:result" />
  </throttle>
</route>

Camel 2.8 onwards

In Camel 2.8 onwards you must set the maximum period as an Expression as shown below where we use a Constant expression:

<route>
    <from uri="seda:a"/>
    <!-- throttle 3 messages per 10 sec -->
    <throttle timePeriodMillis="10000">
        <constant>3</constant>
        <to uri="mock:result"/>
    </throttle>
</route>

Dynamically changing maximum requests per period

Available os of Camel 2.8
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:

<route>
    <from uri="direct:expressionHeader"/>
    <throttle timePeriodMillis="500">
        <!-- use a header to determine how many messages to throttle per 0.5 sec -->
        <header>throttleValue</header>
        <to uri="mock:result"/>
    </throttle>
</route>

Asynchronous delaying

Available as of Camel 2.4

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.

from("seda:a").throttle(100).asyncDelayed().to("seda:b");

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started, you may also find the Architecture useful particularly the description of Endpoint and URIs. Then you could try out some of the Examples first before trying this pattern out.

© 2004-2011 The Apache Software Foundation.
Apache Camel, Camel, Apache, the Apache feather logo, and the Apache Camel project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
Graphic Design By Hiram