Page edited by willem jiang

CAMEL-1799

Error Handler

Camel supports pluggable ErrorHandler strategies to deal with errors processing an Event Driven Consumer. An alternative is to specify the error handling directly in the DSL using the Exception Clause.

For introduction and background material see Error handling in Camel.

Camel 2.0 has a new default error handler

In Camel 2.0 onwards there default error handler is changed from Dead Letter Channel to DefaultErrorHandler. This error handler does not support a dead letter queue and will return exceptions back to the caller. This is what you expects when working with regular Java that exceptions will be thrown back to the caller.

Exception Clause

Using Error Handler combined with Exception Clause is a very powerful ally. We encourage end-users to use this combination in your error handling strategies. See samples and Exception Clause.

Using try ... catch ... finally

Related to error handling is the Try Catch Finally as DSL you can use directly in your route. Its basically a mimic of the regular try catch finally in the Java language but with more power.

The current implementations Camel provides out of the box are:

Non transacted

DefaultErrorHandler is the default error handler in Camel 2.0 onwards. This error handler does not support a deal letter queue, it will propagate exceptions back to the caller, as if there where no error handler at all. It has a limited set of features.
Dead Letter Channel which supports attempting to redeliver the message exchange a number of times before sending it to a dead letter endpoint
LoggingErrorHandler for just catching and logging exceptions
NoErrorHandler for no error handling

Transacted

TransactionErrorHandler is the default error handler in Camel 2.0 onwards for transacted routes. This error handler does not support a deal letter queue, it will propagate exceptions back to the caller, as if there where no error handler at all. It has a limited set of features.
Transaction for transactional error handling (Spring based). See the Transactional Client EIP pattern.

These error handlers can be applied in the DSL to an entire set of rules or a specific routing rule as we show in the next examples. Error handling rules are inherited on each routing rule within a single RouteBuilder

Transaction in Camel 1.x

If the route is transactional then the Dead Letter Channel is disabled. The exchange.isTransacted() is used to determine if an Exchange is transacted or not.
So if you are using transacted routes then you should configure the TransactionErrorHandler instread of DeadLetterChannel. See Transactional Client for further details and samples.

Short Summary of the provided Error Handlers

DefaultErrorHandler new in Camel 2.0

The DefaultErrorHandler is the new default error handler in Camel 2.0. Unlike Dead Letter Channel it does not have any dead letter queue, and do not handle exceptions by default.

Dead Letter Channel

The Dead Letter Channel is the default error handler in Camel 1.x, which is automatically configured for you. By default Camel will redeliver at most 6 times using 1 second delay, and if the exchange failed it will be logged at ERROR level.

You can configure the default dead letter endpoint to use:

RouteBuilder builder = new RouteBuilder() {
    public void configure() {
        // using dead letter channel with a seda queue for errors
        errorHandler(deadLetterChannel("seda:errors"));


        // here is our route
        from("seda:a").to("seda:b");
    }
};

Logging Error Handler

The logging error handler will log (by default at ERROR level) whenever an uncaught exception is thrown. The logging category, logger and level may all be defined in the builder.

errorHandler(loggingErrorHandler("mylogger.name").level(LoggingLevel.INFO));

This would create an error handler which logs exceptions using the category mylogger.name and uses the level INFO for all log messages created.

from("seda:a").errorHandler(loggingErrorHandler("mylogger.name").level(LoggingLevel.DEBUG)).to("seda:b");

Loggers may also be defined for specific routes.

No Error Handler

The no error handler is to be used for disabling error handling.

errorHandler(noErrorHandler());

TransactionErrorHandler new in Camel 2.0

The TransactionErrorHandler is the new default error handler in Camel 2.0 for transacted routes. It only supports a limited set of features such as catching exception and using the Exception Clause. It does not support redelivery, delays or the likes. It will propagate exceptions back to the original caller. It does not have any dead letter queue.

If you have marked a route as transacted using the transacted DSL then Camel will automatic use a TransactionErrorHandler. It will try to lookup the global/per route configured error handler and use it if its a TransactionErrorHandlerBuilder instance. If not Camel will automatic create a temporary TransactionErrorHandler that overrules the default error handler. This is convention over configuration.

Features support by various Error Handlers

In Camel 1.x the TransactionErrorHandler only supports the all scopes feature. In Camel 2.0 we have redone it to be based on the same core class as the DefaultErrorHandler and hence why it supports the same feature set as this.

Here is a breakdown of which features is supported by the Error Handler(s):

Feature	Supported by the following Error Handler
all scopes	DefaultErrorHandler, TransactionErrorHandler, Dead Letter Channel
onException	DefaultErrorHandler, TransactionErrorHandler, Dead Letter Channel
onWhen	DefaultErrorHandler, TransactionErrorHandler, Dead Letter Channel
handled	DefaultErrorHandler, TransactionErrorHandler, Dead Letter Channel
Custom ExceptionPolicy	DefaultErrorHandler, TransactionErrorHandler, Dead Letter Channel
useOriginalBody	DefaultErrorHandler, TransactionErrorHandler, Dead Letter Channel
retryUntil	DefaultErrorHandler, TransactionErrorHandler, Dead Letter Channel
onRedelivery	DefaultErrorHandler, TransactionErrorHandler, Dead Letter Channel
RedeliveryPolicy	DefaultErrorHandler, TransactionErrorHandler, Dead Letter Channel
dead letter queue	Dead Letter Channel

