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.Some current implementations include
For introduction and background material see Error handling in Camel.
...
Using Error Handler combined with Exception Clause is a very powerful combination. We encourage end-users to use this combination in your error handling strategies. See samples and Exception Clause.
...
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. This error handler does not support a dead 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 exceptionsNoErrorHandler
for no error handling
Transacted:
- TransactionErrorHandler is the default error handler in Camel for transacted routesTransaction for transactional error handling (Spring based). See the Transactional Client EIP pattern.
Note | ||
---|---|---|
| ||
If the route is transactional then the Dead Letter Channel is disabled. The |
Tip | ||
---|---|---|
| ||
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. |
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
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
Short Summary of the Provided Error Handlers
DefaultErrorHandler
The DefaultErrorHandler is the default error handler in Camel. 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 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:
...
or also from Camel 2.3.0:
...
The LoggingErrorHandler
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.
...
or in Spring DSL:
...
or also from Camel 2.3.0:
...
This would create an error handler which logs exceptions using the category mylogger.name
and uses the level INFO
for all log messages created.
...
Loggers may also be defined for specific routes.
The NoErrorHandler
The no error handler is to be used for disabling error handling.
...
or in Spring DSL:
...
or also from Camel 2.3.0:
...
TransactionErrorHandler
The TransactionErrorHandler is the default error handler in Camel for transacted routes.
...
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
Here is a breakdown of which features is supported by the Error Handler(s):
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)
...
...
...
Setting error handlers on a specific route
The following example shows how you can register a local route specific error handler; the customized logging handler is only registered for the route from Endpoint seda:a
...
...
Spring Based Configuration
...
Spring based configuration
...
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.
The In Camel 1.4 the error handler can be configured as a spring bean and referenced as eitherscoped 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.
...
...
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 to myDeadLetterErrorHandler
using the errorHandlerRef
attribute on the route
tag.
...
...
...
Then we configure configure myDeadLetterErrorHandler
that is our Dead Letter Channel. This configuration is standard Spring using the bean element.
And finally Finally, we have another spring bean for the redelivery policy where we can configure the options for how many times to redeliver, delays etc.
...
...
...
Default Error Handler
The default error handler is the Dead Letter Channel which is automatically configured for you. You can then configure the specific dead letter endpoint to use either for an entire rule base or a specific rule as shown above. For example
Wiki Markup |
---|
{snippet:id=e3|lang=java|url=activemq/camel/trunk/camel-core/src/test/java/org/apache/camel/builder/ErrorHandlerTest.java} |
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.
Code Block |
---|
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.
Code Block |
---|
from("seda:a").errorHandler(loggingErrorHandler("mylogger.name").level(LoggingLevel.DEBUG)).to("seda:b");
|
Loggers may also be defined for specific routes.
Overriding default behavior
You can also configure the RedeliveryPolicy as this example shows
Wiki Markup |
---|
{snippet:id=e4|lang=java|url=activemq/camel/trunk/camel-core/src/test/java/org/apache/camel/builder/ErrorHandlerTest.java} |
As of Camel 1.4 you can configure the ExceptionPolicyStrategy as this example shows. Notice that we use Exception Clause to handle known exceptions being thrown.
Wiki Markup |
---|
{snippet:id=e1|lang=java|url=activemq/camel/trunk/camel-core/src/test/java/org/apache/camel/processor/exceptionpolicy/CustomExceptionPolicyStrategyTest.java} |
Using our own strategy MyPolicy we can change the default behavior of Camel with our own code to resolve which ExceptionType from above should be handling the given thrown exception.
...
From Camel 2.3.0, camel provides a customer bean configuration for the Error Handler, you can find the examples here.
...
...
...
...
Using
...
the TransactionalErrorHandler
The TransactionalErrorHandler
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.
See also
...
- Error handling in Camel for introduction and background material on error handling in Camel
- Dead Letter Channel for the dead letter error handler
- DefaultErrorHandler for the default error handler in Camel
- TransactionErrorHandler for the default error handler for transacted routes
- Transactional Client for transactional behavior
...
- Exception Clause as it supports handling thrown exceptions
- Try Catch Finally for try ... catch ... finally as DSL you can use in the routing