You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by ac...@apache.org on 2018/08/02 10:51:32 UTC
[camel] branch master updated: CAMEL-11497: Update user guide toc
in summary and migrate some pages
This is an automated email from the ASF dual-hosted git repository.
acosentino pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/master by this push:
new abb1611 CAMEL-11497: Update user guide toc in summary and migrate some pages
abb1611 is described below
commit abb1611828dfba2e2b4d701dd5c6f548a13ef380
Author: Tadayoshi Sato <sa...@gmail.com>
AuthorDate: Thu Aug 2 19:45:11 2018 +0900
CAMEL-11497: Update user guide toc in summary and migrate some pages
---
docs/user-manual/en/SUMMARY.md | 29 ++-
docs/user-manual/en/camel-boot.adoc | 37 ++++
docs/user-manual/en/camel-jar-dependencies.adoc | 55 +++++
docs/user-manual/en/error-handling-in-camel.adoc | 248 +++++++++++++++++++++++
4 files changed, 368 insertions(+), 1 deletion(-)
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index 384fed3..6118d66 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 0000000..ee2927b
--- /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 0000000..9670e51
--- /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 0000000..42bf1d7
--- /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]