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 e8ed16d CAMEL-16861: Cleanup and update EIP docs
e8ed16d is described below
commit e8ed16d12cbf49a34237b0ed9c551b213c6422fd
Author: Claus Ibsen <claus.ib...@gmail.com>
AuthorDate: Fri Sep 17 15:03:03 2021 +0200
CAMEL-16861: Cleanup and update EIP docs
---
.../main/docs/modules/eips/pages/failover-eip.adoc | 154 ++++++++++++++++++---
.../modules/eips/pages/fault-tolerance-eip.adoc | 66 ++++-----
2 files changed, 172 insertions(+), 48 deletions(-)
diff --git
a/core/camel-core-engine/src/main/docs/modules/eips/pages/failover-eip.adoc
b/core/camel-core-engine/src/main/docs/modules/eips/pages/failover-eip.adoc
index 37ee085..1a93b71 100644
--- a/core/camel-core-engine/src/main/docs/modules/eips/pages/failover-eip.adoc
+++ b/core/camel-core-engine/src/main/docs/modules/eips/pages/failover-eip.adoc
@@ -2,10 +2,11 @@
= Failover EIP
:docTitle: Failover
:description: Failover load balancer The failover load balancer is capable of
trying the next processor in case an Exchange failed with an exception during
processing. You can constrain the failover to activate only when one exception
of a list you specify occurs. If you do not specify a list any exception will
cause fail over to occur. This balancer uses the same strategy for matching
exceptions as the Exception Clause does for the onException.
-:since:
+:since:
:supportLevel: Stable
-Failover Load Balancer, with this policy in case of failures the exchange will
be tried on the next endpoint.
+This EIP allows using fail-over (in case of failures the exchange will be
tried on the next endpoint)
+with the xref:loadBalance-eip.adoc[Load Balancer] EIP.
== Options
@@ -22,29 +23,150 @@ The Failover EIP supports 4 options which are listed below:
|===
// eip options: END
-== Examples
+== Example
-In this case we are using the header test as correlation expression:
+In the example below calling the three http services is done with the load
balancer.
[source,java]
----
from("direct:start")
- .loadBalance()
- .failover(MyException.class)
- .to("seda:x", "seda:y", "seda:z");
+ .loadBalance().failover()
+ .to("http:service1")
+ .to("http:service2")
+ .to("http:service3")
+ .end();
----
-In XML you'll have a route like this
+In XML you'll have a route like this:
[source,xml]
----
-<from uri="direct:start"/>
+<route>
+ <from uri="direct:start"/>
<loadBalance>
- <failover>
- <exception>com.example.camel.MyException</exception>
- </failover>
- <to uri="seda:x"/>
- <to uri="seda:y"/>
- <to uri="seda:z"/>
- </loadBalance>
+ <failover/>
+ <to uri="http:service1"/>
+ <to uri="http:service2"/>
+ <to uri="http:service3"/>
+ </loadBalance>
+</route>
+----
+
+In the default mode the fail-over load balancer will always start with the
first processor (i.e. "http:service1").
+And in case this fails, then try the next, until either it succeeded or all of
them failed.
+If all failed then Camel will throw the caused exception which means the
Exchange is failed.
+
+=== Using round-robin mode
+
+You can use the `roundRobin` mode to start again from the beginning, which
then will keep
+trying until one succeed. To prevent endless retries, then it's recommended to
+set a maximum fail-over value.
+
+Setting this in Java DSL is not _pretty_ as there are three parameters:
+
+[source,java]
+----
+from("direct:start")
+ .loadBalance().failover(10, false, true)
+ .to("http:service1")
+ .to("http:service2")
+ .to("http:service3")
+ .end();
+----
+
+[source,java]
+----
+.failover(10, false, true)
+----
+
+Where `10` is the maximum failover attempts, And `false` is a special feature
+related to inheriting error handler. The last parameter `true` is to use round
robin mode.
+
+In XML it is straightforward as shown:
+
+[source,xml]
+----
+<route>
+ <from uri="direct:start"/>
+ <loadBalance>
+ <failover roundRobin="true" maximumFailoverAttempts="10"/>
+ <to uri="http:service1"/>
+ <to uri="http:service2"/>
+ <to uri="http:service3"/>
+ </loadBalance>
+</route>
+----
+
+=== Using sticky mode
+
+The sticky mode is used for remember the last known good endpoint, so the next
exchange
+will start from there, instead from the beginning.
+
+For example support that http:service1 is down, and that service2 is up.
+With sticky mode enabled, then Camel will keep starting from service2 until it
+fails, and then try service3.
+
+If sticky mode is not enabled (default) then Camel will always start from the
beginning, which
+means calling service1.
+
+Setting sticky mode in Java DSL is not _pretty_ as there are four parameters:
+
+[source,java]
+----
+from("direct:start")
+ .loadBalance().failover(10, false, true, true)
+ .to("http:service1")
+ .to("http:service2")
+ .to("http:service3")
+ .end();
+----
+
+The last `true` is to enable sticky mode.
+
+In XML it is straightforward as shown:
+
+[source,xml]
+----
+<route>
+ <from uri="direct:start"/>
+ <loadBalance>
+ <failover roundRobin="true" maximumFailoverAttempts="10"
stickyMode="true"/>
+ <to uri="http:service1"/>
+ <to uri="http:service2"/>
+ <to uri="http:service3"/>
+ </loadBalance>
+</route>
+----
+
+=== Fail-over on specific exceptions
+
+The fail-over load balancer can be configured to only apply for a specific set
of exceptions.
+Suppose you only want to fail-over in case of `java.io.Exception` or
`HttpOperationFailedException` then you can do:
+
+[source,java]
+----
+from("direct:start")
+ .loadBalance().failover(IOException.class,
HttpOperationFailedException.class)
+ .to("http:service1")
+ .to("http:service2")
+ .to("http:service3")
+ .end();
+----
+
+And in XML DSL:
+
+[source,xml]
+----
+<route>
+ <from uri="direct:start"/>
+ <loadBalance>
+ <failover>
+ <exception>java.io.IOException</exception>
+
<exception>org.apache.camel.http.base.HttpOperationFailedException</exception>
+ </failover>
+ <to uri="http:service1"/>
+ <to uri="http:service2"/>
+ <to uri="http:service3"/>
+ </loadBalance>
+</route>
----
diff --git
a/core/camel-core-engine/src/main/docs/modules/eips/pages/fault-tolerance-eip.adoc
b/core/camel-core-engine/src/main/docs/modules/eips/pages/fault-tolerance-eip.adoc
index 0b8b43a..9459656 100644
---
a/core/camel-core-engine/src/main/docs/modules/eips/pages/fault-tolerance-eip.adoc
+++
b/core/camel-core-engine/src/main/docs/modules/eips/pages/fault-tolerance-eip.adoc
@@ -3,24 +3,7 @@
This component supports the Circuit Breaker EIP with the MicroProfile Fault
Tolerance library.
-[NOTE]
-====
-Camel provides the Circuit Breaker EIP in the route model, which allows to
plugin different implementations.
-MicroProfile Fault Tolerance is one such implementation.
-====
-
-Maven users will need to add the following dependency to their pom.xml to use
this EIP:
-
-[source]
-----
-<dependency>
- <groupId>org.apache.camel</groupId>
- <artifactId>camel-microprofile-fault-tolerance</artifactId>
- <version>x.x.x</version><!-- use the same version as your Camel core
version -->
-</dependency>
-----
-
-== Configuration options
+== Options
// eip options: START
The Fault Tolerance EIP supports 2 options which are listed below:
@@ -35,9 +18,10 @@ The Fault Tolerance EIP supports 2 options which are listed
below:
See xref:faultToleranceConfiguration-eip.adoc[Fault Tolerance Configuration]
for all the configuration options on Fault Tolerance Circuit Breaker.
-== Samples
+== Example
Below is an example route showing a Fault Tolerance endpoint that protects
against a downstream HTTP operation by falling back to the in-lined fallback
route.
+
[source,java]
----
from("direct:start")
@@ -50,29 +34,28 @@ from("direct:start")
----
And in XML DSL:
+
[source,xml]
----
-<camelContext xmlns="http://camel.apache.org/schema/spring";>
- <route>
+<route>
<from uri="direct:start"/>
<circuitBreaker>
- <to uri="http://fooservice.com/faulty"/>
- <onFallback>
- <transform>
- <constant>Fallback message</constant>
- </transform>
- </onFallback>
+ <to uri="http://fooservice.com/faulty"/>
+ <onFallback>
+ <transform>
+ <constant>Fallback message</constant>
+ </transform>
+ </onFallback>
</circuitBreaker>
<to uri="mock:result"/>
- </route>
-</camelContext>
+</route>
----
== Configuring Fault Tolerance
You can fine-tune Fault Tolerance by the many
xref:faultToleranceConfiguration-eip.adoc[Fault Tolerance Configuration]
options.
-For example to use a 2 second execution timeout, you can do as follows:
+For example to use 2 second execution timeout, you can do as follows:
[source,java]
----
@@ -109,11 +92,11 @@ See xref:onFallback-eip.adoc[onFallback].
== Using Fault Tolerance with Spring Boot
-This component does not support Spring Boot. Instead its support in standalone
and with Camel Quarkus.
+This component does not support Spring Boot. Instead, its support in
standalone and with Camel Quarkus.
== Camel's Error Handler and Circuit Breaker EIP
-By default the Circuit Breaker EIP handles errors by itself. This means if the
circuit breaker is open and
+By default, the Circuit Breaker EIP handles errors by itself. This means if
the circuit breaker is open and
the message fails, then Camel's error handler is not reacting also.
However, you can enable Camels error handler with circuit breaker by enabling
the `inheritErrorHandler` option, as shown:
@@ -143,3 +126,22 @@ That means the `mock:a` endpoint will receive the message
again, and a total of
If we turn off the `inheritErrorHandler` option (default) then the Circuit
Breaker EIP will only be
executed once because it handled the error itself.
+== Dependencies
+
+[NOTE]
+====
+Camel provides the Circuit Breaker EIP in the route model, which allows to
plugin different implementations.
+MicroProfile Fault Tolerance is one such implementation.
+====
+
+Maven users will need to add the following dependency to their pom.xml to use
this EIP:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-microprofile-fault-tolerance</artifactId>
+ <version>x.x.x</version><!-- use the same version as your Camel core
version -->
+</dependency>
+----
+
