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 is a good base class to extend org.apache.camel.support.RoutePolicySupport.

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 automatic 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.

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).

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 inflight route policy has the following options:

Option Default Description

scope

Route

A scope for either Route or Context which defines if the current number of inflight exchanges is context based or for that particular route.

maxInflightExchanges

1000

The maximum threshold when the throttling will start to suspend the route if the current number of inflight exchanges is higher than this value.

resumePercentOfMax

70

A percentage 0..100 which defines when the throttling should resume again in case it has been suspended.

loggingLevel

INFO

The logging level used for logging the throttling activity.

logger

ThrottlingInflightRoutePolicy

The logger category.

ThrottlingInflightRoutePolicy compared to the Throttler EIP

The ThrottlingInflightRoutePolicy compared to Throttler EIP is that it does not block during throttling. It does throttling that is approximate based, meaning that its more coarse grained and not explicit precise as the Throttler EIP.

The Throttler EIP can be much more accurate and only allow a specific number of messages being passed per a given time unit. Also the ThrottlingInflightRoutePolicy is based its metrics on number of inflight exchanges where as Throttler EIP is based on number o messages per time unit.

ScheduledRoutePolicy

See Scheduled Route Policy for scheduling based route policy.

Using route policies in Camel routes

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 Spring XML you configure using the routePolictRef attribute on <route> as shown:

<bean id="myPolicy" class="com.mycompany.MyRoutePolicy"/>

<route routePolicyRef="myPolicy">
    <from uri="seda:foo"/>
    <to uri="mock:result"/>
</route>

You can configure one or more route policies (separated by comma), such as:

from("seda:foo").routePolicy(myPolicy, myOtherPolicy).to("mock:result");

And in XML:

<route routePolicyRef="myPolicy,myOtherPolicy">
    <from uri="seda:foo"/>
    <to uri="mock:result"/>
</route>

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 a RoutePolicy instance for each route. This can be used when you want to use the same kind of route policy for all or some routes.

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

context.addRoutePolicyFactory(new MyRoutePolicyFactory());

And from XML DSL you just define a <bean> with the factory, and Camel will automatically detect this factory:

<bean id="myRoutePolicyFactory" class="com.foo.MyRoutePolicyFactory"/>

You can have as many route policy factories as you want, so if you have two factories, you can just add them both as shown:

context.addRoutePolicyFactory(new MyRoutePolicyFactory());
context.addRoutePolicyFactory(new MyOtherRoutePolicyFactory());

And in XML:

<bean id="myRoutePolicyFactory" class="com.foo.MyRoutePolicyFactory"/>
<bean id="myOtherRoutePolicyFactory" class="com.foo.MyOtherRoutePolicyFactory"/>
Back to top