[
https://issues.apache.org/jira/browse/CAMEL-11497?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16566616#comment-16566616
]
ASF GitHub Bot commented on CAMEL-11497:
----------------------------------------
oscerd closed pull request #2450: CAMEL-11497: Update user guide toc in summary
and migrate some pages
URL: https://github.com/apache/camel/pull/2450
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index 384fed33b02..6118d668f05 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -547,10 +547,37 @@
* [BAM Example](bam-example.adoc)
* User Guide
- * [Karaf](karaf.adoc)
+
+ * [Camel JAR Dependencies](camel-jar-dependencies.adoc)
+ * [Camel Boot](camel-boot.adoc)
+ * [Working with Camel and CDI]
+ * [Working with Camel and Spring]
+ * [Working with Camel and Guice]
+ * [Working with Camel and Karaf](karaf.adoc)
+ * [How Do I Configure Endpoints?]
+ * [Bean Integration]
+ * [Configuring Camel]
+ * [Configuring route startup ordering and autostartup]
+ * [Graceful Shutdown]
+ * [AsyncProcessorAwaitManager] for insight into the routing engine when it
has been forced to block threads while exchanges are being processed
asynchronous.
+ * [Error handling in Camel](error-handling-in-camel.adoc)
+ * [How to use Camel property placeholders]
+ * [Tutorials]
+ * [Examples]
* [Testing](testing.adoc)
* [Test](test.adoc)
* [Blueprint Testing](test-blueprint.adoc)
* [CDI Testing](test-cdi.adoc)
* [Spring Testing](test-spring.adoc)
+ * [Xml Configuration]
+ * [Using CamelProxy] for how to use proxies for clients to easily invoke
camel routes without them knowing
+ * [Camel Maven Plugin] for running Camel from a Maven goal
+ * [Guice Maven Plugin] for working with [Guice](guice.adoc)
+ * [Camel Maven Archetypes]
+ * [Creating a new Spring based Camel Route]
+ * [Camel JMX]
+ * [How to run Camel in a osgi container]
+ * [Using OSGi blueprint with Camel]
+ * [Working with Camel and SCR]
+ * Working with REST and link:rest-dsl.html[Rest DSL]
* [JSSE Utility](camel-configuration-utilities.adoc)
diff --git a/docs/user-manual/en/camel-boot.adoc
b/docs/user-manual/en/camel-boot.adoc
new file mode 100644
index 00000000000..ee2927bad10
--- /dev/null
+++ b/docs/user-manual/en/camel-boot.adoc
@@ -0,0 +1,37 @@
+[[CamelBoot-CamelBoot]]
+Camel Boot
+~~~~~~~~~~
+
+Camel lets you boot up a JVM process and configure Camel nicely using
+whichever dependency injection framework you choose.
+
+For each of the main dependency injection frameworks, Camel has a Main
+class with a `public static void run(String[] args)` function so that
+you can boot up your JVM which then also bootstraps the Dependency
+Injection framework to load all the camel contexts and services
+required.
+
+The following camel boot options are supported:
+
+[[CamelBoot-CDI]]
+CDI
+^^^
+
+Using the link:cdi.html[camel-cdi module] you can boot up your Camel
+Java process using the *org.apache.camel.cdi.Main* class
+
+[[CamelBoot-Spring]]
+Spring
+^^^^^^
+
+Using the link:spring.html[camel-spring module] you can boot you your
+Camel Java process using the *org.apache.camel.spring.Main* class
+
+[[CamelBoot-SpringBoot]]
+Spring Boot
+^^^^^^^^^^^
+
+You can combine Spring Boot with Camel using
+link:spring-boot.html[Camel's Spring Boot integration]. In this case
+your application looks and feels like a regular Spring Boot application
+but with full Camel integration.
diff --git a/docs/user-manual/en/camel-jar-dependencies.adoc
b/docs/user-manual/en/camel-jar-dependencies.adoc
new file mode 100644
index 00000000000..9670e511b75
--- /dev/null
+++ b/docs/user-manual/en/camel-jar-dependencies.adoc
@@ -0,0 +1,55 @@
+[[CamelJARDependencies-CamelJARDependencies]]
+Camel JAR Dependencies
+~~~~~~~~~~~~~~~~~~~~~~
+
+Camel core itself is lightweight and can run with a few .jars.
+
+[[CamelJARDependencies-camel-coredependenciesforCamel2.0orlower]]
+`camel-core` dependencies for Camel 2.0 or lower
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* `commons-logging-api.jar` - API for commons logging
+* JAXB 2.1.x - XML stuff - Is provided in the JDK core from Java 1.6
+* `activation.jar` - For Attachments support - Is provided in the JDK
+core from Java 1.6
+
+[[CamelJARDependencies-camel-coredependenciesforCamel2.1-2.6]]
+`camel-core` dependencies for Camel 2.1 - 2.6
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* `commons-logging-api-1.1.jar` - API for commons logging
+* `commons-management-1.0.jar` - API for JMX
+* JAXB 2.1.x - XML stuff - Is provided in the JDK core from Java 1.6
+* `activation-1.1.jar` - For Attachments support - Is provided in the
+JDK core from Java 1.6
+
+[[CamelJARDependencies-camel-coredependenciesforCamel2.7-2.8]]
+`camel-core` dependencies for Camel 2.7 - 2.8
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* `slf4j-api-1.5.11.jar` - API for slf4j logging
+* `commons-management-1.0.jar` - API for JMX
+
+[[CamelJARDependencies-camel-coredependenciesforCamel2.9]]
+`camel-core` dependencies for Camel 2.9
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* `slf4j-api-1.6.1.jar` - API for slf4j logging
+
+[[CamelJARDependencies-OptionaldependenciesforJMXforCamel1.x-2.8]]
+Optional dependencies for JMX for Camel 1.x - 2.8
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* `spring-core.jar`, `spring-beans.jar`,
+`spring-context.jar`, `spring-aop.jar` - All 4 jars needed to use JMX
+with Camel (subject to change in the future).
+
+From *Camel 2.9*: the Spring JARs are no longer required for using JMX.
+
+[[CamelJARDependencies-OtherComponents]]
+Other Components
+~~~~~~~~~~~~~~~~
+
+All the other link:components.html[Components] have a range of 3rd party
+.jars they depend on. They are listed in the maven pom files which files
+they require.
diff --git a/docs/user-manual/en/error-handling-in-camel.adoc
b/docs/user-manual/en/error-handling-in-camel.adoc
new file mode 100644
index 00000000000..42bf1d767bb
--- /dev/null
+++ b/docs/user-manual/en/error-handling-in-camel.adoc
@@ -0,0 +1,248 @@
+[[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 link:try-catch-finally.html[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
+uses 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 link:dead-letter-channel.html[Dead Letter Channel]
+is setup as the link:error-handler.html[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
+link:exchange.html[Exchange] and the link:exchange.html[Exchange]
+routing is ended with no indication that it failed. +
+This works great in the link:jms.html[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 link:exchange.html[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
+link:defaulterrorhandler.html[DefaultErrorHandler] is set up as the
+link:error-handler.html[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/Scala 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].
+
+[[ErrorhandlinginCamel-Howdoestheerrorhandlerwork]]
+How does the link:dead-letter-channel.html[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
+link:exception-clause.html[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 link:error-handler.html[Error Handler]. This ensures that the
+link:error-handler.html[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 link:error-handler.html[Error Handler]
+kicks in and decides what to do.
+
+An example illustrating this:
+
+[source,brush:,java;,gutter:,false;,theme:,Default]
+----
+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
+link:error-handler.html[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
+link:dead-letter-channel.html[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 link:dead-letter-channel.html[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 link:components.html[Components] in Camel.
+The sample above only uses link:bean.html[Bean] but it's the same for
+link:file2.html[File], link:mail.html[Mail],
+link:velocity.html[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
+link:error-handler.html[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
+link:transactionerrorhandler.html[TransactionErrorHandler] to build on
+top of the same base that
+link:defaulterrorhandler.html[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
+link:transactionerrorhandler.html[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 link:transactional-client.html[Transactional Client] for more.
+
+[[ErrorhandlinginCamel-Seealso]]
+See also
+~~~~~~~~
+
+* link:error-handler.html[Error Handler]
+* link:dead-letter-channel.html[Dead Letter Channel]
+* link:exception-clause.html[Exception Clause]
+* link:transactional-client.html[Transactional Client]
+* link:transactionerrorhandler.html[TransactionErrorHandler]
+* link:defaulterrorhandler.html[DefaultErrorHandler]
+* link:try-catch-finally.html[Try Catch Finally]
+* link:load-balancer.html[Failover Load Balancer]
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
> Migrate the rest of the Confluence content
> ------------------------------------------
>
> Key: CAMEL-11497
> URL: https://issues.apache.org/jira/browse/CAMEL-11497
> Project: Camel
> Issue Type: Sub-task
> Components: website
> Reporter: Zoran Regvart
> Assignee: Önder Sezgin
> Priority: Major
> Fix For: Future
>
>
> There are still pages in the Confluence that are not migrated to Asciidoctor
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
