Repository: camel Updated Branches: refs/heads/master d486902f4 -> 8a1501d67
CAMEL-11786: Migrate docs to more correct ascii doc format Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/8a1501d6 Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/8a1501d6 Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/8a1501d6 Branch: refs/heads/master Commit: 8a1501d67dbfd9feed707523e17e13edfa1b06a4 Parents: c30a1da Author: Claus Ibsen <davscl...@apache.org> Authored: Wed Sep 20 10:49:45 2017 +0200 Committer: Claus Ibsen <davscl...@apache.org> Committed: Wed Sep 20 10:50:00 2017 +0200 ---------------------------------------------------------------------- camel-core/src/main/docs/eips/hystrix-eip.adoc | 55 +++--- .../src/main/docs/eips/loadBalance-eip.adoc | 173 +++++++++---------- 2 files changed, 108 insertions(+), 120 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/8a1501d6/camel-core/src/main/docs/eips/hystrix-eip.adoc ---------------------------------------------------------------------- diff --git a/camel-core/src/main/docs/eips/hystrix-eip.adoc b/camel-core/src/main/docs/eips/hystrix-eip.adoc index a10538a..cac9da1 100644 --- a/camel-core/src/main/docs/eips/hystrix-eip.adoc +++ b/camel-core/src/main/docs/eips/hystrix-eip.adoc @@ -2,18 +2,18 @@ Available as of Camel 2.18 -The hystrix EIP provides integration with Netflix link:https://github.com/Netflix/Hystrix[Hystrix] to be used as circuit breaker in the Camel routes. Hystrix is a latency and fault tolerance library designed to isolate points of access to remote systems, services and 3rd party libraries, stop cascading failure and enable resilience in complex distributed systems where failure is inevitable. +The Hystrix EIP provides integration with Netflix link:https://github.com/Netflix/Hystrix[Hystrix] to be used as circuit breaker in the Camel routes. Hystrix is a latency and fault tolerance library designed to isolate points of access to remote systems, services and 3rd party libraries, stop cascading failure and enable resilience in complex distributed systems where failure is inevitable. Maven users will need to add the following dependency to their pom.xml to use this EIP: -[source,java] ---------------------- +[source] +---- <dependency> <groupId>org.apache.camel</groupId> <artifactId>camel-hystrix</artifactId> <version>x.x.x</version><!-- use the same version as your Camel core version --> </dependency> ---------------------- +---- === Configuration options @@ -29,10 +29,11 @@ The Hystrix EIP supports 2 options which are listed below: |=== // eip options: END -=== Example +=== Samples + Below is an example route showing an Hystrix endpoint that protects against slow operation by falling back to the in-lined fallback route. By default the timeout request is just *1000ms* so the HTTP endpoint has to be fairly quick to succeed. [source,java] ---------------------- +---- from("direct:start") .hystrix() .to("http://fooservice.com/slow";) @@ -40,11 +41,11 @@ from("direct:start") .transform().constant("Fallback message") .end() .to("mock:result"); ---------------------- +---- And in XML DSL: [source,xml] ---------------------- +---- <camelContext xmlns="http://camel.apache.org/schema/spring";> <route> <from uri="direct:start"/> @@ -59,34 +60,38 @@ And in XML DSL: <to uri="mock:result"/> </route> </camelContext> ---------------------- +---- === onFallback vs onFallbackViaNetwork + If you are using *onFallback* then that is intended to be local processing only where you can do a message transformation or call a bean or something as the fallback. If you need to call an external service over the network then you should use *onFallbackViaNetwork* that runs in another independent *HystrixCommand* that uses its own thread pool to not exhaust the first command. Configuring Hystrix Example Hystrix has many options as listed in the table above. For example to set a higher timeout to *5* seconds, and also let the circuit breaker wait *10* seconds before attempting a request again when the state was tripped to be open. + [source,java] ---------------------- +---- from("direct:start") .hystrix() .hystrixConfiguration() - .executionTimeoutInMilliseconds(5000).circuitBreakerSleepWindowInMilliseconds(10000) - .end() + .executionTimeoutInMilliseconds(5000) + .circuitBreakerSleepWindowInMilliseconds(10000) + .end() // end Hystrix configuration .to("http://fooservice.com/slow";) .onFallback() .transform().constant("Fallback message") .end() .to("mock:result"); ---------------------- +---- And in XML DSL: [source,xml] ---------------------- +---- <camelContext xmlns="http://camel.apache.org/schema/spring";> <route> <from uri="direct:start"/> <hystrix> - <hystrixConfiguration executionTimeoutInMilliseconds="5000" circuitBreakerSleepWindowInMilliseconds="10000"/> + <hystrixConfiguration executionTimeoutInMilliseconds="5000" + circuitBreakerSleepWindowInMilliseconds="10000"/> <to uri="http://fooservice.com/slow"/> <onFallback> <transform> @@ -97,17 +102,18 @@ And in XML DSL: <to uri="mock:result"/> </route> </camelContext> ---------------------- - +---- -You can also configure hystrix globally and then refer to that configuration: +You can also configure Hystrix globally and then refer to that configuration: [source,xml] ---------------------- +---- <camelContext xmlns="http://camel.apache.org/schema/spring";> - <!-- a shared config which you can refer to from all your hystrix EIPs --> - <hystrixConfiguration id="sharedConfig" executionTimeoutInMilliseconds="5000" circuitBreakerSleepWindowInMilliseconds="10000"/> + <!-- a shared config which you can refer to from all your Hystrix EIPs --> + <hystrixConfiguration id="sharedConfig" + executionTimeoutInMilliseconds="5000" + circuitBreakerSleepWindowInMilliseconds="10000"/> <route> <from uri="direct:start"/> @@ -122,7 +128,8 @@ You can also configure hystrix globally and then refer to that configuration: <to uri="mock:result"/> </route> </camelContext> ---------------------- +---- + +=== Other examples -=== Example -You can find an example in the source code: link:https://github.com/apache/camel/tree/master/examples/camel-example-hystrix[camel-example-hystrix]. +You can find an example with the source code: link:https://github.com/apache/camel/tree/master/examples/camel-example-hystrix[camel-example-hystrix]. http://git-wip-us.apache.org/repos/asf/camel/blob/8a1501d6/camel-core/src/main/docs/eips/loadBalance-eip.adoc ---------------------------------------------------------------------- diff --git a/camel-core/src/main/docs/eips/loadBalance-eip.adoc b/camel-core/src/main/docs/eips/loadBalance-eip.adoc index 4f08742..ca3f174 100644 --- a/camel-core/src/main/docs/eips/loadBalance-eip.adoc +++ b/camel-core/src/main/docs/eips/loadBalance-eip.adoc @@ -1,7 +1,9 @@ == Load Balance EIP + The Load Balancer Pattern allows you to delegate to one of a number of endpoints using a variety of different load balancing policies. == Built-in load balancing policies + Camel provides the following policies out-of-the-box: [width="100%",cols="3,6",options="header"] @@ -18,27 +20,41 @@ Camel provides the following policies out-of-the-box: | Circuit Breaker | *Camel 2.14*: Implements the Circuit Breaker pattern as described in "Release it!" book. |======================================================================= -[TIP] -.Load balancing HTTP endpoints -==== -If you are proxying and load balancing HTTP, then see link:TODO[this] page for more details. -==== +=== Options + +// eip options: START +The Load Balance EIP supports 2 options which are listed below: + + +[width="100%",cols="2,5,^1,2",options="header"] +|=== +| Name | Description | Default | Type +| *loadBalancerType* | *Required* The load balancer to be used | | LoadBalancerDefinition +| *inheritErrorHandler* | Sets whether or not to inherit the configured error handler. The default value is true. You can use this to disable using the inherited error handler for a given DSL such as a load balancer where you want to use a custom error handler strategy. | false | Boolean +|=== +// eip options: END + +=== Round Robin -== Round Robin The round robin load balancer is not meant to work with failover, for that you should use the dedicated *failover* load balancer. The round robin load balancer will only change to next endpoint per message. The round robin load balancer is stateful as it keeps state of which endpoint to use next time. -=== Using the Fluent Builders -[source,java] --------------------------------------------------------- -from("direct:start").loadBalance(). -roundRobin().to("mock:x", "mock:y", "mock:z"); --------------------------------------------------------- +Here is a little example: -=== Using the Spring configuration +[source,java] +---- +from("direct:start") + .loadBalance().roundRobin() + .to("mock:x") + .to("mock:y") + .to("mock:z") + .end() // end load balancer +---- + +And in XML: [source,xml] --------------------------------------------------------- +---- <camelContext id="camel" xmlns="http://camel.apache.org/schema/spring";> <route> <from uri="direct:start"/> @@ -50,72 +66,49 @@ roundRobin().to("mock:x", "mock:y", "mock:z"); </loadBalance> </route> </camelContext> --------------------------------------------------------- +---- The above example loads balance requests from *direct:start* to one of the available *mock endpoint* instances, in this case using a round robin policy. -For further examples of this pattern look at link:http://svn.apache.org/viewvc/camel/trunk/camel-core/src/test/java/org/apache/camel/processor/RoundRobinLoadBalanceTest.java?view=markup[this junit test case]. +=== Failover -== Failover 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`. -[TIP] -.Enable stream caching if using streams -==== +TIP: **Enable stream caching if using streams:** If you use streaming then you should enable Stream caching when using the failover load balancer. This is needed so the stream can be re-read after failing over to the next processor. -==== - -// eip options: START -The Load Balance EIP supports 2 options which are listed below: - - -[width="100%",cols="2,5,^1,2",options="header"] -|=== -| Name | Description | Default | Type -| *loadBalancerType* | *Required* The load balancer to be used | | LoadBalancerDefinition -| *inheritErrorHandler* | Sets whether or not to inherit the configured error handler. The default value is true. You can use this to disable using the inherited error handler for a given DSL such as a load balancer where you want to use a custom error handler strategy. | false | Boolean -|=== -// eip options: END - -*Camel 2.2 or older behavior* -The current implementation of failover load balancer uses simple logic which *always* tries the first endpoint, and in case of an exception being thrown it tries the next in the list, and so forth. It has no state, and the next message will thus *always* start with the first endpoint. -*Camel 2.3 onwards behavior* -The failover load balancer now supports round robin mode, which allows you to failover in a round robin fashion. See the `roundRobin` option. - -[WARNING] -.Redelivery must be enabled -==== -In Camel 2.2 or older the `failover` load balancer requires you have enabled Camel Error Handler to use redelivery. In Camel 2.3 onwards this is not required as such, as you can mix and match. See the `inheritErrorHandler` option. -==== Here is a sample to failover only if a IOException related exception was thrown: [source,java] --------------------------------------------------------- +---- from("direct:start") // here we will load balance if IOException was thrown // any other kind of exception will result in the Exchange as failed // to failover over any kind of exception we can just omit the exception // in the failOver DSL .loadBalance().failover(IOException.class) - .to("direct:x", "direct:y", "direct:z"); --------------------------------------------------------- + .to("mock:x") + .to("mock:y") + .to("mock:z"); +---- You can specify multiple exceptions to failover as the option is varargs, for instance: [source,java] --------------------------------------------------------- -// enable redelivery so failover can react +---- +// enable maximum redelivery so failover can react errorHandler(defaultErrorHandler().maximumRedeliveries(5)); from("direct:foo"). loadBalance().failover(IOException.class, MyOtherException.class) - .to("direct:a", "direct:b"); --------------------------------------------------------- + .to("direct:a") + .to("direct:b"); +---- + +And in XML: -=== Using failover in Spring DSL Failover can also be used from Spring DSL and you configure it as: [source,xml] --------------------------------------------------------- +---- <route errorHandlerRef="myErrorHandler"> <from uri="direct:foo"/> <loadBalance> @@ -127,24 +120,28 @@ Failover can also be used from Spring DSL and you configure it as: <to uri="direct:b"/> </loadBalance> </route> --------------------------------------------------------- +---- === Using failover in round robin mode + An example using Java DSL: [source,java] --------------------------------------------------------- +---- from("direct:start") // Use failover load balancer in stateful round robin mode // which mean it will failover immediately in case of an exception // as it does NOT inherit error handler. It will also keep retrying as // its configured to newer exhaust. - .loadBalance().failover(-1, false, true). - to("direct:bad", "direct:bad2", "direct:good", "direct:good2"); --------------------------------------------------------- + .loadBalance().failover(-1, false, true) + .to("direct:bad") + .to("direct:bad2") + .to("direct:good") + .to("direct:good2"); +---- And the same example using Spring XML: [source,xml] --------------------------------------------------------- +---- <route> <from uri="direct:start"/> <loadBalance> @@ -158,37 +155,20 @@ And the same example using Spring XML: <to uri="direct:good2"/> </loadBalance> </route> --------------------------------------------------------- +---- -[TIP] -.Disabled inheritErrorHandler -==== -You can configure `inheritErrorHandler=false` if you want to failover to the next endpoint as fast as possible. +TIP: *Disabled inheritErrorHandler*: You can configure `inheritErrorHandler=false` if you want to failover to the next endpoint as fast as possible. By disabling the Error Handler you ensure it does not _intervene_ which allows the `failover` load balancer to handle failover asap. By also enabling `roundRobin` mode, then it will keep retrying until it success. You can then configure the `maximumFailoverAttempts` option to a high value to let it eventually exhaust (give up) and fail. -==== -== Weighted Round-Robin and Random Load Balancing +=== Weighted Round-Robin and Random Load Balancing + *Available as of Camel 2.5* + In many enterprise environments where server nodes of unequal processing power & performance characteristics are utilized to host services and processing endpoints, it is frequently necessary to distribute processing load based on their individual server capabilities so that some endpoints are not unfairly burdened with requests. Obviously simple round-robin or random load balancing do not alleviate problems of this nature. A Weighted Round-Robin and/or Weighted Random load balancer can be used to address this problem. The weighted load balancing policy allows you to specify a processing load distribution ratio for each server with respect to others. You can specify this as a positive processing weight for each server. A larger number indicates that the server can handle a larger load. The weight is utilized to determine the payload distribution ratio to different processing endpoints with respect to others. -[TIP] -.Disabled inheritErrorHandler -==== -As of Camel 2.6, the Weighted Load balancer usage has been further simplified, there is no need to send in distributionRatio as a `List<Integer>`. It can be simply sent as a delimited String of integer weights separated by a delimiter of choice. -==== -The parameters that can be used are - -*In Camel 2.5* - -[width="100%",cols="3,1,2,6",options="header"] -|======================================================================= -| Option | Type | Default | Description -| roundRobin | boolean | false | The default value for round-robin is false. In the absence of this setting or parameter the load balancing algorithm used is random. -| distributionRatio | List<Integer> | none | The distributionRatio is a list consisting on integer weights passed in as a parameter. The distributionRatio must match the number of endpoints and/or processors specified in the load balancer list. In Camel 2.5 if endpoints do not match ratios, then a best effort distribution is attempted. -|======================================================================= -*Available In Camel 2.6* +The parameters that can be used are [width="100%",cols="3,1,2,6",options="header"] |======================================================================= @@ -199,12 +179,13 @@ The parameters that can be used are |======================================================================= === Using Weighted round-robin & random load balancing -*In Camel 2.5* + +*Available as of Camel 2.5* An example using Java DSL: [source,java] --------------------------------------------------------- -ArrayList<integer> distributionRatio = new ArrayList<integer>(); +---- +List<integer> distributionRatio = new ArrayList<integer>(); distributionRatio.add(4); distributionRatio.add(2); distributionRatio.add(1); @@ -218,27 +199,26 @@ from("direct:start") from("direct:start") .loadBalance().weighted(false, distributionRatio) .to("mock:x", "mock:y", "mock:z"); --------------------------------------------------------- +---- And the same example using Spring XML: [source,xml] --------------------------------------------------------- +---- <route> <from uri="direct:start"/> <loadBalance> - <weighted roundRobin="false" distributionRatio="4 2 1"/> + <weighted roundRobin="false" + distributionRatio="4 2 1"/> <to uri="mock:x"/> <to uri="mock:y"/> <to uri="mock:z"/> </loadBalance> </route> --------------------------------------------------------- - -*Available In Camel 2.6* +---- An example using Java DSL: [source,java] --------------------------------------------------------- +---- // round-robin from("direct:start") .loadBalance().weighted(true, "4:2:1" distributionRatioDelimiter=":") @@ -248,18 +228,19 @@ from("direct:start") from("direct:start") .loadBalance().weighted(false, "4,2,1") .to("mock:x", "mock:y", "mock:z"); --------------------------------------------------------- +---- And the same example using Spring XML: [source,xml] --------------------------------------------------------- +---- <route> <from uri="direct:start"/> <loadBalance> - <weighted roundRobin="false" distributionRatio="4-2-1" distributionRatioDelimiter="-" /> + <weighted roundRobin="false" + distributionRatio="4-2-1" distributionRatioDelimiter="-" /> <to uri="mock:x"/> <to uri="mock:y"/> <to uri="mock:z"/> </loadBalance> </route> --------------------------------------------------------- +----
