RoutePolicy
A route policy org.apache.camel.spi.RoutePolicy is used to control route(s) at runtime. For example, you can use it to determine whether a route should be running or not. However, the policies can support any kind of use cases.
How it works
You associate a route with a given RoutePolicy and then during runtime Camel will invoke callbacks on this policy where you can implement your custom logic. Camel provides a support class that can be used to extend org.apache.camel.support.RoutePolicySupport and implement your logic.
There are these callbacks invoked:
-
onInit -
onRemove -
onStart -
onStop -
onSuspend -
onResume -
onExchangeBegin -
onExchangeDone
See the Javadoc of the org.apache.camel.spi.RoutePolicy for more details; and also the implementation of the org.apache.camel.throttling.ThrottlingInflightRoutePolicy for a concrete example.
Camel provides the following policies out of the box:
-
org.apache.camel.throttling.ThrottlingInflightRoutePolicy- a throttling based policy that automatically suspends/resumes route(s) based on metrics from the current in flight exchanges. You can use this to dynamically throttle, e.g. a JMS consumer, to avoid it consuming too fast. -
org.apache.camel.throttling.ThrottlingExceptionRoutePolicy- a throttling based policy modeled after the circuit breaker. This policy will stop consuming from an endpoint based on the type of exceptions that are thrown and the threshold setting. The exception an exchange fails with and its causes are matched against the exceptions to throttle on (the same asonExceptionanddoCatch). Suppressed exceptions, such as an exception thrown in adoFinallyblock, are not matched. -
org.apache.camel.impl.cluster.ClusteredRoutePolicy- is the foundation forcamel-clusterwhich handles Camel routes to become active if a node becomes leader in a cluster.
Camel also provides an ability to schedule routes to be activated, deactivated, suspended and/or resumed at certain times during the day using a ScheduledRoutePolicy (offered via the Quartz component).
And route policy is also used as an implementation details for some of the Camel observability components.
SuspendableService
If you want to dynamic suspend/resume routes, then it is advised to use SuspendableService as it allows for fine-grained suspend and resume operations.
ThrottlingInflightRoutePolicy
The ThrottlingInflightRoutePolicy is triggered when an Exchange is complete, which means that it requires at least one Exchange to be complete before it works.
The throttling in flight route policy has the following options:
| Option | Default | Description |
|---|---|---|
|
| A scope for either |
|
| The maximum threshold when the throttling will start to suspend the route if the current number of in flight exchanges is higher than this value. |
|
| A percentage |
|
| The logging level used for logging the throttling activity. |
|
| The logger category. |
ThrottlingExceptionRoutePolicy
The ThrottlingExceptionRoutePolicy works like a circuit breaker on the route consumer:
-
When
failureThresholdexchanges fail withinfailureWindow, 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 returnstrue.
The circuit closes by itself, so you do not need to resume the route.
The throttling exception route policy has the following options:
| Option | Default | Description |
|---|---|---|
|
| How many failed exchanges within the |
|
| The sliding window (in millis) in which the failures are counted. |
|
| How long (in millis) the circuit stays open before it is half open. Must be greater than 0. |
| Only the exceptions of these types count as a failure (FQN class names separated by comma). By default, any exception counts. | |
|
| Whether to always keep the circuit open (it never closes). This is only intended for development and testing. |
| A custom | |
|
| 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:
-
Java
-
XML
-
YAML
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"); <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> - 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 Scheduled Route Policy for scheduling based route policy.
Using RoutePolicy in Camel routes
On the route(s) that should use one or more route policies, you configure this as shown below:
-
Java
-
XML
-
YAML
You configure the route policy as follows from Java DSL, using the routePolicy method:
RoutePolicy myPolicy = new MyRoutePolicy();
from("seda:foo")
.routePolicy(myPolicy)
.to("mock:result"); In XML you configure using the routePolicyRef attribute on <route> as shown:
<bean id="myPolicy" class="com.mycompany.MyRoutePolicy"/>
<route routePolicyRef="myPolicy">
<from uri="seda:foo"/>
<to uri="mock:result"/>
</route> In YAML you configure using the routePolicyRef attribute on route node as shown:
- route:
routePolicyRef: myPolicy
from:
uri: seda:foo
steps:
- to:
uri: mock:result You can configure one or more route policies (separated by comma), such as:
-
Java
-
XML
-
YAML
from("seda:foo")
.routePolicy(myPolicy, myOtherPolicy)
.to("mock:result"); <bean id="myPolicy" class="com.mycompany.MyRoutePolicy"/>
<route routePolicyRef="myPolicy,myOtherPolicy">
<from uri="seda:foo"/>
<to uri="mock:result"/>
</route> - route:
routePolicyRef: myPolicy,myOtherPolicy
from:
uri: seda:foo
steps:
- to:
uri: mock:result Using RoutePolicyFactory
If you want to use a route policy for every route, you can use a org.apache.camel.spi.RoutePolicyFactory as a factory for creating new RoutePolicy instance(s) for each route. This can be used when you want to use the same kind of route policy for all.
With the factory, you only need to configure this once, and every route created will have the policy assigned.
There is API on CamelContext to add a factory, as shown below
-
Java
-
Spring Boot
-
Quarkus
-
Spring XML
-
XML
-
YAML
CamelContext context = ...
context.addRoutePolicyFactory(new MyRoutePolicyFactory()); You can also mark your class with Spring Boot @Component for automatic dependency injection
@Component
public class MyRoutePolicyFactory() {
} You can also mark your class with Quarkus @.ApplicationScoped for automatic dependency injection
@ApplicationScoped
public class MyRoutePolicyFactory() {
} And from Spring XML DSL you just define a <bean> with the factory, and Camel will automatically detect this factory:
<bean id="myRoutePolicyFactory" class="com.foo.MyRoutePolicyFactory"/> <bean name="myRoutePolicyFactory" type="com.foo.MyRoutePolicyFactory"/> - beans:
- name: myRoutePolicyFactory
type: com.foo.MyRoutePolicyFactory | You can have as many route policy factories as you want, so if you have two factories, you can just add both of them. |