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 2406c926d5c6 CAMEL-26813: docs - the error handler of the calling
route deals with an exception that escapes a doTry of the called route (#30086)
2406c926d5c6 is described below
commit 2406c926d5c6990d95c1ee783cac7555d187ffcc
Author: Federico Mariani <[email protected]>
AuthorDate: Sun Nov 15 19:06:10 2026 +0100
CAMEL-26813: docs - the error handler of the calling route deals with an
exception that escapes a doTry of the called route (#30086)
Co-authored-by: Claude <[email protected]>
---
.../org/apache/camel/catalog/docs/doTry-eip.adoc | 3 +
.../main/docs/modules/eips/pages/doTry-eip.adoc | 3 +
.../onexception/ErrorHandlingAcrossRoutesTest.java | 121 ++++++++++++++++++++-
.../modules/ROOT/pages/error-handler.adoc | 17 ++-
.../modules/ROOT/pages/exception-clause.adoc | 6 +-
.../modules/ROOT/pages/try-catch-finally.adoc | 5 +
6 files changed, 147 insertions(+), 8 deletions(-)
diff --git
a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/doTry-eip.adoc
b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/doTry-eip.adoc
index 304606c2f286..6e89768c5061 100644
---
a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/doTry-eip.adoc
+++
b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/doTry-eip.adoc
@@ -223,6 +223,9 @@ The `Exchange.EXCEPTION_CAUGHT` exchange property contains
the thrown exception
An exception that is not caught by any `doCatch` (or an exception that is
thrown in a `doCatch` or `doFinally` block)
is not handled by the route error handler: `onException`, redelivery and the
dead letter channel are not in use
for the steps of a `doTry ... doCatch ... doFinally` block. The exception is
thrown from the `doTry`, and the exchange fails.
+When the route was called from another route, such as with `direct`, the error
handler of the calling route deals with
+the exception, as if it failed in the calling route; see
+xref:manual::error-handler.adoc#_error_handling_across_routes[Error handling
across routes].
If an exception is thrown in the `doFinally` block while an exception from the
`doTry` (or `doCatch`) block
is still not handled, then the original exception is kept and the exception
from the `doFinally` block is added
diff --git
a/core/camel-core-engine/src/main/docs/modules/eips/pages/doTry-eip.adoc
b/core/camel-core-engine/src/main/docs/modules/eips/pages/doTry-eip.adoc
index 304606c2f286..6e89768c5061 100644
--- a/core/camel-core-engine/src/main/docs/modules/eips/pages/doTry-eip.adoc
+++ b/core/camel-core-engine/src/main/docs/modules/eips/pages/doTry-eip.adoc
@@ -223,6 +223,9 @@ The `Exchange.EXCEPTION_CAUGHT` exchange property contains
the thrown exception
An exception that is not caught by any `doCatch` (or an exception that is
thrown in a `doCatch` or `doFinally` block)
is not handled by the route error handler: `onException`, redelivery and the
dead letter channel are not in use
for the steps of a `doTry ... doCatch ... doFinally` block. The exception is
thrown from the `doTry`, and the exchange fails.
+When the route was called from another route, such as with `direct`, the error
handler of the calling route deals with
+the exception, as if it failed in the calling route; see
+xref:manual::error-handler.adoc#_error_handling_across_routes[Error handling
across routes].
If an exception is thrown in the `doFinally` block while an exception from the
`doTry` (or `doCatch`) block
is still not handled, then the original exception is kept and the exception
from the `doFinally` block is added
diff --git
a/core/camel-core/src/test/java/org/apache/camel/processor/onexception/ErrorHandlingAcrossRoutesTest.java
b/core/camel-core/src/test/java/org/apache/camel/processor/onexception/ErrorHandlingAcrossRoutesTest.java
index 1a8404c30c1a..2743427e538c 100644
---
a/core/camel-core/src/test/java/org/apache/camel/processor/onexception/ErrorHandlingAcrossRoutesTest.java
+++
b/core/camel-core/src/test/java/org/apache/camel/processor/onexception/ErrorHandlingAcrossRoutesTest.java
@@ -25,6 +25,9 @@ import org.apache.camel.ExchangePattern;
import org.apache.camel.Processor;
import org.apache.camel.builder.RouteBuilder;
import org.apache.camel.builder.RouteConfigurationBuilder;
+import org.apache.camel.component.rest.DummyRestConsumerFactory;
+import org.apache.camel.model.RouteDefinition;
+import org.apache.camel.model.TryDefinition;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.Timeout;
import org.junit.jupiter.params.ParameterizedTest;
@@ -36,11 +39,11 @@ import static org.junit.jupiter.api.Assertions.assertNull;
/**
* The statements of the section "Error handling across routes" of
error-handler.adoc that no other test covers: the
- * onException of the calling route does not run for a failure the called
route's error handler dealt with. Covered
- * elsewhere: the redeliveries of the called route
(DoTryCalledRouteErrorHandlerTest), a dead letter channel in the
- * called route (MultiErrorHandlerInRouteTest,
SedaInOutWithErrorDeadLetterChannelTest), a continued failure
- * (OnExceptionContinueSubRouteTest) and the redelivery of a whole called
route without error handler
- * (RedeliverToSubRouteTest).
+ * onException of the calling route does not run for a failure the called
route's error handler dealt with, and it does
+ * run for an exception that escapes a doTry of the called route. Covered
elsewhere: the redeliveries of the called
+ * route (DoTryCalledRouteErrorHandlerTest), a dead letter channel in the
called route (MultiErrorHandlerInRouteTest,
+ * SedaInOutWithErrorDeadLetterChannelTest), a continued failure
(OnExceptionContinueSubRouteTest) and the redelivery of
+ * a whole called route without error handler (RedeliverToSubRouteTest).
*/
@Timeout(20)
class ErrorHandlingAcrossRoutesTest extends ContextTestSupport {
@@ -270,6 +273,114 @@ class ErrorHandlingAcrossRoutesTest extends
ContextTestSupport {
assertInstanceOf(IOException.class, out.getException());
}
+ /**
+ * The error handler of a route is not in use for the steps of a doTry
block, so an exception that escapes the doTry
+ * of the called route is not dealt with by the error handler of the
called route, but by the one of the calling
+ * route: its onException runs, and its redeliveries call the sub route
again.
+ */
+ @ParameterizedTest
+ @ValueSource(strings = { "notCaught", "thrownFromDoCatch",
"thrownFromDoFinally" })
+ void exceptionEscapingTheDoTryOfTheCalledRoute(String how) throws
Exception {
+ context.addRoutes(new RouteBuilder() {
+ @Override
+ public void configure() {
+ caller(this, "direct:sub");
+ RouteDefinition sub = from("direct:sub");
+
sub.onException(Exception.class).handled(true).to("mock:subOnException");
+ TryDefinition doTry = sub.doTry().process(failing());
+ switch (how) {
+ case "notCaught" ->
doTry.doCatch(IllegalStateException.class).to("mock:catch").end();
+ case "thrownFromDoCatch" ->
doTry.doCatch(IOException.class)
+ .throwException(new IllegalStateException("Thrown
from doCatch")).end();
+ default ->
doTry.doCatch(IOException.class).to("mock:catch")
+ .doFinally().throwException(new
IllegalStateException("Thrown from doFinally")).end();
+ }
+ }
+ });
+ context.start();
+
+ getMockEndpoint("mock:subOnException").expectedMessageCount(0);
+ getMockEndpoint("mock:callerOnException").expectedMessageCount(1);
+ getMockEndpoint("mock:afterCall").expectedMessageCount(0);
+
+ Exchange out = send();
+
+ assertMockEndpointsSatisfied();
+ // the first call and the 2 redeliveries of the caller, each calls the
sub route again
+ assertEquals(3, attempts.get());
+ assertNull(out.getException());
+ }
+
+ /**
+ * The control of the case above: the same exception thrown after the
doTry block of the called route is dealt with
+ * by the error handler of the called route.
+ */
+ @Test
+ void exceptionThrownAfterTheDoTryOfTheCalledRoute() throws Exception {
+ context.addRoutes(new RouteBuilder() {
+ @Override
+ public void configure() {
+ caller(this, "direct:sub");
+ RouteDefinition sub = from("direct:sub");
+
sub.onException(Exception.class).handled(true).to("mock:subOnException");
+
sub.doTry().process(failing()).doCatch(IOException.class).to("mock:catch").end()
+ .throwException(new IllegalStateException("Thrown
after the doTry"));
+ }
+ });
+ context.start();
+
+ getMockEndpoint("mock:subOnException").expectedMessageCount(1);
+ getMockEndpoint("mock:callerOnException").expectedMessageCount(0);
+ getMockEndpoint("mock:afterCall").expectedMessageCount(0);
+
+ Exchange out = send();
+
+ assertMockEndpointsSatisfied();
+ assertEquals(1, attempts.get());
+ assertNull(out.getException());
+ }
+
+ /**
+ * With inline routes, the direct route that a REST service calls is part
of the REST route: an exception that
+ * escapes its doTry fails the exchange, as in any single route. Without
inline routes, the REST route is the
+ * calling route, and its onException runs.
+ */
+ @ParameterizedTest
+ @ValueSource(booleans = { true, false })
+ void exceptionEscapingTheDoTryOfTheDirectRouteOfARestService(boolean
inlineRoutes) throws Exception {
+ context.getRegistry().bind("dummy-rest", new
DummyRestConsumerFactory());
+ context.addRoutes(new RouteBuilder() {
+ @Override
+ public void configure() {
+
restConfiguration().host("localhost").inlineRoutes(inlineRoutes);
+
onException(IllegalStateException.class).handled(true).to("mock:onException");
+
+ rest("/say").get("/hello").to("direct:hello");
+ from("direct:hello")
+ .doTry()
+ .process(failing())
+ .doCatch(IOException.class)
+ .throwException(new IllegalStateException("Thrown
from doCatch"))
+ .end();
+ }
+ });
+ context.start();
+
+ getMockEndpoint("mock:onException").expectedMessageCount(inlineRoutes
? 0 : 1);
+
+ // the input of the REST service is a seda endpoint created by the
DummyRestConsumerFactory
+ Exchange out = template.send("seda:get-say-hello",
ExchangePattern.InOut, e -> e.getMessage().setBody("Hello"));
+
+ assertMockEndpointsSatisfied();
+ assertEquals(inlineRoutes ? 1 : 2, context.getRoutes().size());
+ assertEquals(1, attempts.get());
+ if (inlineRoutes) {
+ assertInstanceOf(IllegalStateException.class, out.getException());
+ } else {
+ assertNull(out.getException());
+ }
+ }
+
public class Inventory {
public void reserve(String body) throws IOException {
attempts.incrementAndGet();
diff --git a/docs/user-manual/modules/ROOT/pages/error-handler.adoc
b/docs/user-manual/modules/ROOT/pages/error-handler.adoc
index 63592b9d8e27..8d4692f293ac 100644
--- a/docs/user-manual/modules/ROOT/pages/error-handler.adoc
+++ b/docs/user-manual/modules/ROOT/pages/error-handler.adoc
@@ -275,7 +275,8 @@ called route is dealt with by the error handler of the
called route, the route w
its `onException` clauses and its dead letter channel. Once that error handler
is done with the failure, the error
handlers of the calling routes do not deal with it again: they do not
redeliver, and their `onException` clauses do
not run for it. This also applies when the called route has only the default
error handler, without any
-`onException`.
+`onException`. An exception that escapes a `doTry` block of the called route
is the one case that differs, as
+described below.
An `onException` defined for all the routes of a `RouteBuilder`, or in a
xref:route-configuration.adoc[route configuration], is part of the error
handler of each route it applies to. When it
@@ -291,9 +292,23 @@ What the calling route sees depends on what the error
handler of the called rout
next steps do not run either. The reply is the message as the called route
left it.
* continued (an `onException` with `continued(true)`): the calling route
continues with its next steps.
+An exception that escapes a xref:try-catch-finally.adoc[doTry ... doCatch ...
doFinally] block of the called route
+(an exception that no `doCatch` catches, or that a `doCatch` or `doFinally`
block throws) is different. The error
+handler of a route is not in use for the steps of such a block, so the error
handler of the called route does not deal
+with this exception: no redelivery, no `onException` and no dead letter
channel of the called route. The error handler
+of the calling route deals with it instead, as if it failed in the calling
route: the `onException` clauses of the
+calling route run (also one defined for all the routes of its `RouteBuilder`),
and a redelivery of the calling route
+calls the whole called route again.
+
The same applies with xref:components::seda-component.adoc[SEDA] when the
calling route waits for the called route to
complete (`InOut`).
+With the xref:rest-dsl.adoc#_inline_rest_dsl_as_a_single_route[inline routes]
of the Rest DSL (the default), a
+`direct` route that a REST service calls and that is inlined is part of the
REST route, not a called route. An
+exception that escapes a `doTry` block of that `direct` route then fails the
exchange, and no `onException` runs for
+it, as in any single route. Without inline routes, the error handler of the
REST route deals with it, as described
+above.
+
To deal with the failure in the calling route instead, either:
* Turn off the error handler of the called route with
`errorHandler(noErrorHandler())`. The failure then goes to the
diff --git a/docs/user-manual/modules/ROOT/pages/exception-clause.adoc
b/docs/user-manual/modules/ROOT/pages/exception-clause.adoc
index 77968c86a6f7..47aed5d01a12 100644
--- a/docs/user-manual/modules/ROOT/pages/exception-clause.adoc
+++ b/docs/user-manual/modules/ROOT/pages/exception-clause.adoc
@@ -170,8 +170,10 @@ technique.
When a route calls another route, such as with `direct`, a failure in the
called route is dealt with by the error
handler of the called route, also when it is the default error handler, and
the exception clauses of the calling
-route do not run for it. See
xref:error-handler.adoc#_error_handling_across_routes[Error handling across
routes]
-for what the calling route sees, and how to deal with the failure there
instead.
+route do not run for it. An exception that escapes a `doTry` block of the
called route is different: the error
+handler of the called route does not deal with it, and the exception clauses
of the calling route run for it. See
+xref:error-handler.adoc#_error_handling_across_routes[Error handling across
routes] for what the calling route sees,
+and how to deal with the failure there instead.
== How Does Camel Select Which Clause Should Handle a Given Thrown Exception?
diff --git a/docs/user-manual/modules/ROOT/pages/try-catch-finally.adoc
b/docs/user-manual/modules/ROOT/pages/try-catch-finally.adoc
index 39311ff0a0a4..b6f106f0a4c4 100644
--- a/docs/user-manual/modules/ROOT/pages/try-catch-finally.adoc
+++ b/docs/user-manual/modules/ROOT/pages/try-catch-finally.adoc
@@ -19,6 +19,11 @@ xref:error-handler.adoc[Error Handler] is not in use;
meaning any
The reason is that
`doTry ... doCatch ... doFinally` is in fact its own error handler and mimics
how try/catch/finally works in Java.
+
+An exception that no `doCatch` catches, or that a `doCatch` or `doFinally`
block throws, is not handled by the error
+handler of the route either: the exchange fails with it. When the route was
called from another route, the error
+handler of the calling route deals with it; see
+xref:error-handler.adoc#_error_handling_across_routes[Error handling across
routes].
====
A route called from the `doTry` block, such as with `direct`, still uses its
own error handler. The `doCatch` catches