This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new e1948e5 CAMEL-16861: Cleanup and update EIP docs
e1948e5 is described below
commit e1948e5ba4631676c08f77578e6a2773ebc7c0b2
Author: Claus Ibsen <claus.ib...@gmail.com>
AuthorDate: Fri Sep 17 10:30:12 2021 +0200
CAMEL-16861: Cleanup and update EIP docs
---
.../modules/eips/pages/dead-letter-channel.adoc | 669 ++++++++++-----------
1 file changed, 320 insertions(+), 349 deletions(-)
diff --git
a/core/camel-core-engine/src/main/docs/modules/eips/pages/dead-letter-channel.adoc
b/core/camel-core-engine/src/main/docs/modules/eips/pages/dead-letter-channel.adoc
index 4c615cc..7c1131b 100644
---
a/core/camel-core-engine/src/main/docs/modules/eips/pages/dead-letter-channel.adoc
+++
b/core/camel-core-engine/src/main/docs/modules/eips/pages/dead-letter-channel.adoc
@@ -5,74 +5,137 @@ Camel supports the
http://www.enterpriseintegrationpatterns.com/DeadLetterChannel.html[Dead
Letter Channel] from the xref:enterprise-integration-patterns.adoc[EIP
patterns] using the
-https://www.javadoc.io/doc/org.apache.camel/camel-base/current/org/apache/camel/processor/errorhandler/DeadLetterChannel.html[DeadLetterChannel]
+https://www.javadoc.io/doc/org.apache.camel/camel-core-processor/current/org/apache/camel/processor/errorhandler/DeadLetterChannel.html[DeadLetterChannel]
processor which is an xref:latest@manual:ROOT:error-handler.adoc[Error
Handler].
image::eip/DeadLetterChannelSolution.gif[image]
-The Dead Letter Channel lets you control behaviors including redelivery,
-whether to propagate the thrown Exception to the caller (the *handled*
-option), and where the (failed) Exchange should now be routed to.
-
-The Dead Letter Channel is also by default configured to not be verbose
-in the logs, so when a message is handled and moved to the dead letter
-endpoint, then there is nothing logged. If you want some level of
-logging you can use the various options on the redelivery policy / dead
-letter channel to configure this. For example if you want the message
-history then set logExhaustedMessageHistory=true (and logHandled=true
-for Camel 2.15.x or older).
-
-When the DeadLetterChannel moves a message to the dead letter endpoint,
-any new Exception thrown is by default handled by the dead letter
-channel as well. This ensures that the DeadLetterChannel will always
-succeed. From *Camel 2.15* onwards this behavior can be changed by
-setting the option deadLetterHandleNewException=false. Then if a new
-Exception is thrown, then the dead letter channel will fail and
-propagate back that new Exception (which is the behavior of the default
-error handler). When a new Exception occurs then the dead letter channel
-logs this at WARN level. This can be turned off by setting
-logNewException=false.
-
-TIP: *Difference between Dead Letter Channel and Default Error
-Handler* The Default Error Handler does very little: it ends the Exchange
-immediately and propagates the thrown Exception back to the caller.
-
-[[deadLetterChannel-Redelivery]]
-== Redelivery
-
-It is common for a temporary outage or database deadlock to cause a
-message to fail to process; but the chances are if its tried a few more
-times with some time delay then it will complete fine. So we typically
-wish to use some kind of redelivery policy to decide how many times to
-try redeliver a message and how long to wait before redelivery attempts.
+The Dead Letter Channel is an xref:latest@manual:ROOT:error-handler.adoc[Error
Handler]
+that implements the principles from the Dead Letter Channel EIP.
+From the illustration above we can see the pattern is that if a message cannot
be processed or fails during sending, it should be moved to a dead letter queue.
+The dead letter queue, is based on a Camel
+xref:message-endpoint.adoc[Endpoint], allowing you to use any of the many
Camel components, such as a file system, database, or a log.
+
+The Dead Letter Channel is similar to the default error handler, but with the
following differences:
+
+- The dead letter channel is the only error handler that supports moving
failed messages to a dedicated error queue, known as the dead letter queue (is
a Camel endpoint).
+- Unlike the default error handler, the dead letter channel will, by default,
handle exceptions and move the failed messages to the dead letter queue.
+- The dead letter channel is by default configured to not log any activity
when it handles exceptions.
+- The dead letter channel supports using the original input message when a
message is moved to the dead letter queue.
+
+== Using Dead Letter Error Handler
+
+When using the dead letter channel error handler, you must configure the dead
letter queue as an endpoint, so the handler knows where to move the failed
messages.
+This is done a bit differently in the Java DSL and XML DSL.
+
+For example, here’s how to log the message at `ERROR` level in Java DSL:
+
+[source,java]
+----
+errorHandler(deadLetterChannel("log:dead?level=ERROR"));
+----
+
+And in Spring XML
+
+[source,xml]
+----
+<errorHandler id="myErrorHandler" type="DeadLetterChannel"
+ deadLetterUri="log:dead?level=ERROR"/>
+----
+
+Pay attention to Spring XML DSL, the type attribute is used to declare which
error handler to use, here its `DeadLetterChannel`.
+And in XML the `<errorHandler>` must be configured with an id.
+The id must then be enabled on either the `<camelContext>` (global scope), or
per route that should use this error handler.
+
+The following listing is an equivalent of the prior Java DSL listing:
+
+[source,xml]
+----
+<camelContext errorHandlerRef="myErrorHandler">
+ <errorHandler id="myErrorHandler" type="DeadLetterChannel"
+ deadLetterUri="log:dead?level=ERROR"/>
+ <route>
+ <from uri="direct:newOrder"/>
+ <bean ref="orderService" method="validate"/>
+ <bean ref="orderService" method="store"/>
+ </route>
+</camelContext>
+----
+
+Notice how we have enabled the error handler on the `<camelContext>` via
`errorHandlerRef`
+which means this error handler is used globally. You can override this per
route, and have
+individual routes used another error handler.
+
+NOTE: The DSLs is planned to be improved in the near future to have a unified
+way of configuring error handling across all DSLs, with
xref:latest@manual:ROOT:route-configuration.adoc[Route Configuration].
+When fully implemented then configuring error handler in Java and XML DSL
would be much more similar than currently.
+
+=== Redelivery
+
+It is common for a temporary outage or database deadlock to cause a message to
fail to process; but the chances are if its tried a few more times with some
time delay then it will complete fine.
+So we typically wish to use some kind of redelivery policy to decide how many
times to try to redeliver a message and how long to wait before redelivery
attempts.
The
https://www.javadoc.io/doc/org.apache.camel/camel-base/current/org/apache/camel/processor/errorhandler/RedeliveryPolicy.html[RedeliveryPolicy]
-defines how the message is to be redelivered. You can customize things
-like
+defines how the message is to be redelivered.
+You can customize things like:
-* how many times a message is attempted to be redelivered before it is
-considered a failure and sent to the dead letter channel
+* how many times a message is attempted to be redelivered before it is
considered a failure and sent to the dead letter channel
* the initial redelivery timeout
-* whether or not exponential backoff is used (i.e. the time between
-retries increases using a backoff multiplier)
-* whether to use collision avoidance to add some randomness to the
-timings
-* delay pattern (see below for details)
-* *Camel 2.11:* whether to allow redelivery during stopping/shutdown
+* using exponential backoff (i.e. the time between retries increases using a
backoff multiplier)
+* whether to use collision avoidance to add some randomness to the timings
+* delay pattern
+* whether to allow redelivery during stopping/shutdown
+
+Only when all redelivery attempts have failed then the message is moved to the
dead letter queue.
+
+=== Redelivery default values
+
+Redelivery is disabled by default.
+
+The default redeliver policy will use the following values:
+
+* maximumRedeliveries = 0
+* redeliveryDelay = 1000L (1 second)
+* maximumRedeliveryDelay = 60 * 1000L (60 seconds)
+* And the exponential backoff and collision avoidance is turned off.
+* The retriesExhaustedLogLevel are set to LoggingLevel.ERROR
+* The retryAttemptedLogLevel are set to LoggingLevel.DEBUG
+* Stack traces is logged for exhausted messages
+* Handled exceptions is not logged
+* allowRedeliveryWhileStopping is true
+* logExhaustedMessageHistory is false
+* logExhaustedMessageBody is disabled by default to avoid logging sensitive
message body/header details.
+ If this option is true, then logExhaustedMessageHistory must also be true.
+
+The maximum redeliver delay ensures that a delay is never longer than the
value, default 1 minute.
+This can happen if you turn on the exponential backoff.
+
+The maximum redeliveries are the number of redelivery attempts.
+Setting the maximumRedeliveries to a negative value such as -1 will then
always redelivery (unlimited).
+Setting the maximumRedeliveries to 0 will disable any redelivery attempt.
+
+Camel will log delivery failures at the DEBUG logging level by default.
+You can change this by specifying retriesExhaustedLogLevel and/or
retryAttemptedLogLevel.
+
+You can turn logging of stack traces on/off.
+If turned off Camel will still log the redelivery attempt, it's just much less
verbose.
+
+There are more options for fine-tuned logging configurations which you can
find at
https://www.javadoc.io/doc/org.apache.camel/camel-core-processor/current/org/apache/camel/processor/errorhandler/RedeliveryPolicy.html[RedeliveryPolicy].
+
+
+=== What happens when an exception is thrown during sending to the dead letter
queue
-Once all attempts at redelivering the message fails then the message is
-forwarded to the dead letter queue.
+When the Dead Letter Channel moves a message to the dead letter endpoint, and
a new Exception is thrown, then the new caused exception is logged at WARN
level (can be turned off by setting `logNewException` to false) and Camel stops
processing the message.
+This ensures that the Dead LetterChannel will always succeed.
-[[deadLetterChannel-AboutmovingExchangetodeadletterqueueandusinghandled]]
-== About moving Exchange to dead letter queue and using handled
+If you do not want this behaviour you can configure
`deadLetterHandleNewException` to false, which then causes the dead letter
channel to fail and propagate back the new Exception, which causes Camel to
fail processing the message.
+
+=== What happens when an Exchange is moved to the dead letter queue
When all attempts of redelivery have failed the
-xref:latest@manual:ROOT:exchange.adoc[Exchange] is moved to the dead letter
queue (the dead
-letter endpoint). The exchange is then complete and from the client
-point of view it was processed. As such the
-xref:dead-letter-channel.adoc[Dead Letter Channel] have handled the
-xref:latest@manual:ROOT:exchange.adoc[Exchange].
+xref:latest@manual:ROOT:exchange.adoc[Exchange] is moved to the dead letter
queue.
+The exchange is then complete, and from the client point of view, the message
is done being processed.
For instance configuring the dead letter channel as:
@@ -86,34 +149,19 @@ And in XML:
[source,xml]
----
-<route errorHandlerRef="myDeadLetterErrorHandler">
- ...
-</route>
-
-<bean id="myDeadLetterErrorHandler"
class="org.apache.camel.builder.DeadLetterChannelBuilder">
- <property name="deadLetterUri" value="jms:queue:dead"/>
- <property name="redeliveryPolicy" ref="myRedeliveryPolicyConfig"/>
-</bean>
-
-<bean id="myRedeliveryPolicyConfig"
class="org.apache.camel.processor.RedeliveryPolicy">
- <property name="maximumRedeliveries" value="3"/>
- <property name="redeliveryDelay" value="5000"/>
-</bean>
+<errorHandler id="myErrorHandler" type="DeadLetterChannel"
+ deadLetterUri="jms:queue:dead">
+ <redeliveryPolicy maximumRedeliveries="3" redeliveryDelay="5000"/>
+</errorHandler>
----
-The xref:dead-letter-channel.adoc[Dead Letter Channel] above will clear
-the caused exception (`setException(null)`), by moving the caused
-exception to a property on the
xref:latest@manual:ROOT:exchange.adoc[Exchange], with the
-key `Exchange.EXCEPTION_CAUGHT`. Then the
xref:latest@manual:ROOT:exchange.adoc[Exchange]
-is moved to the `"jms:queue:dead"` destination and the client will not
-notice the failure.
+The Dead Letter error handler will clear the caused exception
(`setException(null)`), by moving the caused exception to a property on the
xref:latest@manual:ROOT:exchange.adoc[Exchange], with the key
`Exchange.EXCEPTION_CAUGHT`.
+Then the xref:latest@manual:ROOT:exchange.adoc[Exchange]
+is moved to the `jms:queue:dead` destination, and the client will not notice
the failure.
-[[deadLetterChannel-AboutmovingExchangetodeadletterqueueandusingtheoriginalmessage]]
-== Moving Exchange to dead letter queue and using the original message
+=== Moving the original message to the dead letter queue
-The option *useOriginalMessage* is used for routing the original input
-message instead of the current message that potentially is modified
-during routing.
+The option `useOriginalMessage` is used for routing the original input message
instead of the current message that potentially is modified during routing.
For instance if you have this route:
@@ -125,21 +173,21 @@ from("jms:queue:order:input")
.to("bean:handleOrder");
-----
-The route listen for JMS messages and validates, transforms and handle
-it. During this the xref:latest@manual:ROOT:exchange.adoc[Exchange] payload is
-transformed/modified. So in case something goes wrong and we want to
-move the message to another JMS destination, then we can configure our
-xref:dead-letter-channel.adoc[Dead Letter Channel] with the
-*useOriginalMessage* option. But when we move the
-xref:latest@manual:ROOT:exchange.adoc[Exchange] to this destination we do not
know in which
-state the message is in. Did the error happen in before the
-transformOrder or after? So to be sure we want to move the original
-input message we received from `jms:queue:order:input`. So we can do
-this by enabling the *useOriginalMessage* option as shown below:
+The route listen for JMS messages and validates, transforms and handle it.
+During this the xref:latest@manual:ROOT:exchange.adoc[Exchange] payload is
transformed/modified in the various bean stages.
+
+Now suppose that if an exception is thrown we want to move the message to the
dead letter queue.
+However the message that is moved to the dead letter queue (by default) is the
current message.
+Suppose at one time there is an exception in the validateOrder, and another
time an exception thrown
+by transformOrder, and yet also in handleOrder. In all these different
situations the message may be changed.
+
+By enabling `useOriginalMessage` on the dead letter channel, then the message
that is moved to the dead letter queue,
+would be the original incoming message.
[NOTE]
====
-There is also a *useOriginalBody* option.
+There is also a *useOriginalBody* option, which only keeps the original
message body, and does
+not change the message headers.
====
[source,java]
@@ -149,85 +197,137 @@ errorHandler(deadLetterChannel("jms:queue:dead")
.useOriginalMessage().maximumRedeliveries(5).redeliveryDelay(5000);
----
+And in XML, you set `useOriginalMessage=true` on the `<errorHandler>` as shown:
+
+[source,xml]
+----
+<errorHandler id="myErrorHandler" type="DeadLetterChannel"
useOriginalMessage="true"
+ deadLetterUri="jms:queue:dead">
+ <redeliveryPolicy maximumRedeliveries="5" redeliveryDelay="5000"/>
+</errorHandler>
+----
+
Then the messages routed to the `jms:queue:dead` is the original input.
-If we want to manually retry we can move the JMS message from the failed
-to the input queue, with no problem as the message is the same as the
-original we received.
+If we want to manually retry we can move the JMS message from the failed to
the input queue, with no problem as the message is the same as the original we
received.
-=== Boundary of original message
+==== Boundary of original message
-The original input means the input message that are bounded by the current
unit of work. An unit of work typically spans one route, or multiple routes if
they are connected
-using internal endpoints such as direct or seda. When messages are passed via
external
-endpoints such as JMS or HTT then the consumer will create a new unit of work,
with the
-message it received as input as the original input. Also some EIP patterns
such as splitter,
-multicast, will create a new unit of work boundary for the messages in their
sub-route
-(eg the splitted message); however these EIPs have an option named
shareUnitOfWork which
-allows to combine with the parent unit of work in regard to error handling and
therefore use
-the parent original message.
+The original input means the input message that are bounded by the current
unit of work.
+A unit of work typically spans one route, or multiple routes if they are
connected using internal endpoints such as direct or seda.
+When messages are passed via external endpoints such as JMS or HTT then the
consumer will create a new unit of work, with the message it received as input
as the original input.
+Also, some EIP patterns such as splitter, multicast, will create a new unit of
work boundary for the messages in
+their sub-route (i.e. the _splitted_ message); however these EIPs have an
option named `shareUnitOfWork` which allows
+combining with the parent unit of work and ends up usinguse the parent
original message.
-[[deadLetterChannel-OnRedelivery]]
-== OnRedelivery
-When xref:dead-letter-channel.adoc[Dead Letter Channel] is doing
-redeliver its possible to configure a
xref:latest@manual:ROOT:processor.adoc[Processor]
-that is executed just *before* every redelivery attempt. This can be
-used for the situations where you need to alter the message before its
-redelivered. See below for sample.
+=== Calling a processor before redelivery using OnRedelivery
-TIP: *onException and onRedeliver*
-We also support for per
xref:latest@manual:ROOT:exception-clause.adoc[*onException*] to set
-a *onRedeliver*. That means you can do special on redelivery for
-different exceptions, as opposed to onRedelivery set on
-xref:dead-letter-channel.adoc[Dead Letter Channel] can be viewed as a
-global scope.
+When the Dead Letter Channel is doing redeliver its possible to configure a
xref:latest@manual:ROOT:processor.adoc[Processor]
+that is executed just _before_ every redelivery attempt.
+This can be used for the situations where you need to alter the message before
its redelivered.
+For example in Java DSL you can do:
-[[deadLetterChannel-Redeliverydefaultvalues]]
-== Redelivery default values
+[source,java]
+----
+errorHandler(deadLetterChannel("jms:queue:dead")
+ .maximumRedeliveries(3)
+ .onRedeliver(new MyOnRedeliveryProcessor());
+----
-Redelivery is disabled by default.
+And in XML DSL, you specify a bean id via `onRedeliveryRef` on the
`<errorHandler>` as shown:
-The default redeliver policy will use the following values:
+[source,xml]
+----
+<bean id="myRedeliveryProcessor" class="com.foo.MyRedeliveryProcessor"/>
-* maximumRedeliveries=0
-* redeliveryDelay=1000L (1 second)
-* maximumRedeliveryDelay = 60 * 1000L (60 seconds)
-* And the exponential backoff and collision avoidance is turned off.
-* The retriesExhaustedLogLevel are set to LoggingLevel.ERROR
-* The retryAttemptedLogLevel are set to LoggingLevel.DEBUG
-* Stack traces is logged for exhausted messages
-* Handled exceptions is not logged
-* logExhaustedMessageHistory is true for default error handler, and
-false for dead letter channel.
-* logExhaustedMessageBody is disabled by default to avoid
-logging sensitive message body/header details. If this option is true,
-then logExhaustedMessageHistory must also be true.
-
-The maximum redeliver delay ensures that a delay is never longer than
-the value, default 1 minute. This can happen if you turn on the
-exponential backoff.
-
-The maximum redeliveries are the number of redelivery attempts. By
-default Camel will try to process the exchange 1 + 5 times. 1 time for
-the normal attempt and then 5 attempts as redeliveries.
-Setting the maximumRedeliveries to a negative value such as -1 will
-then always redelivery (unlimited). Setting the maximumRedeliveries to 0
-will disable any redelivery attempt.
+<errorHandler id="myErrorHandler" type="DeadLetterChannel"
onRedeliveryRef="myRedeliveryProcessor"
+ deadLetterUri="jms:queue:dead">
+ <redeliveryPolicy maximumRedeliveries="3"/>
+</errorHandler>
+----
-Camel will log delivery failures at the DEBUG logging level by default.
-You can change this by specifying retriesExhaustedLogLevel and/or
-retryAttemptedLogLevel.
+TIP: Camel also supports
xref:latest@manual:ROOT:exception-clause.adoc[onException] to use `onRedeliver`.
+This means you can do special on redelivery for different exceptions, as
opposed to `onRedelivery` set on
+Dead Letter Channel (or
xref:latest@manual:ROOT:defaulterrorhandler.adoc[Default Error Handler]) can be
viewed as global scoped.
+
+
+=== Calling a processor before sending message to the dead letter queue using
OnPrepareFailure
-You can turn logging of stack traces on/off. If turned off Camel will
-still log the redelivery attempt. Its just much less verbose.
+Before the exchange is sent to the dead letter queue, you can use `onPrepare`
to allow a custom `Processor` to prepare the exchange, such as adding
information why the Exchange failed.
-[[deadLetterChannel-RedeliverDelayPattern]]
-== Redeliver Delay Pattern
+For example the following processor adds a header with the exception message:
+
+[source,java]
+----
+public static class MyPrepareProcessor implements Processor {
+ @Override
+ public void process(Exchange exchange) throws Exception {
+ Exception cause = exchange.getProperty(Exchange.EXCEPTION_CAUGHT,
Exception.class);
+ exchange.getIn().setHeader("FailedBecause", cause.getMessage());
+ }
+}
+----
-Delay pattern is used as a single option to set a range pattern for
-delays. If used then the following options does not apply: (delay,
-backOffMultiplier, useExponentialBackOff, useCollisionAvoidance,
-maximumRedeliveryDelay).
+Then configure the error handler to use the processor as follows:
+
+[source,java]
+----
+errorHandler(deadLetterChannel("jms:dead").onPrepareFailure(new
MyPrepareProcessor()));
+----
+
+Configuring this from Spring XML is done with the `onPrepareFailureRef` to
refer to the processor as a `<bean>` as shown:
+
+[source,xml]
+----
+<bean id="myPrepare"
+
class="org.apache.camel.processor.DeadLetterChannelOnPrepareTest.MyPrepareProcessor"/>
+
+<errorHandler id="dlc" type="DeadLetterChannel" deadLetterUri="jms:dead"
onPrepareFailureRef="myPrepare"/>
+----
+
+=== Calling a processor when an exception occurred
+
+With the `onExceptionOccurred` you can call a custom processor right after an
exception was thrown,
+and the Dead Letter Channel is about to decide what to do (either to schedule
a redelivery, or move the message into the dead letter queue).
+
+In other words this happens right after the exception was thrown, where you
may want to do some custom logging, or something else.
+
+For example, you may have a `Processor` that does some special logging:
+
+[source,java]
+----
+public static class OnErrorLogger implements Processor {
+ @Override
+ public void process(Exchange exchange) throws Exception {
+ Exception cause = exchange.getProperty(Exchange.EXCEPTION_CAUGHT,
Exception.class);
+ String msg = "Something went wrong due to " + cause.getMessage();
+ // do some custom logging here
+ }
+}
+----
+
+You can then configure the Dead Letter Channel to use this as shown:
+
+[source,java]
+----
+errorHandler(deadLetterChannel("jms:dead").onExceptionOccurred(new
OnErrorLogger()));
+----
+
+Configuring this from Spring XML is done with the `onExceptionOccurredRef` to
refer to the processor as a `<bean>` as shown:
+
+[source,xml]
+----
+<bean id="myErrorLogger" class="com.foo.OnErrorLogger"/>
+
+<errorHandler id="dlc" type="DeadLetterChannel" deadLetterUri="jms:dead"
onExceptionOccurredRef="myErrorLogger"/>
+----
+
+
+=== Redeliver Delay Pattern
+
+Delay pattern is used as a single option to set a range pattern for delays.
+If used then the following options does not apply: (delay, backOffMultiplier,
useExponentialBackOff, useCollisionAvoidance, maximumRedeliveryDelay).
The idea is to set groups of ranges using the following syntax:
`limit:delay;limit 2:delay 2;limit 3:delay 3;...;limit N:delay N`
@@ -235,14 +335,15 @@ The idea is to set groups of ranges using the following
syntax:
Each group has two values separated with colon
* limit = upper limit
-* delay = delay in millis
-And the groups is again separated with semi colon.
-The rule of thumb is that the next groups should have a higher limit
-than the previous group.
+* delay = delay in milliseconds. The groups are separated with semicolon.
+ The rule of thumb is that the next groups should have a higher limit than
the previous group.
-Lets clarify this with an example:
-
-`delayPattern=5:1000;10:5000;20:20000`
+Let's clarify this with an example:
+
+[source,properties]
+----
+delayPattern=5:1000;10:5000;20:20000
+----
That gives us 3 groups:
@@ -252,58 +353,52 @@ That gives us 3 groups:
Resulting in these delays for redelivery attempt:
-* Redelivery attempt number 1..4 = 0 millis (as the first group start
-with 5)
+* Redelivery attempt number 1..4 = 0 millis (as the first group start with 5)
* Redelivery attempt number 5..9 = 1000 millis (the first group)
* Redelivery attempt number 10..19 = 5000 millis (the second group)
* Redelivery attempt number 20.. = 20000 millis (the last group)
-Note: The first redelivery attempt is 1, so the first group should start
-with 1 or higher.
+NOTE: The first redelivery attempt is 1, so the first group should start with
1 or higher.
-You can start a group with limit 1 to eg have a starting delay:
-`delayPattern=1:1000;5:5000`
+You can start a group with limit 1 to have a starting delay:
+
+[source,properties]
+----
+delayPattern=1:1000;5:5000
+----
* Redelivery attempt number 1..4 = 1000 millis (the first group)
* Redelivery attempt number 5.. = 5000 millis (the last group)
-There is no requirement that the next delay should be higher than the
-previous. You can use any delay value you like. For example with
-`delayPattern=1:5000;3:1000` we start with 5 sec delay and then later
-reduce that to 1 second.
-
-[[deadLetterChannel-Redeliveryheader]]
-== Redelivery header
-
-When a message is redelivered the
-https://www.javadoc.io/doc/org.apache.camel/camel-base/current/org/apache/camel/processor/errorhandler/DeadLetterChannel.html[DeadLetterChannel]
-will append a customizable header to the message to indicate how many
-times its been redelivered.
-Before Camel 2.6: The header is *CamelRedeliveryCounter*, which is also
-defined on the `Exchange.REDELIVERY_COUNTER`.
-Starting with 2.6: The header *CamelRedeliveryMaxCounter*, which is
-also defined on the `Exchange.REDELIVERY_MAX_COUNTER`, contains the
-maximum redelivery setting. This header is absent if you use
-`retryWhile` or have unlimited maximum redelivery configured.
+There is no requirement that the next delay should be higher than the previous.
+You can use any delay value you like. For example with:
-And a boolean flag whether it is being redelivered or not (first
-attempt)
-The header *CamelRedelivered* contains a boolean if the message is
-redelivered or not, which is also defined on the `Exchange.REDELIVERED`.
+[source,properties]
+----
+delayPattern=1:5000;3:1000
+----
+
+We start with 5 sec delay and then later reduce that to 1 second.
-Dynamically calculated delay from the exchange
-In Camel 2.9 and 2.8.2: The header is *CamelRedeliveryDelay*, which is
-also defined on the `Exchange.REDELIVERY_DELAY`.
-Is this header is absent, normal redelivery rules apply.
-[[deadLetterChannel-Whichendpointfailed]]
-== Which endpoint failed
+=== State of redelivery as message headers
+
+When a message is redelivered the Dead Letter Channel
+will append the following headers to the message with the state of the
redelivery:
+
+[width="100%",cols="1m,1m,",options="header"]
+|===
+| Header | Type | Description
+| Exchange.REDELIVERED | Boolean | Whether the message is redelivered
+| Exchange.REDELIVERY_COUNTER | Integer | The current redelivery attempt
+| Exchange.REDELIVERY_MAX_COUNTER | Integer | The maximum number of
redeliveries configured (if any). This header is absent if you use
+`retryWhile` or have unlimited maximum redelivery configured.
+|===
-*Since Camel 2.1*
+=== Which endpoint failed
-When Camel routes messages it will decorate the
-xref:latest@manual:ROOT:exchange.adoc[Exchange] with a property that contains
the *last*
-endpoint Camel send the xref:latest@manual:ROOT:exchange.adoc[Exchange] to:
+During routing messages Camel will store an exchange property
+with the most recent endpoint in use (send to):
[source,java]
----
@@ -313,185 +408,61 @@ String lastEndpointUri =
exchange.getProperty(Exchange.TO_ENDPOINT, String.class
The `Exchange.TO_ENDPOINT` have the constant value `CamelToEndpoint`.
This information is updated when Camel sends a message to any endpoint.
-So if it exists its the *last* endpoint which Camel send the Exchange
-to.
When for example processing the
xref:latest@manual:ROOT:exchange.adoc[Exchange] at a given
-xref:latest@manual:ROOT:endpoint.adoc[Endpoint] and the message is to be moved
into the
-dead letter queue, then Camel also decorates the Exchange with another
-property that contains that *last* endpoint:
+xref:latest@manual:ROOT:endpoint.adoc[Endpoint] and the message is to be moved
into the dead letter queue, then Camel also decorates the Exchange with another
property that contains that *last* endpoint:
[source,java]
----
String failedEndpointUri = exchange.getProperty(Exchange.FAILURE_ENDPOINT,
String.class);
----
-The `Exchange.FAILURE_ENDPOINT` have the constant value
-`CamelFailureEndpoint`.
+The `Exchange.FAILURE_ENDPOINT` have the constant value `CamelFailureEndpoint`.
-This allows for example you to fetch this information in your dead
-letter queue and use that for error reporting. +
- This is useable if the Camel route is a bit dynamic such as the dynamic
-xref:recipientList-eip.adoc[Recipient List] so you know which endpoints
-failed.
+This allows for example you to fetch this information in your dead letter
queue and use that for error reporting.
+This is particular usable if the Camel route uses dynamic EIPs such as
+xref:recipientList-eip.adoc[Recipient List] or xref:toD-eip.adoc[ToD], where
the target
+endpoint uri would be stored as information.
-These information is kept on the Exchange even if the message
-was successfully processed by a given endpoint, and then later fails for
-example in a local xref:components::bean-component.adoc[Bean] processing
instead. So beware
-that this is a hint that helps pinpoint errors.
+This information is kept on the Exchange even if the message was successfully
processed by a given endpoint,
+and then later fails for example in a local xref:bean-eip.adoc[Bean] EIP
processing instead.
+So beware that this is a hint that helps pinpoint errors to
xref:latest@manual:ROOT:endpoint.adoc[Endpoints], and not EIPs.
[source,java]
----
from("activemq:queue:foo")
.to("http://someserver/somepath";)
- .beanRef("foo");
-----
-
-Now suppose the route above and a failure happens in the `foo` bean.
-Then the `Exchange.TO_ENDPOINT` and `Exchange.FAILURE_ENDPOINT` will
-still contain the value of `\http://someserver/somepath`.
-
-[[deadLetterChannel-OnPrepareFailure]]
-== OnPrepareFailure
-
-*Since Camel 2.16*
-
-Before the exchange is sent to the dead letter queue, you can use
-onPrepare to allow a custom `Processor` to prepare the exchange, such as
-adding information why the Exchange failed. For example the following
-processor adds a header with the exception message
-
-[source,java]
-----
-public static class MyPrepareProcessor implements Processor {
- @Override
- public void process(Exchange exchange) throws Exception {
- Exception cause = exchange.getProperty(Exchange.EXCEPTION_CAUGHT,
Exception.class);
- exchange.getIn().setHeader("FailedBecause", cause.getMessage());
- }
-}
-----
-
-Then configure the error handler to use the processor as follows:
-
-[source,java]
-----
-errorHandler(deadLetterChannel("jms:dead").onPrepareFailure(new
MyPrepareProcessor()));
-----
-
-Configuring this from XML DSL is as shown:
-
-[source,xml]
-----
-<bean id="myPrepare"
-
class="org.apache.camel.processor.DeadLetterChannelOnPrepareTest.MyPrepareProcessor"/>
-
-
-<errorHandler id="dlc" type="DeadLetterChannel" deadLetterUri="jms:dead"
onPrepareFailureRef="myPrepare"/>
+ .bean("foo");
----
-The onPrepare is also available using the default error handler.
+Now suppose the route above, and a failure happens in the `foo` bean.
+Then the `Exchange.TO_ENDPOINT` and `Exchange.FAILURE_ENDPOINT` will still
contain the value of `\http://someserver/somepath`.
-[[deadLetterChannel-Whichroutefailed]]
-== Which route failed
-*Since Camel 2.10.4/2.11*
+=== Which route failed
-When Camel error handler handles an error such as
-xref:dead-letter-channel.adoc[Dead Letter Channel] or using
-xref:latest@manual:ROOT:exception-clause.adoc[Exception Clause] with
handled=true, then
-Camel will decorate +
- the xref:latest@manual:ROOT:exchange.adoc[Exchange] with the route id where
the error
-occurred.
+When a message is moved into the dead letter queue, then Camel will store the
id of the route,
+where the message failed. This information can be obtained in Java via:
[source,java]
----
String failedRouteId = exchange.getProperty(Exchange.FAILURE_ROUTE_ID,
String.class);
----
-The `Exchange.FAILURE_ROUTE_ID` have the constant value
-`CamelFailureRouteId`.
+The `Exchange.FAILURE_ROUTE_ID` have the constant value `CamelFailureRouteId`.
-This allows for example you to fetch this information in your dead
-letter queue and use that for error reporting.
+This allows for example you to fetch this information in your dead letter
queue and use that for error reporting.
-[[deadLetterChannel-Controlifredeliveryisallowedduringstoppingshutdown]]
-== Control if redelivery is allowed during stopping/shutdown
-*Since Camel 2.11*
-
-Prior to Camel 2.10, Camel will perform redelivery while stopping a
-route, or shutting down Camel. This has improved a bit in Camel 2.10
-onwards, as Camel will not perform redelivery attempts when shutting
-down aggressively (eg during
xref:latest@manual:ROOT:graceful-shutdown.adoc[Graceful
-Shutdown] and timeout hit). From Camel 2.11 onwards there is a new
-option `allowRedeliveryWhileStopping` which you can use to control if
-redelivery is allowed or not; notice that any in progress redelivery
-will still be executed. This option can only disallow any redelivery to
-be executed *after* the stopping of a route/shutdown of Camel has been
-triggered. If a redelivery is disallowed then a
-`RejectedExecutionException` is set on the
xref:latest@manual:ROOT:exchange.adoc[Exchange]
-and the processing of the xref:latest@manual:ROOT:exchange.adoc[Exchange]
stops. This means
-any consumer will see the xref:latest@manual:ROOT:exchange.adoc[Exchange] as
failed due the
-`RejectedExecutionException`.
-
-The default value is `true` to be backwards compatible as before. For
-example the following sample shows how to do this with Java DSL and XML
-DSL
-
-And the sample with XML DSL
+== Control if redelivery is allowed during stopping/shutdown
-[[deadLetterChannel-Samples]]
-== Samples
+The option `allowRedeliveryWhileStopping` (default is `true`) controls whether
redelivery is allowed or not,
+during stopping Camel or the route. This only applies for any potential new
redelivery attempts;
+any currently ongoing redeliveries is still being executed.
-The following example shows how to configure the Dead Letter Channel
-configuration using the xref:latest@manual:ROOT:dsl.adoc[DSL]
+This option can only disallow any redelivery to be executed *after* the
stopping of a route/shutdown of Camel has been triggered.
-You can also configure the
-https://www.javadoc.io/doc/org.apache.camel/camel-base/current/org/apache/camel/processor/errorhandler/RedeliveryPolicy.html[RedeliveryPolicy]
-as this example shows
-
-[[deadLetterChannel-HowcanImodifytheExchangebeforeredelivery]]
-== How can I modify the Exchange before redelivery?
-
-We support directly in xref:dead-letter-channel.adoc[Dead Letter
-Channel] to set a xref:latest@manual:ROOT:processor.adoc[Processor] that is
executed
-*before* each redelivery attempt.
-
-When xref:dead-letter-channel.adoc[Dead Letter Channel] is doing
-redeliver its possible to configure a
xref:latest@manual:ROOT:processor.adoc[Processor]
-that is executed just *before* every redelivery attempt. This can be
-used for the situations where you need to alter the message before its
-redelivered.
-
-Here we configure the xref:dead-letter-channel.adoc[Dead Letter Channel]
-to use our processor `MyRedeliveryProcessor` to be executed before each
-redelivery.
-
-And this is the processor `MyRedeliveryProcessor` where we alter the
-message.
-
-[[deadLetterChannel-HowcanIlogwhatcausedtheDeadLetterChanneltobeinvoked]]
-== How can I log what caused the Dead Letter Channel to be invoked?
-
-You often need to know what went wrong that caused the Dead Letter
-Channel to be used and it does not offer logging for this purpose. So
-the Dead Letter Channel's endpoint can be set to a endpoint of our own
-(such as `direct:deadLetterChannel`). We write a route to accept this
-Exchange and log the Exception, then forward on to where we want the
-failed Exchange moved to (which might be a DLQ queue for instance). See
-also
http://stackoverflow.com/questions/13711462/logging-camel-exceptions-and-sending-to-the-dead-letter-channel[http://stackoverflow.com/questions/13711462/logging-camel-exceptions-and-sending-to-the-dead-letter-channel]
-
-[[deadLetterChannel-UsingThisPattern]]
-=== Using This Pattern
-
-If you would like to use this EIP Pattern then please read the
-xref:latest@manual:ROOT:getting-started.adoc[Getting Started], you may also
find the
-xref:latest@manual:ROOT:architecture.adoc[Architecture] useful particularly
the description
-of xref:latest@manual:ROOT:endpoint.adoc[Endpoint] and
xref:latest@manual:ROOT:uris.adoc[URIs]. Then you could
-try out some of the xref:latest@manual:ROOT:examples.adoc[Examples] first
before trying
-this pattern out.
-
-* xref:latest@manual:ROOT:error-handler.adoc[Error Handler]
-* xref:latest@manual:ROOT:exception-clause.adoc[Exception Clause]
+If a redelivery is disallowed then a
+`RejectedExecutionException` exception is set on the Exchange, and it stops
being routed.
+The outcome of the Exchange is then a failure due the
`RejectedExecutionException`.
