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 485709e CAMEL-16861: Cleanup and update EIP docs
485709e is described below
commit 485709eef61e23bece6d8c4da2afee2c3f3f20a4
Author: Claus Ibsen <claus.ib...@gmail.com>
AuthorDate: Sat Sep 18 18:21:21 2021 +0200
CAMEL-16861: Cleanup and update EIP docs
---
.../main/docs/modules/eips/pages/choice-eip.adoc | 4 -
.../modules/eips/pages/fault-tolerance-eip.adoc | 54 +++++---
.../pages/faultToleranceConfiguration-eip.adoc | 5 +
.../main/docs/modules/eips/pages/filter-eip.adoc | 140 ++++++++++++++-------
.../src/main/docs/modules/eips/pages/from-eip.adoc | 22 ++--
5 files changed, 146 insertions(+), 79 deletions(-)
diff --git
a/core/camel-core-engine/src/main/docs/modules/eips/pages/choice-eip.adoc
b/core/camel-core-engine/src/main/docs/modules/eips/pages/choice-eip.adoc
index 522c841..06d62a1 100644
--- a/core/camel-core-engine/src/main/docs/modules/eips/pages/choice-eip.adoc
+++ b/core/camel-core-engine/src/main/docs/modules/eips/pages/choice-eip.adoc
@@ -28,10 +28,6 @@ The Choice EIP supports 2 options which are listed below:
== Example
-The following example shows how to route a request from an input
-*seda:a* endpoint to either *seda:b*, *seda:c* or *seda:d* depending on
-the evaluation of various xref:latest@manual:ROOT:predicate.adoc[Predicate].
-
The Camel xref:components:languages:simple-language.adoc[Simple] language
is great to use with the Choice EIP when routing is based on the content of
the message,
such as checking message headers.
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 9459656..e841610 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
@@ -1,7 +1,8 @@
[[faulttolerance-eip]]
= Fault Tolerance EIP
-This component supports the Circuit Breaker EIP with the MicroProfile Fault
Tolerance library.
+This component supports the xref:circuitBreaker-eip.adoc[Circuit Breaker] EIP
with the
+xref:components:others:microprofile-fault-tolerance.adoc[MicroProfile Fault
Tolerance] library.
== Options
@@ -16,11 +17,13 @@ The Fault Tolerance EIP supports 2 options which are listed
below:
|===
// eip options: END
-See xref:faultToleranceConfiguration-eip.adoc[Fault Tolerance Configuration]
for all the configuration options on Fault Tolerance Circuit Breaker.
+See xref:faultToleranceConfiguration-eip.adoc[Fault Tolerance Configuration]
for all the configuration options
+on the Fault Tolerance xref:circuitBreaker-eip.adoc[Circuit Breaker].
-== Example
+== Using Fault Tolerance EIP
-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.
+Below is an example route showing a Fault Tolerance EIP circuit breaker
+that protects against a downstream HTTP operation with fallback.
[source,java]
----
@@ -51,9 +54,16 @@ And in XML DSL:
</route>
----
-== Configuring Fault Tolerance
+In case the calling the downstream HTTP service is failing, and an exception
is thrown
+then the circuit breaker will react and execute the fallback route instead.
-You can fine-tune Fault Tolerance by the many
xref:faultToleranceConfiguration-eip.adoc[Fault Tolerance Configuration]
options.
+If there was no fallback, then the circuit breaker will throw an exception.
+
+TIP: For more information about fallback see
xref:onFallback-eip.adoc[onFallback].
+
+=== Configuring Fault Tolerance
+
+You can fine-tune the Fault Tolerance EIP by the many
xref:faultToleranceConfiguration-eip.adoc[Fault Tolerance Configuration]
options.
For example to use 2 second execution timeout, you can do as follows:
@@ -64,7 +74,7 @@ from("direct:start")
// use 2 second timeout
.faultToleranceConfiguration().timeoutEnabled(true).timeoutDuration(2000).end()
.log("Fault Tolerance processing start: ${threadName}")
- .toD("direct:${body}")
+ .to("http://fooservice.com/faulty";)
.log("Fault Tolerance processing end: ${threadName}")
.end()
.log("After Fault Tolerance ${body}");
@@ -79,26 +89,24 @@ And in XML:
<circuitBreaker>
<faultToleranceConfiguration timeoutEnabled="true" timeoutDuration="2000"/>
<log message="Fault Tolerance processing start: ${threadName}"/>
- <toD uri="direct:${body}"/>
+ <to uri="http://fooservice.com/faulty"/>
<log message="Fault Tolerance processing end: ${threadName}"/>
</circuitBreaker>
<log message="After Fault Tolerance: ${body}"/>
</route>
----
-== Fallback
-
-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.
+In this example if calling the downstream service does not return a response
within 2 seconds,
+a timeout is triggered, and the exchange will fail with a TimeoutException.
== 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
-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:
+By default, the xref:circuitBreaker-eip.adoc[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:
[source,java]
----
@@ -116,7 +124,7 @@ from("direct:start")
.to("mock:result");
----
-This example is from an unit test, where you can see the Circuit Breaker EIP
block has been hardcoded
+This example is from a test, where you can see the Circuit Breaker EIP block
has been hardcoded
to always fail by throwing an exception. Because the `inheritErrorHandler` has
been enabled,
then Camel's error handler will attempt to call the Circuit Breaker EIP block
again.
@@ -130,7 +138,8 @@ executed once because it handled the error itself.
[NOTE]
====
-Camel provides the Circuit Breaker EIP in the route model, which allows to
plugin different implementations.
+Camel provides the xref:circuitBreaker-eip.adoc[Circuit Breaker] EIP in the
route model,
+which allows to plugin different implementations.
MicroProfile Fault Tolerance is one such implementation.
====
@@ -145,3 +154,8 @@ Maven users will need to add the following dependency to
their pom.xml to use th
</dependency>
----
+=== Using Fault Tolerance with Spring Boot
+
+This component does not support Spring Boot.
+Instead, it is supported in Standalone and with Camel Quarkus.
+
diff --git
a/core/camel-core-engine/src/main/docs/modules/eips/pages/faultToleranceConfiguration-eip.adoc
b/core/camel-core-engine/src/main/docs/modules/eips/pages/faultToleranceConfiguration-eip.adoc
index aa57867..e85824b 100644
---
a/core/camel-core-engine/src/main/docs/modules/eips/pages/faultToleranceConfiguration-eip.adoc
+++
b/core/camel-core-engine/src/main/docs/modules/eips/pages/faultToleranceConfiguration-eip.adoc
@@ -5,6 +5,7 @@
:since:
:supportLevel: Stable
+This page documents all the specific options for the
xref:fault-tolerance-eip.adoc[Fault Tolerance] EIP.
// eip options: START
The Fault Tolerance Configuration EIP supports 13 options which are listed
below:
@@ -27,3 +28,7 @@ The Fault Tolerance Configuration EIP supports 13 options
which are listed below
| *bulkheadExecutorServiceRef* | References to a custom thread pool to use
when bulkhead is enabled. | | String
|===
// eip options: END
+
+== Example
+
+See xref:fault-tolerance-eip.adoc[Fault Tolerance] EIP for details how to use
this EIP.
diff --git
a/core/camel-core-engine/src/main/docs/modules/eips/pages/filter-eip.adoc
b/core/camel-core-engine/src/main/docs/modules/eips/pages/filter-eip.adoc
index 61eab1a..d0e8f96 100644
--- a/core/camel-core-engine/src/main/docs/modules/eips/pages/filter-eip.adoc
+++ b/core/camel-core-engine/src/main/docs/modules/eips/pages/filter-eip.adoc
@@ -7,13 +7,12 @@
The http://www.enterpriseintegrationpatterns.com/Filter.html[Message
Filter] from the xref:enterprise-integration-patterns.adoc[EIP patterns]
-allows you to filter messages
+allows you to filter messages.
-image::eip/MessageFilter.gif[image]
+IMPORTANT: The message filter implemented in Camel is similar to `if
(predicate) { block }`
+in Java. The filter will *include* the message if the predicate evaluated to
`true`.
-The following example shows how to create a Message Filter route
-consuming messages from an endpoint called *queue:a*, which if the
-xref:latest@manual:ROOT:predicate.adoc[Predicate] is true will be dispatched
to *queue:b*
+image::eip/MessageFilter.gif[image]
== EIP options
@@ -21,18 +20,37 @@ xref:latest@manual:ROOT:predicate.adoc[Predicate] is true
will be dispatched to
The Filter EIP has no options.
// eip options: END
-== Samples
+== Example
-Here is a little example in Java DSL:
+The Camel xref:components:languages:simple-language.adoc[Simple] language
+is great to use with the Filter EIP when routing is based on the content of
the message,
+such as checking message headers.
[source,java]
----
from("direct:a")
.filter(simple("${header.foo} == 'bar'"))
- .to("direct:b");
+ .to("direct:bar")
+ .end()
+ .to("direct:b")
+----
+
+And in XML:
+
+[source,xml]
+----
+<route>
+ <from uri="direct:a"/>
+ <filter>
+ <simple>${header.foo} == 'bar'</simple>
+ <to uri="direct:bar"/>
+ </filter>
+ <to uri="direct:b"/>
+</route>
----
-You can use many different languages as the predicate, such as XPath:
+You can use many languages as the predicate, such as
xref:components:languages:xpath-language.adoc[XPath]:
+
[source,java]
----
from("direct:start").
@@ -40,7 +58,21 @@ from("direct:start").
to("mock:result");
----
-Here is another example of using a bean to define the filter behavior
+And in XML:
+
+[source,xml]
+----
+<route>
+ <from uri="direct:start"/>
+ <filter>
+ <xpath>/person[@name='James']</xpath>
+ <to uri="mock:result"/>
+ </filter>
+</route>
+----
+
+Here is another example of calling a
xref:components:languages:bean-language.adoc[method on a bean]
+to define the filter behavior:
[source,java]
----
@@ -49,56 +81,72 @@ from("direct:start")
.to("mock:gold")
.end()
.to("mock:all");
+}
+----
+
+And then bean can have a method that returns a `boolean` as the predicate:
+[source,java]
+----
public static class MyBean {
- public boolean isGoldCustomer(@Header("level") String level) {
- return level.equals("gold");
+
+ public boolean isGoldCustomer(@Header("level") String level) {
+ return level.equals("gold");
}
+
}
----
-And the example in XML:
+And in XML we can call the bean in `<method> where we can specify the FQN
classname
+of the bean as shown:
[source,xml]
----
-<bean id="myBean" class="com.foo.MyBean"/>
-
-<camelContext xmlns="http://camel.apache.org/schema/spring";>
- <route>
- <from uri="direct:a"/>
- <filter>
- <method ref="myBean" method="isGoldCustomer"/>
- <to uri="direct:b"/>
- </filter>
- </route>
-</camelContext>
+<route>
+ <from uri="direct:start"/>
+ <filter>
+ <method type="com.foo.MyBean" method="isGoldCustomer"/>
+ <to uri="mock:gold"/>
+ </filter>
+ <to uri="mock:all"/>
+</route>
----
+=== Filtering and stopping
-== Using stop
+When using the Message Filter EIP, then it only applies to its children.
-Stop is a bit different than a message filter as it will filter out all
-messages and end the route entirely (filter only applies to its child
-processor). Stop is convenient to use in a
-xref:choice-eip.adoc[Content Based Router] when you for
-example need to stop further processing in one of the predicates.
+For example in the previous example:
-In the example below we do not want to route messages any further that
-has the word `Bye` in the message body. Notice how we prevent this in
-the when predicate by using the `.stop()`.
+[source,xml]
+----
+<route>
+ <from uri="direct:start"/>
+ <filter>
+ <method type="com.foo.MyBean" method="isGoldCustomer"/>
+ <to uri="mock:gold"/>
+ </filter>
+ <to uri="mock:all"/>
+</route>
+----
+
+Then for a message that is a gold customer will be routed to both mock:gold
and mock:all (predicate is true).
+However, for a non-gold message (predicate is false) then the message will not
be routed in the filter block,
+but will be routed to mock:all.
-== Knowing if Exchange was filtered or not
+Sometimes you may want to stop continue routing for messages that was filtered.
+To do this, you can use the xref:stop-eip.adoc[Stop] EIP as shown:
-The xref:filter-eip.adoc[Message Filter] EIP will add a property on
-the xref:latest@manual:ROOT:exchange.adoc[Exchange] that states if it was
filtered or not.
+[source,xml]
+----
+<route>
+ <from uri="direct:start"/>
+ <filter>
+ <method type="com.foo.MyBean" method="isGoldCustomer"/>
+ <to uri="mock:gold"/>
+ <stop/>
+ </filter>
+ <to uri="mock:all"/>
+</route>
+----
-The property has the key `Exchange.FILTER_MATCHED`, which has the String
-value of `CamelFilterMatched`. Its value is a boolean indicating `true`
-or `false`. If the value is `true` then the
xref:latest@manual:ROOT:exchange.adoc[Exchange]
-was routed in the filter block. This property will be visible within the
-xref:filter-eip.adoc[Message Filter] block who's
-xref:latest@manual:ROOT:predicate.adoc[Predicate] matches (value set to
`true`), and to the
-steps immediately following the xref:filter-eip.adoc[Message Filter]
-with the value set based on the results of the last
-xref:filter-eip.adoc[Message Filter]
xref:latest@manual:ROOT:predicate.adoc[Predicate]
-evaluated.
diff --git
a/core/camel-core-engine/src/main/docs/modules/eips/pages/from-eip.adoc
b/core/camel-core-engine/src/main/docs/modules/eips/pages/from-eip.adoc
index c87052a..8b19731 100644
--- a/core/camel-core-engine/src/main/docs/modules/eips/pages/from-eip.adoc
+++ b/core/camel-core-engine/src/main/docs/modules/eips/pages/from-eip.adoc
@@ -5,6 +5,11 @@
:since:
:supportLevel: Stable
+Every Camel xref:latest@manual:ROOT:routes.adoc[route] starts from an
xref:latest@manual:ROOT:endpoint.adoc[Endpoint]
+as the input (source) to the route.
+
+The From EIP is the input.
+
== Options
// eip options: START
@@ -17,24 +22,23 @@ The From EIP supports 1 options which are listed below:
|===
// eip options: END
-== Samples
+== Example
-Start a route with the File endpoint. Each file in the directory creates an
exchange that is put into the camel route.
-
-A camel route is started using from inside the configure method of the class
*RouteBuilder*
+In the route below the route starts from
+a xref:components::file-component.adoc[File] endpoint.
[source,java]
----
-from("file:c:/in")
+from("file:inbox")
+ .to("log:inbox");
----
-And examples in Spring XML Schema:
-
-The route is defined inside a CamelContext.
+And the same example in XML DSL:
[source,xml]
----
<route>
- <from uri="file:c:/in" />
+ <from uri="file:inbox"/>
+ <to uri="log:inbox"/>
</route>
----
