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
+

Reply via email to