[camel] branch main updated: CAMEL-17811: documentation - Explain better the difference between kamelet eip vs to kamelet

[da...@apache.org]

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 5468762  CAMEL-17811: documentation - Explain better the difference between kamelet eip vs to kamelet
5468762 is described below

commit 5468762f17191f572ab6572800e6c8f829071187
Author: Claus Ibsen <cl...@gmail.com>
AuthorDate: Fri Mar 18 10:06:38 2022 +0100

    CAMEL-17811: documentation - Explain better the difference between kamelet eip vs to kamelet
---
 .../main/docs/modules/eips/pages/kamelet-eip.adoc  | 55 +++++++++++++++++++++-
 .../resources/org/apache/camel/model/kamelet.json  |  2 +-
 .../org/apache/camel/model/KameletDefinition.java  |  2 +-
 3 files changed, 55 insertions(+), 4 deletions(-)

diff --git a/core/camel-core-engine/src/main/docs/modules/eips/pages/kamelet-eip.adoc b/core/camel-core-engine/src/main/docs/modules/eips/pages/kamelet-eip.adoc
index cae55df..6d2270f 100644
--- a/core/camel-core-engine/src/main/docs/modules/eips/pages/kamelet-eip.adoc
+++ b/core/camel-core-engine/src/main/docs/modules/eips/pages/kamelet-eip.adoc
@@ -1,14 +1,65 @@
 = Kamelet EIP
 :doctitle: Kamelet
 :shortname: kamelet
-:description: To call Kamelets
+:description: To call Kamelets in special situations
 :since: 
 :supportlevel: Stable
 
 Kamelets (Kamel route snippets) allow users to connect to external systems via a simplified interface,
 hiding all the low level details about how those connections are implemented.
 
-The Kamelet EIP allows calling Kamelets (i.e. xref:manual::route-template.adoc[Route Template]).
+[IMPORTANT]
+By default, calling kamelets should be done as xref:message-endpoint.adoc[endpoints] with
+the xref:components::kamelet-component.adoc[kamelet] component, such as `to("kamelet:mykamelet")`.
+
+The Kamelet EIP allows calling Kamelets (i.e. xref:manual::route-template.adoc[Route Template]),
+**for special use-cases**.
+
+When a Kamelet is designed for a special use-case such as aggregating messages, and returning
+a response message only when a group of aggregated message is completed. In other words the kamelet
+does not return a response message for every incoming message. In special situations like these,
+then you **must** use this Kamelet EIP instead of using the xref:components::kamelet-component.adoc[kamelet] component.
+
+Given the following Kamelet (as a route template):
+
+[source,java]
+----
+routeTemplate("my-aggregate")
+        .templateParameter("count")
+        .from("kamelet:source")
+        .aggregate(constant(true))
+            .completionSize("{{count}}")
+            .aggregationStrategy(AggregationStrategies.string(","))
+            .to("log:aggregate")
+            .to("kamelet:sink")
+        .end();
+----
+
+NOTE: Note how the route template above uses _kamelet:sink_ as a special endpoint
+to send out a result message. This is only done when the xref:aggregate-eip.adoc[Aggregate EIP]
+has completed a group of messages.
+
+And the following route using the kamelet:
+
+[source,java]
+----
+from("direct:start")
+    // this is not possible, you must use Kamelet EIP instead
+    .to("kamelet:my-aggregate?count=5")
+    .to("log:info")
+    .to("mock:result");
+----
+
+Then this does not work, instead you **must** use Kamelet EIP instead:
+
+[source,java]
+----
+from("direct:start")
+    .kamelet("my-aggregate?count=5")
+    .to("log:info")
+    .to("mock:result");
+----
+
 When calling a Kamelet you may just refer to the name (template id) of the Kamelet in the EIP as shown below:
 
 == Options
diff --git a/core/camel-core-model/src/generated/resources/org/apache/camel/model/kamelet.json b/core/camel-core-model/src/generated/resources/org/apache/camel/model/kamelet.json
index cb3ab81..b5fc1e7 100644
--- a/core/camel-core-model/src/generated/resources/org/apache/camel/model/kamelet.json
+++ b/core/camel-core-model/src/generated/resources/org/apache/camel/model/kamelet.json
@@ -3,7 +3,7 @@
     "kind": "model",
     "name": "kamelet",
     "title": "Kamelet",
-    "description": "To call Kamelets",
+    "description": "To call Kamelets in special situations",
     "deprecated": false,
     "label": "eip,routing",
     "javaType": "org.apache.camel.model.KameletDefinition",
diff --git a/core/camel-core-model/src/main/java/org/apache/camel/model/KameletDefinition.java b/core/camel-core-model/src/main/java/org/apache/camel/model/KameletDefinition.java
index bca46fa..a6083ca 100644
--- a/core/camel-core-model/src/main/java/org/apache/camel/model/KameletDefinition.java
+++ b/core/camel-core-model/src/main/java/org/apache/camel/model/KameletDefinition.java
@@ -27,7 +27,7 @@ import javax.xml.bind.annotation.XmlRootElement;
 import org.apache.camel.spi.Metadata;
 
 /**
- * To call Kamelets
+ * To call Kamelets in special situations
  */
 @Metadata(label = "eip,routing")
 @XmlRootElement(name = "kamelet")