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 7406711 Polish and cleanup documentation
7406711 is described below
commit 7406711360935a11ade7e0c90989832079e3b2d1
Author: Claus Ibsen <claus.ib...@gmail.com>
AuthorDate: Tue Aug 10 14:51:15 2021 +0200
Polish and cleanup documentation
---
.../docs/modules/eips/pages/polling-consumer.adoc | 2 +-
docs/user-manual/modules/ROOT/nav.adoc | 2 +-
.../modules/ROOT/pages/error-handler.adoc | 3 -
.../ROOT/pages/error-handling-in-camel.adoc | 225 ---------------------
docs/user-manual/modules/ROOT/pages/index.adoc | 2 +-
...en-consuming-for-example-from-a-ftp-server.adoc | 2 +-
...-file-consumer-use-the-camel-error-handler.adoc | 2 +-
7 files changed, 5 insertions(+), 233 deletions(-)
diff --git
a/core/camel-core-engine/src/main/docs/modules/eips/pages/polling-consumer.adoc
b/core/camel-core-engine/src/main/docs/modules/eips/pages/polling-consumer.adoc
index 8522266..4c78805 100644
---
a/core/camel-core-engine/src/main/docs/modules/eips/pages/polling-consumer.adoc
+++
b/core/camel-core-engine/src/main/docs/modules/eips/pages/polling-consumer.adoc
@@ -323,7 +323,7 @@ executed. For instance if Camel should poll a file network,
and this
network resource is not available then a *`java.io.IOException`* could
occur. As this error happens *before* any
xref:latest@manual:ROOT:exchange.adoc[Exchange]
has been created and prepared for routing, then the regular
-xref:latest@manual:ROOT:error-handling-in-camel.adoc[Error handling in Camel]
does not
+xref:latest@manual:ROOT:error-handler.adoc[Error handler] does not
apply. So what does the consumer do then? Well the exception is
propagated back to the *`run`* method where its handled. Camel will by
default log the exception at *`WARN`* level and then ignore it. At next
diff --git a/docs/user-manual/modules/ROOT/nav.adoc
b/docs/user-manual/modules/ROOT/nav.adoc
index 59e5e63..8f213d5 100644
--- a/docs/user-manual/modules/ROOT/nav.adoc
+++ b/docs/user-manual/modules/ROOT/nav.adoc
@@ -15,7 +15,7 @@
** xref:Endpoint-dsl.adoc[Endpoint-dsl]
** xref:examples.adoc[Examples]
** xref:graceful-shutdown.adoc[Graceful Shutdown]
-** xref:error-handling-in-camel.adoc[Error handling in Camel]
+** xref:error-handler.adoc[Error handler]
** xref:using-osgi-blueprint-with-camel.adoc[Using OSGi blueprint with Camel]
** xref:using-propertyplaceholder.adoc[How to use Camel property placeholders]
** xref:templating.adoc[Templating]
diff --git a/docs/user-manual/modules/ROOT/pages/error-handler.adoc
b/docs/user-manual/modules/ROOT/pages/error-handler.adoc
index f31f903..921e6f5 100644
--- a/docs/user-manual/modules/ROOT/pages/error-handler.adoc
+++ b/docs/user-manual/modules/ROOT/pages/error-handler.adoc
@@ -8,9 +8,6 @@ strategies to deal with errors processing an
xref:{eip-vc}:eips:eventDrivenConsu
An alternative is to specify the error handling directly in the
xref:dsl.adoc[DSL]
using the xref:exception-clause.adoc[Exception Clause].
-For introduction and background material see xref:error-handler.adoc[Error
handling]
-in Camel.
-
== Exception Clause
Using Error Handler combined with
diff --git a/docs/user-manual/modules/ROOT/pages/error-handling-in-camel.adoc
b/docs/user-manual/modules/ROOT/pages/error-handling-in-camel.adoc
deleted file mode 100644
index 08d9aef..0000000
--- a/docs/user-manual/modules/ROOT/pages/error-handling-in-camel.adoc
+++ /dev/null
@@ -1,225 +0,0 @@
-[[ErrorhandlinginCamel-ErrorhandlinginCamel]]
-= Error handling in Camel
-
-Error handling in Camel can roughly be separated into two distinct
-types:
-
-* non transactional
-* transactional
-
-Where non transactional is the most common type that is enabled
-out-of-the-box and handled by Camel itself. The transaction type is
-handled by a backing system such as a J2EE application server.
-
-[TIP]
-====
-**Using try ... catch ... finally**
-
-Related to error handling is the xref:try-catch-finally.adoc[Try Catch
-Finally] feature in Camel.
-====
-
-[[ErrorhandlinginCamel-Whendoesanerrorhappen]]
-== When does an error happen
-
-An error happens when
-
-* any uncaught exception is thrown during routing and processing of
-messages within Camel
-
-TIP: So think of this as a big exception interceptor that catches all
-exceptions and handles what to do.
-
-[[ErrorhandlinginCamel-Nontransactional]]
-== Non transactional
-
-By default Camel uses the non transaction type and orchestrates the
-error handling during processing and routing.
-
-As there isn't a single error handling configuration that suites all
-use cases, you should consider altering the default configurations to
-better suit you needs.
-
-[[ErrorhandlinginCamel-Camel1.xdefaulterrorhandler]]
-== Camel 1.x default error handler
-
-In Camel 1.x a global xref:{eip-vc}:eips:dead-letter-channel.adoc[Dead Letter
Channel]
-is setup as the xref:error-handler.adoc[Error Handler] by default. It's
-configured as:
-
-* redeliver up to 6 times
-* pause 1 second between each redelivery attempt
-* if all redelivery attempts failed then move exchange into the dead
-letter queue
-* the default dead letter queue is a logger that logs the exchange at
-ERROR level :star:
-
-[WARNING]
-====
-**Dead Letter Queue (*)**
-
-A dead letter queue is like a black hole, it will consume the
-xref:exchange.adoc[Exchange] and the xref:exchange.adoc[Exchange]
-routing is ended with no indication that it failed. +
-This works great in the xref:components::jms-component.adoc[JMS] Messaging
world where we
-don't want a bad message to cause endless retries and causing the system
-to exhaust. The message is said to be poison and thus we want to move it
-to a dead letter queue so the system can continue to operate and work
-with the next message.
-
-This default does not go well with other transports using in a
-request/reply messaging style. If the xref:exchange.adoc[Exchange]
-failed then the original caller will still want a response after the
-failure.
-
-So the bottom line is that you *must* configure and setup the error
-handling strategies that suits your business needs.
-====
-
-[[ErrorhandlinginCamel-Camel2.0onwardsdefaulterrorhandler]]
-== Camel 2.0 onwards default error handler
-
-In Camel 2.0 onwards a global
-xref:defaulterrorhandler.adoc[DefaultErrorHandler] is set up as the
-xref:error-handler.adoc[Error Handler] by default. It's configured as:
-
-* no redeliveries
-* no dead letter queue
-* if the exchange failed an exception is thrown and propagated back to
-the original caller wrapped in a `RuntimeCamelException`.
-
-[[ErrorhandlinginCamel-Scopes]]
-== Scopes
-
-Camel supports 2 scopes that is determined by the DSL in use:
-
-[width="100%",cols="25%,25%,25%,25%",options="header",]
-|=======================================================================
-|DSL |Scope 1 |Scope 2 |Note
-|XML DSL |CamelContext |route |Scope 2 takes precedence over scope 1
-
-|Java DSL |RouteBuilder |route |Scope 2 takes precedence over
-scope 1
-|=======================================================================
-
-When using XML DSL then scope 1 applies for all routes. Where as when
-using Java DSL then route 1 only applies for the given RouteBuilder
-instance. So if you have multiple RouteBuilder's then each route builder
-has its own scope 1.
-
-[TIP]
-====
-If you want to share scope among RouteBuilder's you can use class
-inheritance and create a base class, and then extend this class for your
-RouteBuilder's and invoke the super.configure() method.
-====
-
-Mind that there was a bug in Camel that affected the scopes when using
-multiple RouteBuilder classes. See more details at
-https://issues.apache.org/jira/browse/CAMEL-5456[CAMEL-5456].
-
-//NOTE: normal attribute replacement doesn't seem to work in xrefs in section
headers.
-[[ErrorhandlinginCamel-Howdoestheerrorhandlerwork]]
-== How does the xref:latest@components:eips:dead-letter-channel.adoc[Dead
Letter Channel] error handler work
-
-When Camel is started it will inspect the routes and weave in the error
-handling into the routing. With up to 3 supported scopes, the error
-handling can be quite complex. And on top of that you have inherited
-error handling and you can even configure
-xref:exception-clause.adoc[Exception Clause]s to handle specific
-exception types differently. So yes it's advanced but very powerful when
-you get the grip of it.
-
-To keep things simple we first look at the basic concept how Camel
-orchestrates the redelivery attempt. At any given node in the route
-graph Camel intercepts the current Exchange being routed and wraps it
-with the xref:error-handler.adoc[Error Handler]. This ensures that the
-xref:error-handler.adoc[Error Handler] can kick in, just as the AOP
-around concept. If the exchange can be routed without any problems then
-it's forwarded to the next node in the route graph, *But* if there was
-an exception thrown, then the xref:error-handler.adoc[Error Handler]
-kicks in and decides what to do.
-
-An example illustrating this:
-
-[source,java]
-----
-errorHandler(deadLetterChannel("jms:queue:dead"));
-
-from("seda:newOrder")
- .to("bean:validateOrder")
- .to("bean:storeOrder")
- .to("bean:confirmOrder");
-----
-
-In this route we have 3 nodes (the dots) where the
-xref:error-handler.adoc[Error Handler] is watching us (The AOP around
-stuff). So when an order arrives on the seda queue we consume it and
-send it to the validateOrder bean. In case the validation bean processed
-ok, we move on to the next node. In case the storeOrder bean failed and
-throws an exception it's caught by the
-xref:{eip-vc}:eips:dead-letter-channel.adoc[Dead Letter Channel] that decides
what to
-do next. Either it does a:
-
-* redeliver
-* or move it to dead letter queue
-
-It will continue to do redeliveries based on the policy configured. By
-default xref:{eip-vc}:eips:dead-letter-channel.adoc[Dead Letter Channel] will
attempt
-at most 6 redeliveries with 1 second delay. So if the storeOrder bean
-did succeed at the 3rd attempt the routing will continue to the next
-node the confirmOrder bean. In case all redeliveries failed the Exchange
-is regarded as failed and is moved to the dead letter queue and the
-processing of this exchange stops. By default the dead letter queue is
-just a ERROR logger.
-
-[NOTE]
-====
-This applies to all kind of xref:component.adoc[Components] in Camel.
-The sample above only uses xref:components::bean-component.adoc[Bean] but it's
the same for
-xref:components::file-component.adoc[File],
xref:components::mail-component.adoc[Mail],
-xref:components::velocity-component.adoc[Velocity] or whatever component you
use.
-====
-
-[[ErrorhandlinginCamel-Transactional]]
-== Transactional
-
-Camel leverages Spring transactions. Usually you can only use this with
-a limited number of transport types such as JMS or JDBC based, that yet
-again requires a transaction manager such as a Spring transaction, a
-J2EE server or a Message Broker.
-
-[[ErrorhandlinginCamel-Howdoesitwork]]
-== How does it work
-
-*Camel 1.x*
-
-Camel does the same weaving as for the non-transactional type. The
-difference is that for transactional exchanges the
-xref:error-handler.adoc[Error Handler] does *not* kick in. You can say
-the AOP around does not apply. Camel relies solely on the backing system
-to orchestrate the error handling. And as such the when the backing
-system does redeliver it will start all over again. For instance if the
-exchange was started by a JMS consumer then it's started again as the
-JMS message is rolled back on the JMS queue and Camel will re consume
-the JMS message again.
-
-*Camel 2.0*
-
-In Camel 2.0 we have empowered the
-xref:transactionerrorhandler.adoc[TransactionErrorHandler] to build on
-top of the same base that
-xref:defaulterrorhandler.adoc[DefaultErrorHandler] does. This allows you
-to use Camel redelivery with transactional routes as well. The Spring
-transaction manager is still in charge and have the last say. But you
-can use Camel to do some local redelivery, for instance to upload a file
-to a FTP server, in which Camel can do local redelivery. So this gives
-you the power from both worlds. In case Camel cannot redeliver the
-exchange will be failed and rolled back. By default the
-xref:transactionerrorhandler.adoc[TransactionErrorHandler] does *not*
-attempt any local redeliveries. You have to configure it to do so, for
-instance to set a maximum redelivers to a number > 0.
-
-See xref:{eip-vc}:eips:transactional-client.adoc[Transactional Client]
-for more.
-
diff --git a/docs/user-manual/modules/ROOT/pages/index.adoc
b/docs/user-manual/modules/ROOT/pages/index.adoc
index f290d8e..f6ac94f 100644
--- a/docs/user-manual/modules/ROOT/pages/index.adoc
+++ b/docs/user-manual/modules/ROOT/pages/index.adoc
@@ -53,7 +53,7 @@ For a deeper and better understanding of Apache Camel, an
xref:faq:what-is-camel
* xref:bean-integration.adoc[Bean Integration]
* xref:configuring-route-startup-ordering-and-autostartup.adoc[Configuring
route startup ordering and autostartup]
* xref:graceful-shutdown.adoc[Graceful Shutdown]
-* xref:error-handling-in-camel.adoc[Error handling in Camel]
+* xref:error-handler.adoc[Error handler]
* xref:using-propertyplaceholder.adoc[How to use Camel property placeholders]
* xref:examples.adoc[Examples]
* xref:testing.adoc[Testing]
diff --git
a/docs/user-manual/modules/faq/pages/how-do-i-handle-failures-when-consuming-for-example-from-a-ftp-server.adoc
b/docs/user-manual/modules/faq/pages/how-do-i-handle-failures-when-consuming-for-example-from-a-ftp-server.adoc
index 7630217..b4313aa 100644
---
a/docs/user-manual/modules/faq/pages/how-do-i-handle-failures-when-consuming-for-example-from-a-ftp-server.adoc
+++
b/docs/user-manual/modules/faq/pages/how-do-i-handle-failures-when-consuming-for-example-from-a-ftp-server.adoc
@@ -9,7 +9,7 @@
from("ftp://f...@somesever.com?password=secret";).to("bean:logic?method=doSomethin
----
And there is a failure with connecting to the remote FTP server. The
-existing xref:ROOT:error-handling-in-camel.adoc[Error handling in Camel] is
+existing xref:ROOT:error-handler.adoc[error handler] is
based on when a message is *being* routed.
In this case the error occurs *before* a message has been initiated and
routed. So how can I control the error handling?
diff --git
a/docs/user-manual/modules/faq/pages/why-does-my-file-consumer-not-pick-up-the-file-and-how-do-i-let-the-file-consumer-use-the-camel-error-handler.adoc
b/docs/user-manual/modules/faq/pages/why-does-my-file-consumer-not-pick-up-the-file-and-how-do-i-let-the-file-consumer-use-the-camel-error-handler.adoc
index 71d731c..d574076 100644
---
a/docs/user-manual/modules/faq/pages/why-does-my-file-consumer-not-pick-up-the-file-and-how-do-i-let-the-file-consumer-use-the-camel-error-handler.adoc
+++
b/docs/user-manual/modules/faq/pages/why-does-my-file-consumer-not-pick-up-the-file-and-how-do-i-let-the-file-consumer-use-the-camel-error-handler.adoc
@@ -14,7 +14,7 @@ xref:how-do-i-enable-debug-logging.adoc[turn on DEBUG
logging] at
Well, this is really a
http://en.wikipedia.org/wiki/Chicken_or_the_egg["chicken or the egg"]
-question. The Camel xref:ROOT:error-handling-in-camel.adoc[error handler]
+question. The Camel xref:ROOT:error-handler.adoc[error handler]
(e.g., in the routes) only applies when a message is being routed by the
routing engine.
Before this happens, a consumer must successfully receive a message,