See Exception Clause documentation for documentation of some of the features above.

Scopes

The error handler is scoped as either

global
per route

The following example shows how you can register a global error handler (in this case using the logging handler)

RouteBuilder builder = new RouteBuilder() {
    public void configure() {
        // use logging error handler
        errorHandler(loggingErrorHandler("com.mycompany.foo"));

        // here is our regular route
        from("seda:a").to("seda:b");
    }
};

The following example shows how you can register a route specific error handler; the customized logging handler is only registered for the route from Endpoint seda:a

RouteBuilder builder = new RouteBuilder() {
    public void configure() {
        // this route is using a nested logging error handler
        from("seda:a")
            // here we configure the logging error handler
            .errorHandler(loggingErrorHandler("com.mycompany.foo"))
            // and we continue with the routing here
            .to("seda:b");

        // this route will use the default error handler (DeadLetterChannel)
        from("seda:b").to("seda:c");
    }
};

Spring based configuration

Available as of Camel 1.4

Java DSL vs. Spring DSL

The error handler is configured a bit differently in Java DSL and Spring DSL. Spring DSL relies more on standard Spring bean configuration whereas Java DSL uses fluent builders.

In Camel 1.4 the error handler can be configured as a spring bean and scoped in:

global (the camelContext tag)
per route (the route tag)
or per policy (the policy/transacted tag)

The error handler is configured with the errorHandlerRef attribute.

Error Handler Hierarchy

The error handlers is inherited, so if you only have set a global error handler then its use everywhere. But you can override this in a route and use another error handler.

Spring based configuration sample

In this sample we configure a Dead Letter Channel on the route that should redeliver at most 3 times and use a little delay before retrying.
First we configure the reference to myDeadLetterErrorHandler using the errorHandlerRef attribute on the route tag.

  <camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
      <template id="myTemplate"/>
<!-- set the errorHandlerRef to our DeadLetterChannel, this applies for this route only -->
      <route errorHandlerRef="myDeadLetterErrorHandler">
          <from uri="direct:in"/>
          <process ref="myFailureProcessor"/>
          <to uri="mock:result"/>
      </route>
  </camelContext>

Then we configure myDeadLetterErrorHandler that is our Dead Letter Channel. This configuration is standard Spring using the bean element.
And finally we have another spring bean for the redelivery policy where we can configure the options for how many times to redeliver, delays etc.

   <!-- here we configure our DeadLetterChannel -->
<bean id="myDeadLetterErrorHandler" class="org.apache.camel.builder.DeadLetterChannelBuilder">
    <!-- exchanges is routed to mock:dead in cased redelivery failed -->
       <property name="deadLetterUri" value="mock:dead"/>
	<!-- reference the redelivery policy to use -->
       <property name="redeliveryPolicy" ref="myRedeliveryPolicyConfig"/>
   </bean>

   <!-- here we set the redelivery settings -->
<bean id="myRedeliveryPolicyConfig" class="org.apache.camel.processor.RedeliveryPolicy">
    <!-- try redelivery at most 3 times, after that the exchange is dead and its routed to the mock:dead endpoint -->
       <property name="maximumRedeliveries" value="3"/>
	<!-- delay 250ms before redelivery -->
       <property name="redeliveryDelay" value="250"/>
   </bean>

From Camel 2.3.0, camel provides a customer bean configuration for the Error Handler, you can find the examples here.

<errorHandler id="loggingErrorHandler" xmlns="http://camel.apache.org/schema/spring" type="LoggingErrorHandler" level="INFO" />

<!-- If don't specify type attribute, the type value will be set to DefaultErrorHandler -->
<errorHandler id="errorHandler" xmlns="http://camel.apache.org/schema/spring" />

<!-- You can define the redeliveryPolicy inside of the errorHandler -->
<camel:errorHandler id="defaultErrorHandler" type="DefaultErrorHandler">
   <camel:redeliveryPolicy maximumRedeliveries="2" redeliveryDelay="0" logStackTrace="false" />
</camel:errorHandler>

<camel:errorHandler id="deadLetterErrorHandler" type="DeadLetterChannel" deadLetterUri="log:dead">
   <camel:redeliveryPolicy maximumRedeliveries="2" redeliveryDelay="1000" logHandled="true" />
</camel:errorHandler>

<bean id="myErrorProcessor" class="org.apache.camel.spring.handler.MyErrorProcessor"/>

<camel:errorHandler id="transactionErrorHandler" type="TransactionErrorHandler" transactionTemplateRef="PROPAGATION_REQUIRED"  class="code-quote">"myErrorProcessor" />

<!-- You can also define the errorHandler inside the camelContext -->
<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
	<errorHandler id="noErrorHandler" type="NoErrorHandler"/>
</camelContext>

Using the transactional error handler

The transactional error handler is introduced in Camel 1.4 and is based on spring transaction. This requires the usage of the camel-spring component.
See Transactional Client that has many samples for how to use and transactional behavior and configuration with this error handler.

[CONF] Apache Camel > Error Handler

Error Handler

Page edited by willem jiang

Error Handler

Non transacted

Transacted

Short Summary of the provided Error Handlers

DefaultErrorHandler new in Camel 2.0

Dead Letter Channel

Logging Error Handler

No Error Handler

TransactionErrorHandler new in Camel 2.0

Features support by various Error Handlers

Scopes

Spring based configuration

Spring based configuration sample

Using the transactional error handler

See also

Reply via email to