Failover - 6.3

The failover load balancer is capable of trying the next processor in case an Exchange failed with an exception during processing. You can configure the failover with a list of specific exception to only failover. If you do not specify any exceptions it will failover over any exceptions. It uses the same strategy for matching exceptions as the Exception Clause does for the onException.

Important

If you use streaming then you should enable Stream caching when using the failover load balancer. This is needed so the stream can be re-read when failing over.

It has the following options:

Option	Type	Default	Description
inheritErrorHandler	boolean	true	Whether or not the Error Handler configured on the route should be used or not. You can disable it if you want the failover to trigger immediately and failover to the next endpoint. On the other hand if you have this option enabled, then Camel will first let the Error Handler try to process the message. The Error Handler may have been configured to redelivery and use delays between attempts. If you have enabled a number of redeliveries then Camel will try to redeliver to the same endpoint, and only failover to the next endpoint, when the Error Handler is exhausted.
maximumFailover-Attempts	int	-1	A value to indicate after X failver attempts we should exhaust (give up). Use -1 to indicate newer give up and always try to failover. Use 0 to newer failover. And use e.g. 3 to failover at most 3 times before giving up. This option can be used whether or not round robin is enabled or not.
roundRobin	boolean	false	Whether or not the `failover` load balancer should operate in round robin mode or not. If not, then it will always start from the first endpoint when a new message is to be processed. In other words it restart from the top for every message. If round robin is enabled, then it keeps state and will continue with the next endpoint in a round robin fashion. When using round robin it will not stick to last known good endpoint, it will always pick the next endpoint to use.

The failover load balancer supports round robin mode, which allows you to failover in a round robin fashion. See the roundRobin option.

Here is a sample to failover only if a IOException related exception was thrown:

from("direct:start")
    // here we will load balance if IOException was thrown
    // any other kind of exception will result in the Exchange as failed
    // to failover over any kind of exception we can just omit 
    // the exception in the failOver DSL
    .loadBalance().failover(IOException.class)
        .to("direct:x", "direct:y", "direct:z");

You can specify multiple exceptions to failover as the option is varargs, for instance:

// enable redelivery so failover can react
errorHandler(defaultErrorHandler().maximumRedeliveries(5));

from("direct:foo").
    loadBalance().failover(IOException.class, MyOtherException.class)
        .to("direct:a", "direct:b");

Using failover in Spring DSL

Failover can also be used from Spring DSL and you configure it as:

<route errorHandlerRef="myErrorHandler">
      <from uri="direct:foo"/>
      <loadBalance>
          <failover>
              <exception>java.io.IOException</exception>
              <exception>com.mycompany.MyOtherException</exception>
          </failover>
          <to uri="direct:a"/>
          <to uri="direct:b"/>
      </loadBalance>
</route>

Using failover in round robin mode

An example using Java DSL:

from("direct:start")
    // Use failover load balancer in stateful round robin mode
    // which mean it will failover immediately in case of an exception
    // as it does NOT inherit error handler. It will also keep retrying as
    // it is configured to newer exhaust.
    .loadBalance().failover(-1, false, true).
        to("direct:bad", "direct:bad2", "direct:good", "direct:good2");

And the same example using Spring XML:

<route>
    <from uri="direct:start"/>
    <loadBalance>
        <!-- failover using stateful round robin,
             which will keep retrying forever those 
             4 endpoints until success. You can set
             the maximumFailoverAttempt to break out after 
             X attempts -->
        <failover roundRobin="true"/>
        <to uri="direct:bad"/>
        <to uri="direct:bad2"/>
        <to uri="direct:good"/>
        <to uri="direct:good2"/>
    </loadBalance>
</route>