blob: b9e428178684a015ecb1711c8b1641d5d9d7dc2d [file] [log] [blame]
[[ErrorHandler-ErrorHandler]]
Error Handler
~~~~~~~~~~~~~
Camel supports pluggable
http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/processor/ErrorHandler.html[ErrorHandler]
strategies to deal with errors processing an
link:event-driven-consumer.html[Event Driven Consumer]. An alternative
is to specify the error handling directly in the link:dsl.html[DSL]
using the link:exception-clause.html[Exception Clause].
For introduction and background material see
link:error-handling-in-camel.html[Error handling in Camel].
*Exception Clause*
Using link:error-handler.html[Error Handler] combined with
link:exception-clause.html[Exception Clause] is a very powerful
combination. We encourage end-users to use this combination in your
error handling strategies. See samples and
link:exception-clause.html[Exception Clause].
*Using try ... catch ... finally*
Related to error handling is the link:try-catch-finally.html[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:
[[ErrorHandler-Nontransacted]]
Non transacted
++++++++++++++
* link:defaulterrorhandler.html[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.
* link:dead-letter-channel.html[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
[[ErrorHandler-Transacted]]
Transacted
++++++++++
* link:transactionerrorhandler.html[TransactionErrorHandler] is the
default error handler in Camel for transacted routes. See the
link:transactional-client.html[Transactional Client] EIP pattern.
These error handlers can be applied in the link:dsl.html[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 link:routebuilder.html[RouteBuilder]
[[ErrorHandler-ShortSummaryoftheprovidedErrorHandlers]]
Short Summary of the provided Error Handlers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[[ErrorHandler-DefaultErrorHandlerhttps://cwiki.apache.org/confluence/pages/viewpage.action?pageId=113880]]
link:defaulterrorhandler.html[DefaultErrorHandler]
++++++++++++++++++++++++++++++++++++++++++++++++++
The link:defaulterrorhandler.html[DefaultErrorHandler] is the default
error handler in Camel. Unlike link:dead-letter-channel.html[Dead Letter
Channel] it does not have any dead letter queue, and do *not* handle
exceptions by default.
[[ErrorHandler-DeadLetterChannelhttps://cwiki.apache.org/confluence/pages/viewpage.action?pageId=49482]]
link:dead-letter-channel.html[Dead Letter Channel]
++++++++++++++++++++++++++++++++++++++++++++++++++
The link:dead-letter-channel.html[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 in Spring DSL
[source,xml]
-----------------------------------------------------------------------------------------------------
<bean id="deadLetterErrorHandler" class="org.apache.camel.builder.DeadLetterChannelBuilder">
<property name="deadLetterUri" value="log:dead"/>
</bean>
<camelContext errorHandlerRef="deadLetterErrorHandler" xmlns="http://camel.apache.org/schema/spring">
...
</camelContext>
-----------------------------------------------------------------------------------------------------
or also from *Camel 2.3.0 onwards*
[source,xml]
--------------------------------------------------------------------------------------------------
<camel:errorHandler id="deadLetterErrorHandler" type="DeadLetterChannel" deadLetterUri="log:dead">
<camel:camelContext errorHandlerRef="deadLetterErrorHandler">
...
</camel:camelContext>
--------------------------------------------------------------------------------------------------
[[ErrorHandler-LoggingErrorHandler]]
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.
[source,java]
----------------------------------------------------------------------------
errorHandler(loggingErrorHandler("mylogger.name").level(LoggingLevel.INFO));
----------------------------------------------------------------------------
or in Spring DSL
[source,xml]
--------------------------------------------------------------------------------------------------
<bean id="loggingErrorHandler" class="org.apache.camel.builder.LoggingErrorHandler">
<property name="logName" value="mylogger.name"/>
<property name="level" value="DEBUG"/>
</bean>
<camelContext errorHandlerRef="loggingErrorHandler" xmlns="http://camel.apache.org/schema/spring">
...
</camelContext>
--------------------------------------------------------------------------------------------------
or also from *Camel 2.3.0 onwards*
[source,xml]
---------------------------------------------------------------------------------------------------------------
<camel:errorHandler id="loggingErrorHandler" type="LoggingErrorHandler" logName="mylogger.name" level="DEBUG"/>
<camel:camelContext errorHandlerRef="loggingErrorHandler">
...
</camel:camelContext>
---------------------------------------------------------------------------------------------------------------
This would create an error handler which logs exceptions using the
category mylogger.name and uses the level INFO for all log messages
created.
[source,java]
---------------------------------------------------------------------------------------------------------
from("seda:a").errorHandler(loggingErrorHandler("mylogger.name").level(LoggingLevel.DEBUG)).to("seda:b");
---------------------------------------------------------------------------------------------------------
Loggers may also be defined for specific routes.
[[ErrorHandler-NoErrorHandler]]
No Error Handler
++++++++++++++++
The no error handler is to be used for disabling error handling.
[source,java]
-------------------------------
errorHandler(noErrorHandler());
-------------------------------
or in Spring DSL
[source,xml]
---------------------------------------------------------------------------------------------
<bean id="noErrorHandler" class="org.apache.camel.builder.NoErrorHandlerBuilder"/>
<camelContext errorHandlerRef="noErrorHandler" xmlns="http://camel.apache.org/schema/spring">
...
</camelContext>
---------------------------------------------------------------------------------------------
or also from *Camel 2.3.0 onwards*
[source,xml]
---------------------------------------------------------------
<camel:errorHandler id="noErrorHandler" type="NoErrorHandler"/>
<camel:camelContext errorHandlerRef="noErrorHandler">
...
</camel:camelContext>
---------------------------------------------------------------
[[ErrorHandler]]
link:transactionerrorhandler.html[TransactionErrorHandler]
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
The link:transactionerrorhandler.html[TransactionErrorHandler] is the
default error handler in Camel for transacted routes.
TIP:If you have marked a route as transacted using the *transacted* DSL then
Camel will automatic use a
link:transactionerrorhandler.html[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
link:transactionerrorhandler.html[TransactionErrorHandler] that
overrules the default error handler. This is convention over
configuration.
[[ErrorHandler-Featuressupportbyvariouss]]
Features support by various link:error-handler.html[Error Handler]s
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Here is a breakdown of which features is supported by the
link:error-handler.html[Error Handler](s):
[width="100%",cols="20%,80%",options="header",]
|=======================================================================
Feature |Supported by the following link:error-handler.html[Error Handler]
|all scopes |link:defaulterrorhandler.html[DefaultErrorHandler],
link:transactionerrorhandler.html[TransactionErrorHandler],
link:dead-letter-channel.html[Dead Letter Channel]
|onException |link:defaulterrorhandler.html[DefaultErrorHandler],
link:transactionerrorhandler.html[TransactionErrorHandler],
link:dead-letter-channel.html[Dead Letter Channel]
|onWhen |link:defaulterrorhandler.html[DefaultErrorHandler],
link:transactionerrorhandler.html[TransactionErrorHandler],
link:dead-letter-channel.html[Dead Letter Channel]
|continued |link:defaulterrorhandler.html[DefaultErrorHandler],
link:transactionerrorhandler.html[TransactionErrorHandler],
link:dead-letter-channel.html[Dead Letter Channel]
|handled |link:defaulterrorhandler.html[DefaultErrorHandler],
link:transactionerrorhandler.html[TransactionErrorHandler],
link:dead-letter-channel.html[Dead Letter Channel]
|Custom ExceptionPolicy |link:defaulterrorhandler.html[DefaultErrorHandler],
link:transactionerrorhandler.html[TransactionErrorHandler],
link:dead-letter-channel.html[Dead Letter Channel]
|useOriginalBody |link:defaulterrorhandler.html[DefaultErrorHandler],
link:transactionerrorhandler.html[TransactionErrorHandler],
link:dead-letter-channel.html[Dead Letter Channel]
|retryWhile |link:defaulterrorhandler.html[DefaultErrorHandler],
link:transactionerrorhandler.html[TransactionErrorHandler],
link:dead-letter-channel.html[Dead Letter Channel]
|onRedelivery |link:defaulterrorhandler.html[DefaultErrorHandler],
link:transactionerrorhandler.html[TransactionErrorHandler],
link:dead-letter-channel.html[Dead Letter Channel]
|RedeliveryPolicy |link:defaulterrorhandler.html[DefaultErrorHandler],
link:transactionerrorhandler.html[TransactionErrorHandler],
link:dead-letter-channel.html[Dead Letter Channel]
|asyncDelayedRedelivery |link:defaulterrorhandler.html[DefaultErrorHandler],
link:transactionerrorhandler.html[TransactionErrorHandler],
link:dead-letter-channel.html[Dead Letter Channel]
|redeliverWhileStopping |link:defaulterrorhandler.html[DefaultErrorHandler],
link:transactionerrorhandler.html[TransactionErrorHandler],
link:dead-letter-channel.html[Dead Letter Channel]
|dead letter queue |link:dead-letter-channel.html[Dead Letter Channel]
|onPrepareFailure |link:defaulterrorhandler.html[DefaultErrorHandler],
link:dead-letter-channel.html[Dead Letter Channel]
|=======================================================================
See link:exception-clause.html[Exception Clause] documentation for
documentation of some of the features above.
[[ErrorHandler-Scopes]]
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)
[source,java]
---------------------------------------------------------------
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 link:endpoint.html[Endpoint] *seda:a*
[source,java]
---------------------------------------------------------------
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");
}
};
---------------------------------------------------------------
[[ErrorHandler-Springbasedconfiguration]]
Spring based configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^
*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.
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.
TIP:*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.
[[ErrorHandler-Springbasedconfigurationsample]]
Spring based configuration sample
+++++++++++++++++++++++++++++++++
In this sample we configure a link:dead-letter-channel.html[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.
Then we configure *myDeadLetterErrorHandler* that is our
link:dead-letter-channel.html[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.
From Camel 2.3.0, camel provides a customer bean configuration for the
Error Handler, you can find the examples here.
[[ErrorHandler-Usingthetransactionalerrorhandler]]
Using the transactional error handler
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The transactional error handler is based on spring transaction. This
requires the usage of the camel-spring component. +
See link:transactional-client.html[Transactional Client] that has many
samples for how to use and transactional behavior and configuration with
this error handler.
[[ErrorHandler-Seealso]]
See also
^^^^^^^^
* link:error-handling-in-camel.html[Error handling in Camel] for
introduction and background material on error handling in Camel
* link:dead-letter-channel.html[Dead Letter Channel] for the dead letter
error handler
* link:defaulterrorhandler.html[DefaultErrorHandler] for the default
error handler in Camel
* link:transactionerrorhandler.html[TransactionErrorHandler] for the
default error handler for transacted routes
* link:transactional-client.html[Transactional Client] for transactional
behavior
* link:exception-clause.html[Exception Clause] as it supports *handling*
thrown exceptions
* link:try-catch-finally.html[Try Catch Finally] for try ... catch ...
finally as DSL you can use in the routing