Repository: camel Updated Branches: refs/heads/master ffb006008 -> bd6f1d284
Added error-handler docs to Gitbook Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/3002f8d3 Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/3002f8d3 Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/3002f8d3 Branch: refs/heads/master Commit: 3002f8d3effb0bbaf6a0a1bd33f9ac1b474fa968 Parents: ffb0060 Author: Andrea Cosentino <[email protected]> Authored: Sun Jul 31 11:08:56 2016 +0200 Committer: Andrea Cosentino <[email protected]> Committed: Sun Jul 31 11:08:56 2016 +0200 ---------------------------------------------------------------------- docs/user-manual/en/SUMMARY.md | 3 +- docs/user-manual/en/error-handler.adoc | 390 ++++++++++++++++++++++++++++ 2 files changed, 391 insertions(+), 2 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/3002f8d3/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index d621211..0ecc6f4 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -30,6 +30,7 @@ * [Scala DSL Supported Languages](scala-dsl-supported-languages.adoc) * [Annotation DSL](bean-integration.adoc) * [Endpoint](endpoint.adoc) + * [Error Handler](error-handler.adoc) * [Exchange](exchange.adoc) * [Exchange Pattern](exchange-pattern.adoc) * [Intercept](intercept.adoc) @@ -38,8 +39,6 @@ * [Scala DSL](scala-dsl.adoc) <!-- - * [Camel-Core](camel-core.adoc) - * [Error Handler](.adoc) * [Expression](.adoc) * [Injector](.adoc) * [Inversion Of Control With Smart Defaults](.adoc) http://git-wip-us.apache.org/repos/asf/camel/blob/3002f8d3/docs/user-manual/en/error-handler.adoc ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/error-handler.adoc b/docs/user-manual/en/error-handler.adoc new file mode 100644 index 0000000..b9e4281 --- /dev/null +++ b/docs/user-manual/en/error-handler.adoc @@ -0,0 +1,390 @@ +[[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 +
