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 5061077 CAMEL-16861: Cleanup and update EIP docs
5061077 is described below
commit 506107708a138821c09dc647d698dc29d4b25e88
Author: Claus Ibsen <claus.ib...@gmail.com>
AuthorDate: Fri Sep 17 11:00:51 2021 +0200
CAMEL-16861: Cleanup and update EIP docs
---
.../main/docs/modules/eips/pages/delay-eip.adoc | 142 +++++++--------------
.../modules/eips/pages/durable-subscriber.adoc | 7 +-
.../docs/modules/eips/pages/dynamicRouter-eip.adoc | 122 +++++++-----------
.../modules/languages/pages/simple-language.adoc | 4 +-
4 files changed, 99 insertions(+), 176 deletions(-)
diff --git
a/core/camel-core-engine/src/main/docs/modules/eips/pages/delay-eip.adoc
b/core/camel-core-engine/src/main/docs/modules/eips/pages/delay-eip.adoc
index a667a51..dbd7922 100644
--- a/core/camel-core-engine/src/main/docs/modules/eips/pages/delay-eip.adoc
+++ b/core/camel-core-engine/src/main/docs/modules/eips/pages/delay-eip.adoc
@@ -19,22 +19,7 @@ The Delay EIP supports 3 options which are listed below:
|===
// eip options: END
-[NOTE]
-====
-The expression is a value in millis to wait from the current time, so the
expression should just be 3000.
-
-However you can use a long value for a fixed value to indicate the delay in
millis.
-
-See the Spring DSL samples for Delayer.
-====
-
-[CAUTION]
-.Using Delayer in Java DSL
-===
-See this ticket:
https://issues.apache.org/jira/browse/CAMEL-2654[https://issues.apache.org/jira/browse/CAMEL-2654]
-===
-
-== Samples
+== Example
The example below will delay all messages received on *seda:b* 1 second before
sending them to *mock:result*.
@@ -45,86 +30,74 @@ from("seda:b")
.to("mock:result");
----
-You can just delay things a fixed amount of time from the point at which the
delayer receives the message. For example to delay things 2 seconds
+And in XML:
-[source,java]
+[source,xml]
----
-delayer(2000)
+<route>
+ <from uri="seda:b"/>
+ <delay>
+ <constant>1000</constant>
+ </delay>
+ <to uri="mock:result"/>
+</route>
----
-The above assume that the delivery order is maintained and that the messages
are delivered in delay order. If you want to reorder the messages based on
delivery time, you can use the Resequencer with this pattern. For example
+The delayed value can be a dynamic
xref:latest@manual:ROOT:expression.adoc[Expression].
+
+For example to delay a random between 1 and 5 seconds, we can use
+the xref:components:languages:simple-language.adoc[Simple] language:
[source,java]
----
-from("activemq:someQueue")
- .resequencer(header("MyDeliveryTime"))
- .delay("MyRedeliveryTime")
- .to("activemq:aDelayedQueue");
+from("seda:b")
+ .delay(simple("${random(1000,5000)}"))
+ .to("mock:result");
----
-You can of course use many different Expression languages such as XPath,
XQuery, SQL or various Scripting Languages. For example to delay the message
for the time period specified in the header, use the following syntax:
+And in XML DSL:
-[source,java]
+[source,xml]
----
-from("activemq:someQueue")
- .delay(header("delayValue"))
- .to("activemq:aDelayedQueue");
+<route>
+ <from uri="seda:b"/>
+ <delay>
+ <simple>${random(1000,5000)}</simple>
+ </delay>
+ <to uri="mock:result"/>
+</route>
----
-And to delay processing using the Simple language you can use the following
DSL:
+You can also call a xref:components:languages:bean-language.adoc[Bean Method]
to compute the
+delayed value from Java code:
[source,java]
----
-from("activemq:someQueue")
- .delay(simple("${body.delayProperty}"))
- .to("activemq:aDelayedQueue");
+from("activemq:foo")
+ .delay().method("someBean", "computeDelay")
+ .to("activemq:bar");
----
-=== Spring DSL
-The sample below demonstrates the delay in Spring DSL:
+Then the bean would look something like this:
-[source,xml]
+[source,java]
----
-<bean id="myDelayBean" class="org.apache.camel.processor.MyDelayCalcBean"/>
-<bean id="exchangeAwareBean"
class="org.apache.camel.processor.ExchangeAwareDelayCalcBean"/>
-
-<camelContext xmlns="http://camel.apache.org/schema/spring";>
- <route>
- <from uri="seda:a"/>
- <delay>
- <header>MyDelay</header>
- </delay>
- <to uri="mock:result"/>
- </route>
- <route>
- <from uri="seda:b"/>
- <delay>
- <constant>1000</constant>
- </delay>
- <to uri="mock:result"/>
- </route>
- <route>
- <from uri="seda:c"/>
- <delay>
- <method ref="myDelayBean" method="delayMe"/>
- </delay>
- <to uri="mock:result"/>
- </route>
- <route>
- <from uri="seda:d"/>
- <delay>
- <method ref="exchangeAwareBean" method="delayMe"/>
- </delay>
- <to uri="mock:result"/>
- </route>
-</camelContext>
+public class SomeBean {
+ public long computeDelay() {
+ long delay = 0;
+ // use java code to compute a delay value in millis
+ return delay;
+ }
+}
----
== Asynchronous delaying
-You can let the Delayer use non blocking asynchronous delaying, which means
Camel will use a scheduler to schedule a task to be executed in the future. The
task will then continue routing. This allows the caller thread to not block and
be able to service other messages etc.
+You can let the Delayer use non-blocking asynchronous delaying,
+which means Camel will use scheduled thread pool (`ScheduledExecutorService`)
+to schedule a task to be executed in the future.
+This allows the caller thread to not block and be able to service other
messages.
-=== From Java DSL
You use the `asyncDelayed()` to enable the async behavior.
[source,java]
@@ -134,9 +107,7 @@ from("activemq:queue:foo")
.to("activemq:aDelayedQueue");
----
-=== From Spring XML
-
-You use the `asyncDelayed="true"` attribute to enable the async behavior.
+In XML DSL you use the `asyncDelayed` attribute to enable the async mode:
[source,xml]
----
@@ -149,26 +120,3 @@ You use the `asyncDelayed="true"` attribute to enable the
async behavior.
</route>
----
-== Creating a custom delay
-
-You can use an expression, such as calling a method on a bean, to determine
when to send a message using something like this
-
-[source,java]
-----
-from("activemq:foo").
- delay().method("someBean", "computeDelay").
- to("activemq:bar");
-----
-
-then the bean would look like this...
-
-[source,java]
-----
-public class SomeBean {
- public long computeDelay() {
- long delay = 0;
- // use java code to compute a delay value in millis
- return delay;
- }
-}
-----
diff --git
a/core/camel-core-engine/src/main/docs/modules/eips/pages/durable-subscriber.adoc
b/core/camel-core-engine/src/main/docs/modules/eips/pages/durable-subscriber.adoc
index faba184..d9d77c8 100644
---
a/core/camel-core-engine/src/main/docs/modules/eips/pages/durable-subscriber.adoc
+++
b/core/camel-core-engine/src/main/docs/modules/eips/pages/durable-subscriber.adoc
@@ -5,11 +5,14 @@ Camel supports the
https://www.enterpriseintegrationpatterns.com/patterns/messaging/DurableSubscription.html[Durable
Subscriber]
from the xref:enterprise-integration-patterns.adoc[EIP patterns] book.
-Camel supports the Durable Subscriber from the EIP patterns using components
such as the JMS or Kafka component which supports publish & subscribe using
topics with support for non-durable and durable subscribers.
+Camel supports the Durable Subscriber from the EIP patterns
+using components, such as the xref:components::jms-component.adoc[JMS] or
+xref:components::kafka-component.adoc[Kafka] component, which supports publish
& subscribe
+using topics with support for non-durable and durable subscribers.
image::eip/DurableSubscriptionSolution.gif[image]
-== Sample
+== Example
Here is a simple example of creating durable subscribers to a JMS topic
diff --git
a/core/camel-core-engine/src/main/docs/modules/eips/pages/dynamicRouter-eip.adoc
b/core/camel-core-engine/src/main/docs/modules/eips/pages/dynamicRouter-eip.adoc
index 77afb8f..2050ccc 100644
---
a/core/camel-core-engine/src/main/docs/modules/eips/pages/dynamicRouter-eip.adoc
+++
b/core/camel-core-engine/src/main/docs/modules/eips/pages/dynamicRouter-eip.adoc
@@ -7,33 +7,12 @@
The
http://www.enterpriseintegrationpatterns.com/DynamicRouter.html[Dynamic
-Router] from the EIP patterns
+Router] from the xref:enterprise-integration-patterns.adoc[EIP patterns]
allows you to route messages while avoiding the dependency of the router
on all possible destinations while maintaining its efficiency.
image::eip/DynamicRouter.gif[image]
-The `dynamicRouter` in the DSL is similar to
-a dynamic Routing Slip which evaluates the slip
-_on-the-fly_.
-
-WARNING: *Beware*
-You must ensure the expression used for the `dynamicRouter` such as a
-bean, will return `null` to indicate the end. Otherwise the
-`dynamicRouter` will keep repeating endlessly.
-
-[[DynamicRouter-DynamicRouterinCamel2.5onwards]]
-== Dynamic Router in Camel 2.5 onwards
-
-The Dynamic Router will set 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. (It's a slip
-because the Dynamic Router implementation is
-based on top of Routing Slip).
-
-TIP: See the `cacheSize` option for more details on _how much cache_ to use
depending on how many or few unique endpoints are used.
-
== Options
// eip options: START
@@ -48,8 +27,16 @@ The Dynamic Router EIP supports 3 options which are listed
below:
|===
// eip options: END
-[[DynamicRouter-JavaDSL]]
-== Java DSL
+== Dynamic Router
+
+The Dynamic Router is similar to the xref:routingSlip-eip.adoc[Routing Slip]
EIP,
+but with the slip evaluated dynamically _on-the-fly_. The
xref:routingSlip-eip.adoc[Routing Slip]
+on the other hand evaluates the slip only once in the beginning.
+
+The Dynamic Router sets the exchange property (`Exchange.SLIP_ENDPOINT`)
+with the current slip. This allows you to know how far we have processed in
the overall slip.
+
+== Example
In Java DSL you can use the `dynamicRouter` as shown below:
@@ -57,11 +44,24 @@ In Java DSL you can use the `dynamicRouter` as shown below:
----
from("direct:start")
// use a bean as the dynamic router
- .dynamicRouter(method(DynamicRouterTest.class, "slip"));
+ .dynamicRouter(method(MySlipBean.class, "slip"));
+----
+
+And in XML:
+
+[source,xml]
+----
+<route>
+ <from uri="direct:start"/>
+ <dynamicRouter>
+ <!-- use a method call on a bean as dynamic router -->
+ <method beanType="com.foo.MySlipBean" method="slip"/>
+ </dynamicRouter>
+</route>
----
-Which will leverage a xref:components::bean-component.adoc[Bean] to compute
the slip
-_on-the-fly_, which could be implemented as follows:
+Which will call a xref:components:languages:bean-language.adoc[Bean Method] to
compute the slip
+_on-the-fly_. The bean could be implemented as follows:
[source,java]
----
@@ -90,9 +90,16 @@ public String slip(String body) {
}
----
+WARNING: *Beware*
+You must ensure the expression used for the `dynamicRouter` such as a
+bean, will return `null` to indicate the end. Otherwise, the
+`dynamicRouter` will keep repeating endlessly.
+
+=== Thread safety beans
+
Mind that this example is only for show and tell. The current
implementation is not thread safe. You would have to store the state on
-the Exchange, to ensure thread safety, as shown
+the `Exchange`, to ensure thread safety, as shown
below:
[source,java]
@@ -134,45 +141,19 @@ public String slip(String body, @ExchangeProperties
Map<String, Object> properti
----
You could also store state as message headers, but they are not
-guaranteed to be preserved during routing, where as properties on the
-Exchange are. Although there was a bug in the method
-call expression, see the warning below.
-
-[[DynamicRouter-SpringXML]]
-== Spring XML
-
-The same example in Spring XML would be:
-
-[source,xml]
-----
-<bean id="mySlip" class="org.apache.camel.processor.DynamicRouterTest"/>
-
-<camelContext xmlns="http://camel.apache.org/schema/spring";>
- <route>
- <from uri="direct:start"/>
- <dynamicRouter>
- <!-- use a method call on a bean as dynamic router -->
- <method ref="mySlip" method="slip"/>
- </dynamicRouter>
- </route>
-
- <route>
- <from uri="direct:foo"/>
- <transform><constant>Bye World</constant></transform>
- </route>
-
-</camelContext>
-----
+guaranteed to be preserved during routing, whereas properties on the
+Exchange are.
-[[DynamicRouter-DynamicRouterannotation]]
== @DynamicRouter annotation
-You can also use the `@DynamicRouter` annotation. The `route` method would
+You can also use xref:latest@manual:ROOT:bean-integration.adoc[Bean
Integration] with the `@DynamicRouter` annotation,
+on a Java bean method.
+
+In the example below the `route` method would
then be invoked repeatedly as the message is processed dynamically. The
-idea is to return the next endpoint uri where to go. Return `null` to
-indicate the end. You can return multiple endpoints if you like, just as
-the Routing Slip, where each endpoint is
-separated by a delimiter.
+idea is to return the next endpoint uri where to go, and to return `null` to
end.
+You can return multiple endpoints if you like, just as
+the xref:routingSlip-eip.adoc[Routing Slip], where each endpoint is separated
by a comma.
[source,java]
----
@@ -181,21 +162,12 @@ public class MyDynamicRouter {
@Consume(uri = "activemq:foo")
@DynamicRouter
public String route(@XPath("/customer/id") String customerId,
@Header("Location") String location, Document body) {
- // query a database to find the best match of the endpoint based on
the input parameteres
+ // query a database to find the best match of the endpoint based on
the input parameters
// return the next endpoint uri, where to go. Return null to indicate
the end.
}
}
----
-In the above we can use the
-Parameter Binding Annotations
-to bind different parts of the Message to method
-parameters or use an Expression such as using
-xref:components:languages:xpath-language.adoc[XPath] or
xref:components:languages:xpath-language.adoc[XQuery].
-
-The method can be invoked in a number of ways as described in the
-Bean Integration such as
+The parameters on the `route` method is bound to information from the Exchange
using
+xref:latest@manual:ROOT:bean-binding.adoc[Bean Parameter Binding].
-* POJO Producing
-* Spring Remoting
-* xref:components::bean-component.adoc[Bean] component
diff --git
a/core/camel-core-languages/src/main/docs/modules/languages/pages/simple-language.adoc
b/core/camel-core-languages/src/main/docs/modules/languages/pages/simple-language.adoc
index 27e958e..294a4bb 100644
---
a/core/camel-core-languages/src/main/docs/modules/languages/pages/simple-language.adoc
+++
b/core/camel-core-languages/src/main/docs/modules/languages/pages/simple-language.adoc
@@ -199,10 +199,10 @@ constant field from Exchange as:
`org.apache.camel.Exchange.FILE_NAME`
|null |null |represents a *null*
-|random_(value)_ |Integer |returns a random Integer between 0 (included) and
_value_
+|random(value) |Integer |returns a random Integer between 0 (included) and
_value_
(excluded)
-|random_(min,max)_ |Integer |returns a random Integer between _min_ (included)
and
+|random(min,max) |Integer |returns a random Integer between _min_ (included)
and
_max_ (excluded)
|collate(group) |List |The collate function iterates the message body and
groups
