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 385fd5c CAMEL-16861: Cleanup and update EIP docs
385fd5c is described below
commit 385fd5c8fa563af71aa114cb4e40a4294d352118
Author: Claus Ibsen <claus.ib...@gmail.com>
AuthorDate: Tue Oct 12 16:25:06 2021 +0200
CAMEL-16861: Cleanup and update EIP docs
---
.../docs/modules/eips/pages/recipientList-eip.adoc | 15 ++-
.../docs/modules/eips/pages/routingSlip-eip.adoc | 117 +++++++++++----------
2 files changed, 69 insertions(+), 63 deletions(-)
diff --git
a/core/camel-core-engine/src/main/docs/modules/eips/pages/recipientList-eip.adoc
b/core/camel-core-engine/src/main/docs/modules/eips/pages/recipientList-eip.adoc
index e0c6e13..dc83f77 100644
---
a/core/camel-core-engine/src/main/docs/modules/eips/pages/recipientList-eip.adoc
+++
b/core/camel-core-engine/src/main/docs/modules/eips/pages/recipientList-eip.adoc
@@ -46,7 +46,7 @@ The Recipient List EIP has many features and is based on the
xref:multicast-eip.
For example the Recipient List EIP is capable of aggregating each message into
a single
_response_ message as the result after the Recipient List EIP.
-=== Using static Recipient List
+=== Using Static Recipient List
The following example shows how to route a request from an input queue:a
endpoint
to a static list of destinations, using `constant`:
@@ -69,7 +69,7 @@ And in XML:
</route>
----
-=== Using dynamic Recipient List
+=== Using Dynamic Recipient List
Usually one of the main reasons for using the Recipient List pattern is that
the list of recipients is dynamic and
calculated at runtime.
@@ -167,13 +167,12 @@ And in XML it is an attribute on `<recipientList>`:
==== Using custom thread pool
A thread pool is only used for `parallelProcessing`. You supply your own
custom thread pool via the `ExecutorServiceStrategy` (see Camel's Threading
Model),
-the same way you would do it for the `aggregationStrategy`. By default Camel
uses a thread pool with 10 threads (subject to change in future versions).
+the same way you would do it for the `aggregationStrategy`. By default, Camel
uses a thread pool with 10 threads (subject to change in future versions).
-The Multicast EIP will by default continue to process
-the entire exchange even in case one of the
-multicasted messages will throw an exception during routing.
+The Recipient List EIP will by default continue to process the entire exchange
even in case one of the
+sub messages will throw an exception during routing.
-For example if you want to multicast to 3 destinations and the 2nd
+For example if you want to route to 3 destinations and the 2nd
destination fails by an exception. What Camel does by default is to
process the remainder destinations. You have the chance to deal with the
exception
when aggregating using an `AggregationStrategy`.
@@ -236,7 +235,7 @@ And using XML DSL you specify it as follows:
=== Ignore invalid endpoints
-The Recipient List now supports `ignoreInvalidEndpoints` (like
xref:routingSlip-eip.adoc[Routing Slip] EIP).
+The Recipient List supports `ignoreInvalidEndpoints` (like
xref:routingSlip-eip.adoc[Routing Slip] EIP).
You can use it to skip endpoints which are invalid.
[source,java]
diff --git
a/core/camel-core-engine/src/main/docs/modules/eips/pages/routingSlip-eip.adoc
b/core/camel-core-engine/src/main/docs/modules/eips/pages/routingSlip-eip.adoc
index b11942d..0438f64 100644
---
a/core/camel-core-engine/src/main/docs/modules/eips/pages/routingSlip-eip.adoc
+++
b/core/camel-core-engine/src/main/docs/modules/eips/pages/routingSlip-eip.adoc
@@ -5,9 +5,15 @@
:since:
:supportlevel: Stable
+Camel supports the
+https://www.enterpriseintegrationpatterns.com/patterns/messaging/RoutingTable.html[Routing
Slip]
+from the xref:enterprise-integration-patterns.adoc[EIP patterns].
+
+How do we route a message consecutively through a series of processing steps
when the sequence of steps is not known at design-time and may vary for each
message?
+
image::eip/RoutingTableSimple.gif[image]
-TIP: See the `cacheSize` option for more details on _how much cache_ to use
depending on how many or few unique endpoints are used.
+Attach a Routing Slip to each message, specifying the sequence of processing
steps. Wrap each component with a special message router that reads the Routing
Slip and routes the message to the next component in the list.
== Options
@@ -15,93 +21,94 @@ TIP: See the `cacheSize` option for more details on _how
much cache_ to use depe
include::partial$eip-options.adoc[]
// eip options: END
-== Example
-The following route will take any messages sent to the Apache ActiveMQ queue
SomeQueue and pass them into the Routing Slip pattern.
+TIP: See the `cacheSize` option for more details on _how much cache_ to use
depending on how many or few unique endpoints are used.
-[source,java]
----------------------
-from("activemq:SomeQueue")
- .routingSlip("aRoutingSlipHeader");
----------------------
+== Exchange properties
-Messages will be checked for the existence of the `aRoutingSlipHeader` header.
-The value of this header should be a comma-delimited list of endpoint URIs you
wish the message to be routed to.
-The Message will be routed in a pipeline fashion, i.e., one after the other.
The Routing Slip sets a property, `Exchange.SLIP_ENDPOINT`, on the Exchange
which contains the current endpoint as it advanced though the slip. This allows
you to _know_ how far we have processed in the slip.
+The following properties are set on each Exchange that are sent by the routing
slip:
-The Routing Slip will compute the slip *beforehand* which means, the slip is
only computed once. If you need to compute the slip _on-the-fly_ then use the
Dynamic Router pattern instead.
+[width="100%",cols="3,1m,6",options="header"]
+|=======================================================================
+| Property | Type | Description
+| `CamelToEndpoint` | `String` | Uri of the `Endpoint` that the message was
sent to.
+| `CamelSlipEndpoint` | `String` | Uri of the `Endpoint` that the message was
sent to.
+|=======================================================================
-== Configuration Options
-Here we set the header name and the URI delimiter to something different.
+== Using Routing Slip
-#=== Using the Fluent Builders
-[source,java]
----------------------
-from("direct:c").routingSlip(header("aRoutingSlipHeader"), "#");
----------------------
+The Routing Slip EIP allows to route a message through a series of
xref:latest@manual:ROOT:endpoint.adoc[endpoints] (the slip).
-#=== Using the Spring XML Extensions
+There can be 1 or more endpoint xref:latest@manual:ROOT:uris.adoc[uris] in the
slip.
-[source,xml]
----------------------
-<camelContext id="buildRoutingSlip"
xmlns="http://activemq.apache.org/camel/schema/spring";>
- <route>
- <from uri="direct:c"/>
- <routingSlip uriDelimiter="#">
- <header>aRoutingSlipHeader</header>
- </routingSlip>
- </route>
-</camelContext>
----------------------
+TIP: A slip can be empty, meaning that the message will not be routed anywhere.
-== Ignore Invalid Endpoints
+The following route will take any messages sent to the Apache ActiveMQ queue
cheese
+and use the header with key "whereTo" that is used to compute the slip
(endpoint xref:latest@manual:ROOT:uris.adoc[uris]).
-The Routing Slip supports ignoreInvalidEndpoints which the Recipient List also
supports. You can use it to skip endpoints which are invalid.
[source,java]
---------------------
-from("direct:a")
- .routingSlip("myHeader")
- .ignoreInvalidEndpoints();
+from("activemq:cheese")
+ .routingSlip(header("whereTo"));
---------------------
-And in Spring XML its an attribute on the recipient list tag:
+The value of the header ("whereTo") should be a comma-delimited string of
endpoint URIs you wish the message to be routed to.
+The message will be routed in a xref:pipeline-eip.adoc[pipeline] fashion,
i.e., one after the other.
+
+The Routing Slip sets a property, `Exchange.SLIP_ENDPOINT`, on the `Exchange`
which contains the
+current endpoint as it advanced though the slip. This allows you to _know_ how
far we have processed in the slip.
+
+The Routing Slip will compute the slip *beforehand* which means,
+the slip is only computed once. If you need to compute the slip _on-the-fly_
then use the xref:dynamicRouter-eip.adoc[Dynamic Router] EIP instead.
+
+The same example in XML is simply just:
[source,xml]
----------------------
+----
<route>
- <from uri="direct:a"/>
- <routingSlip ignoreInvalidEndpoints="true"/>
- <header>myHeader</header>
+ <from uri="activemq:cheese"/>
+ <routingSlip>
+ <header>whereTo</header>
</routingSlip>
</route>
----------------------
+----
+
+=== How is the slip computed
+
+The Routing Slip uses an xref:latest@manual:ROOT:expression.adoc[Expression]
to compute the value for the slip.
+The result of the expression can be one of:
-Then let's say the myHeader contains the following two endpoints
direct:foo,xxx:bar. The first endpoint is valid and works. However the second
endpoint is invalid and will just be ignored. Camel logs at INFO level, so you
can see why the endpoint was invalid.
+- `String`
+- `Collection`
+- `Iterator` or `Iterable`
+- Array
-== Expression Support
+If the value is a `String` then the `uriDelimiter` is used to split the string
into multiple uris.
+The default delimiter is comma, but can be re-configured.
-The Routing Slip supports to take the expression parameter as the Recipient
List does. You can tell Camel the expression that you want to use to get the
routing slip.
+=== Ignore Invalid Endpoints
+
+The Routing Slip supports `ignoreInvalidEndpoints` (like
xref:recipientList-eip.adoc[Recipient List] EIP).
+You can use it to skip endpoints which are invalid.
[source,java]
---------------------
-from("direct:a")
- .routingSlip(header("myHeader"))
- .ignoreInvalidEndpoints();
+from("direct:start")
+ .routingSlip("myHeader").ignoreInvalidEndpoints();
---------------------
-And in Spring XML its an attribute on the recipient list tag.
+And in XML DSL it is an attribute on `<routingSlip>`:
+
[source,xml]
---------------------
<route>
- <from uri="direct:a"/>
- <!--NOTE from Camel 2.4.0, you need to specify the expression element inside
of the routingSlip element -->
+ <from uri="direct:start"/>
<routingSlip ignoreInvalidEndpoints="true">
<header>myHeader</header>
</routingSlip>
</route>
---------------------
-== Further Examples
-For further examples of this pattern in use you could look at the routing slip
test cases.
+Then let us say the `myHeader` contains the following two endpoints
`direct:foo,xxx:bar`.
+The first endpoint is valid and works. However, the second one is invalid and
will just be ignored.
+Camel logs at DEBUG level about it, so you can see why the endpoint was
invalid.
-== Using This Pattern
-If you would like to use this EIP Pattern then please read the Getting
Started, you may also find the Architecture useful particularly the description
of Endpoint and URIs. Then you could try out some of the Examples first before
trying this pattern out.
