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 3f28d4e CAMEL-16861: Cleanup and update EIP docs
3f28d4e is described below
commit 3f28d4e537d51040a130dd5ab11831d112efe1a8
Author: Claus Ibsen <claus.ib...@gmail.com>
AuthorDate: Wed Oct 20 19:20:45 2021 +0200
CAMEL-16861: Cleanup and update EIP docs
---
.../docs/modules/eips/pages/message-endpoint.adoc | 4 +
.../src/main/docs/modules/eips/pages/to-eip.adoc | 78 ++++++----------
.../src/main/docs/modules/eips/pages/toD-eip.adoc | 101 ++++++++++++++-------
3 files changed, 97 insertions(+), 86 deletions(-)
diff --git
a/core/camel-core-engine/src/main/docs/modules/eips/pages/message-endpoint.adoc
b/core/camel-core-engine/src/main/docs/modules/eips/pages/message-endpoint.adoc
index 77d0a74..63fed17 100644
---
a/core/camel-core-engine/src/main/docs/modules/eips/pages/message-endpoint.adoc
+++
b/core/camel-core-engine/src/main/docs/modules/eips/pages/message-endpoint.adoc
@@ -7,8 +7,12 @@ patterns] using the
https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/Endpoint.html[Endpoint]
interface.
+How does an application connect to a messaging channel to send and receive
messages?
+
image::eip/MessageEndpointSolution.gif[image]
+Connect an application to a messaging channel using a Message Endpoint, a
client of the messaging system that the application can then use to send or
receive messages.
+
When using the xref:latest@manual:ROOT:dsl.adoc[DSL] to create
xref:latest@manual:ROOT:routes.adoc[Routes] you
typically refer to Message Endpoints by their
xref:latest@manual:ROOT:uris.adoc[URIs]
rather than directly using the
diff --git
a/core/camel-core-engine/src/main/docs/modules/eips/pages/to-eip.adoc
b/core/camel-core-engine/src/main/docs/modules/eips/pages/to-eip.adoc
index f4e3403..a316445 100644
--- a/core/camel-core-engine/src/main/docs/modules/eips/pages/to-eip.adoc
+++ b/core/camel-core-engine/src/main/docs/modules/eips/pages/to-eip.adoc
@@ -5,14 +5,22 @@
:since:
:supportlevel: Stable
-See message related documentation
+Camel supports the
+http://www.enterpriseintegrationpatterns.com/MessageEndpoint.html[Message
+Endpoint] from the xref:enterprise-integration-patterns.adoc[EIP
+patterns] using the
+https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/Endpoint.html[Endpoint]
+interface.
-* xref:message.adoc[Message]
-* xref:message-bus.adoc[Message Bus]
-* xref:message-channel.adoc[Message Channel]
-* xref:message-endpoint.adoc[Message Endpoint]
-* xref:message-router.adoc[Message Router]
-* xref:message-translator.adoc[Message Translator]
+How does an application connect to a messaging channel to send and receive
messages?
+
+image::eip/MessageEndpointSolution.gif[image]
+
+Connect an application to a messaging channel using a Message Endpoint, a
client of the messaging system that the application can then use to send or
receive messages.
+
+In Camel the To EIP is used for sending xref:message.adoc[messages] to static
xref:message-endpoint.adoc[endpoints].
+
+The To and xref:toD-eip.adoc[ToD] EIPs are the most common patterns to use in
Camel xref:latest@manual:ROOT:routes.adoc[routes].
== Options
@@ -20,7 +28,17 @@ See message related documentation
include::partial$eip-options.adoc[]
// eip options: END
-== Example
+=== Different between To and ToD
+
+The `to` is used for sending messages to a static
xref:message-endpoint.adoc[endpoint].
+In other words `to` sends message only to the *same* endpoint.
+
+The `toD` is used for sending message to a dynamic
xref:message-endpoint.adoc[endpoint].
+The dynamic endpoint is evaluated _on-demand_ by an
xref:latest@manual:ROOT:expression.adoc[Expression].
+By default, the xref:components:languages:simple-language.adoc[Simple]
expression is used to compute
+the dynamic endpoint URI.
+
+== Using To
The following example route demonstrates the use of a
xref:components::file-component.adoc[File] consumer endpoint and a
xref:components::jms-component.adoc[JMS] producer endpoint,
by their xref:latest@manual:ROOT:uris.adoc[URIs]:
@@ -41,47 +59,3 @@ And in XML:
</route>
----
-=== Using Exchange Pattern
-
-Instead of using `inOnly` and `inOut` you may want to keep using `to`
-where you can specify the exchange pattern as shown:
-
-[source,java]
-----
-from("direct:startInOnly")
- .to(ExchangePattern.InOnly, "bean:process");
-
-from("direct:startInOut")
- .to(ExchangePattern.InOut, "bean:process");
-----
-
-
-And here is how to do it in XML:
-
-[source,xml]
-----
-<route>
- <from uri="direct:startInOnly"/>
- <inOnly uri="bean:process"/>
-</route>
-
-<route>
- <from uri="direct:startInOut"/>
- <inOut uri="bean:process"/>
-</route>
-----
-
-And here we use `<to>` with the `pattern` attribute to set the exchange
pattern:
-
-[source,xml]
-----
-<route>
- <from uri="direct:startInOnly"/>
- <to pattern="InOnly" uri="bean:process"/>
-</route>
-
-<route>
- <from uri="direct:startInOut"/>
- <to pattern="InOut" uri="bean:process"/>
-</route>
-----
diff --git
a/core/camel-core-engine/src/main/docs/modules/eips/pages/toD-eip.adoc
b/core/camel-core-engine/src/main/docs/modules/eips/pages/toD-eip.adoc
index dae0c8d..f1c824f 100644
--- a/core/camel-core-engine/src/main/docs/modules/eips/pages/toD-eip.adoc
+++ b/core/camel-core-engine/src/main/docs/modules/eips/pages/toD-eip.adoc
@@ -5,11 +5,22 @@
:since:
:supportlevel: Stable
-There is a new `.toD` / `<toD>` that allows to send a message to a dynamic
-computed xref:latest@manual:ROOT:endpoint.adoc[Endpoint] using one or
-more xref:latest@manual:ROOT:expression.adoc[Expression] that are concat
together. By
-default the xref:components:languages:simple-language.adoc[Simple] language is
used to compute
-the endpoint.
+Camel supports the
+http://www.enterpriseintegrationpatterns.com/MessageEndpoint.html[Message
+Endpoint] from the xref:enterprise-integration-patterns.adoc[EIP
+patterns] using the
+https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/Endpoint.html[Endpoint]
+interface.
+
+How does an application connect to a messaging channel to send and receive
messages?
+
+image::eip/MessageEndpointSolution.gif[image]
+
+Connect an application to a messaging channel using a Message Endpoint, a
client of the messaging system that the application can then use to send or
receive messages.
+
+In Camel the ToD EIP is used for sending xref:message.adoc[messages] to
dynamic xref:message-endpoint.adoc[endpoints].
+
+The xref:to-eip.adoc[To] and ToD EIPs are the most common patterns to use in
Camel xref:latest@manual:ROOT:routes.adoc[routes].
== Options
@@ -17,10 +28,20 @@ the endpoint.
include::partial$eip-options.adoc[]
// eip options: END
-== Samples
+=== Different between To and ToD
+
+The `to` is used for sending messages to a static
xref:message-endpoint.adoc[endpoint].
+In other words `to` sends message only to the *same* endpoint.
+
+The `toD` is used for sending message to a dynamic
xref:message-endpoint.adoc[endpoint].
+The dynamic endpoint is evaluated _on-demand_ by an
xref:latest@manual:ROOT:expression.adoc[Expression].
+By default, the xref:components:languages:simple-language.adoc[Simple]
expression is used to compute
+the dynamic endpoint URI.
+
+== Using ToD
-For example to send a message to a endpoint defined by a
-header you can do as shown below:
+For example to send a message to an endpoint which is dynamic determined by a
+xref:message.adoc[message header] you can do as shown below:
[source,java]
----
@@ -38,8 +59,8 @@ And in XML:
</route>
----
-You can also prefix the uri with a value because by default the uri is
-evaluated using the xref:components:languages:simple-language.adoc[Simple]
language
+You can also prefix the uri with a value because the endpoint
xref:latest@manual:ROOT:uris.adoc[URI] is
+evaluated using the xref:components:languages:simple-language.adoc[Simple]
language:
[source,java]
----
@@ -57,17 +78,26 @@ And in XML:
</route>
----
-In the example above we compute an endpoint that has prefix "mock:" and
+In the example above we compute the dynamic endpoint with a prefix "mock:" and
then the header foo is appended. So for example if the header foo has
value order, then the endpoint is computed as "mock:order".
-You can also use another language than
xref:components:languages:simple-language.adoc[Simple] such
-as xref:components:languages:xpath-language.adoc[XPath] - this requires to
prefix with language: as
-shown below (simple language is the default language). If you do not
-specify language: then the endpoint is a component name. And in some
+=== Using other languages with toD
+
+You can also use other languages such as
xref:components:languages:xpath-language.adoc[XPath].
+Doing this requires to start with `language:` as shown below. If you do not
+specify `language:` then the endpoint is a component name. And in some
cases there is both a component and language with the same name such as
xquery.
+[source,java]
+----
+from("direct:start")
+ .toD("language:xpath:/order/@uri");
+----
+
+And in XML:
+
[source,xml]
----
<route>
@@ -76,15 +106,7 @@ xquery.
</route>
----
-This is done by specifying the name of the language followed by a colon.
-
-[source,java]
-----
-from("direct:start")
- .toD("language:xpath:/order/@uri");
-----
-
-== Avoid creating endless dynamic endpoints which takes up resources
+=== Avoid creating endless dynamic endpoints which takes up resources
When using dynamic computed endpoints with `toD` then you may compute a lot of
dynamic endpoints,
which results in an overhead of resources in use, by each dynamic endpoint
uri, and its associated producer.
@@ -98,7 +120,8 @@ from("direct:login")
----
In the example above then the parameter `userid` is dynamic computed, and
would result in one instance of endpoint and producer
-for each different userid. To avoid having too many dynamic endpoints you can
configure `toD` to reduce its cache size, for example:
+for each different userid. To avoid having too many dynamic endpoints you can
configure `toD` to reduce its cache size, for example
+to use a cache size of 10:
[source,java]
----
@@ -106,12 +129,22 @@ from("direct:login")
.toD("http:myloginserver:8080/login?userid=${header.userName}", 10);
----
-where the cache is 10. *Important* this will only reduce the endpoint cache of
the `toD` that has a chance
-of being reused in case a message is routed with the same `userName` header.
Therefore reducing the cache size
-will not solve the _endless dynamic endpoints_ problem. Instead you should use
static endpoints with `to` and
+And in XML:
+
+[source,xml]
+----
+<route>
+ <from uri="direct:login"/>
+ <toD uri="http:myloginserver:8080/login?userid=${header.userName}"
cacheSize="10"/>
+</route>
+----
+
+IMPORTANT: this will only reduce the endpoint cache of the `toD` that has a
chance
+of being reused in case a message is routed with the same `userName` header.
Therefore, reducing the cache size
+will not solve the _endless dynamic endpoint`s_ problem. Instead, you should
use static endpoints with `to` and
provide the dynamic parts in Camel message headers (if possible).
-=== Using static endpoints
+==== Using static endpoints to avoid endless dynamic endpoints
In the example above then the parameter `userid` is dynamic computed, and
would result in one instance of endpoint and producer
for each different userid. To avoid having too dynamic endpoints you use a
single static endpoint and use headers to provide the dynamic parts:
@@ -124,10 +157,10 @@ from("direct:login")
.toD("http:myloginserver:8080");
----
-However, you can use its optimised components for `toD` that can _solve_ this
out of the box,
+However, you can use optimised components for `toD` that can _solve_ this out
of the box,
as documented next.
-== Using optimised components
+=== Using optimised components with toD
A better solution would be if the HTTP component could be optimised to handle
the variations of dynamic computed endpoint uris.
This is with among the following components, which have been optimised for
`toD`:
@@ -155,8 +188,8 @@ A number of non-HTTP components has been optimised as well:
For the optimisation to work, then:
-. The optimisation is detected and activated during startup of the Camel
routes with `toD`'s.
-. The dynamic uri in `toD` must provide the component name as either static or
resolved via property placeholders.
+. The optimisation is detected and activated during startup of the Camel
routes with `toD`.
+. The dynamic uri in `toD` must provide the component name as either static or
resolved via xref:latest@manual:ROOT:using-propertyplaceholder.adoc[property
placeholders].
. The supported components must be on the classpath.
The HTTP based components will be optimised to use the same hostname:port for
each endpoint, and the dynamic values
@@ -170,7 +203,7 @@ from("direct:login")
.toD("http:myloginserver:8080/login?userid=${header.userName}");
----
-will essentially be optimised to (pseudo route):
+Will essentially be optimised to (pseudo route):
[source,java]
----
