Federico Mariani created CAMEL-26813:
----------------------------------------
Summary: Documentation: explain error handling across routes (a
calling route's onException does not run for a failure the called route's error
handler dealt with)
Key: CAMEL-26813
URL: https://issues.apache.org/jira/browse/CAMEL-26813
Project: Camel
Issue Type: Improvement
Components: documentation, camel-core
Reporter: Federico Mariani
When route A calls route B (with {{direct}}, or {{seda}} with InOut) and B
fails, the failure is dealt with by the error handler of B, the route where it
happened. Once B's error handler is done with it (redelivery exhausted, whether
or not the failure was handled), the error handlers and {{onException}} clauses
of the calling routes do not run again for that failure: the callers only see
the outcome. This also applies when B has only the default error handler (no
{{onException}} at all). In the code this is
{{RedeliveryErrorHandler.isDone()}} / {{isFailedOrBridged()}} in
camel-core-processor (the failure handled / redelivery exhausted marks); for
{{seda}} InOut, {{ExchangeHelper.copyResults}} copies those marks back to the
caller.
The user manual does not say this anywhere, so users expect the {{onException}}
of the calling route to run:
* {{error-handler.adoc}}: the "Scopes" section only covers per RouteBuilder /
per route.
* {{exception-clause.adoc}}: "Scopes" only covers global / route specific.
* {{exception-advanced.adoc}}: "Global exception policies and nested error
handlers" is about one route.
* {{try-catch-finally.adoc}}: does not say that a {{doCatch}} catches the
failure of a called route.
Parts of the mechanism only appear as migration notes in
{{camel-4x-upgrade-guide-4_24.adoc}}.
Typical consequences:
* {{onException(...).handled(false)}} in B gives the exception back to A, but
A's {{onException}} does not run.
* To handle the failure in A instead: B uses {{errorHandler(noErrorHandler())}}
(B then has no redelivery or {{onException}} of its own, and a redelivery in A
sends the message to {{direct:B}} again, so the whole of B is retried, as the
existing section "How do I retry processing a message from a certain point back
or an entire route" shows), or A calls B inside {{doTry ... doCatch}}, and the
{{doCatch}} catches it.
*Planned doc change*
* error-handler.adoc: a short section "Error handling across routes" after
"Scopes" with the rule, {{seda}} InOut, the two ways to handle the failure in
the calling route (with the cost of {{noErrorHandler}}), and a small example.
* exception-clause.adoc ("Scopes") and try-catch-finally.adoc: short
cross-links.
* A focused test in camel-core that pins each statement of the new section on
main.
Motivating user question (Camel 4.17, unanswered):
https://stackoverflow.com/questions/79891038
Related: CAMEL-26447 (doTry: after a doCatch caught the failure of a called
route that failed unhandled, the later error handlers of the exchange treat it
as done). The new section does not describe what happens after the {{doCatch}},
which CAMEL-26447 may change. See also CAMEL-26332, CAMEL-26333, CAMEL-26434.
_Claude Code on behalf of Federico Mariani_
--
This message was sent by Atlassian Jira
(v10.3.26#10030026)
