This is an automated email from the ASF dual-hosted git repository.

pcongiusti pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-k.git


The following commit(s) were added to refs/heads/main by this push:
     new a0ec1705d chore(docs): Add Kamelet data types documentation
a0ec1705d is described below

commit a0ec1705d8410845a8f6cd6057953e8dd0a685f3
Author: Christoph Deppisch <[email protected]>
AuthorDate: Fri Jul 14 11:13:37 2023 +0200

    chore(docs): Add Kamelet data types documentation
---
 docs/modules/ROOT/pages/kamelets/kamelets-dev.adoc | 145 ++++++++++++++++++++-
 .../modules/ROOT/pages/kamelets/kamelets-user.adoc |  96 ++++++++++++++
 2 files changed, 237 insertions(+), 4 deletions(-)

diff --git a/docs/modules/ROOT/pages/kamelets/kamelets-dev.adoc 
b/docs/modules/ROOT/pages/kamelets/kamelets-dev.adoc
index 992c343fc..785408699 100644
--- a/docs/modules/ROOT/pages/kamelets/kamelets-dev.adoc
+++ b/docs/modules/ROOT/pages/kamelets/kamelets-dev.adoc
@@ -331,6 +331,144 @@ If everything goes right, you should get some tweets in 
the logs after the integ
 
 Refer to the xref:kamelets/kamelets-user.adoc[Kamelets User Guide] for more 
information on how to use it in different contexts (like Knative, Kafka, etc.).
 
+== Kamelet data types
+
+A Kamelet usually encapsulates a specific functionality and serves a very 
opinionated use case with well-defined input parameters and outcome.
+
+In order to enhance the Kamelet interoperability with other components the 
Kamelet may specify one to many data types for input, output and error 
scenarios.
+The declaration of supported Kamelet data types helps users to incorporate the 
Kamelet into their specific applications.
+
+When referencing a Kamelet users may choose from a list of supported 
input/output data types in order to gain best fit for the individual use case.
+
+Following from that each Kamelet may declare all supported input/output data 
types each of them providing additional information like header names, content 
type, content schema and so on.
+
+.my-sample-source.kamelet.yaml
+[source,yaml]
+----
+apiVersion: camel.apache.org/v1
+kind: Kamelet
+metadata:
+  name: my-sample-source
+  labels:
+    camel.apache.org/kamelet.type: "source"
+spec:
+  definition:
+# ...
+  dataTypes:
+    out: # <1>
+      default: application-json # <2>
+      headers:
+        MySpecialCamelHeaderName: # <3>
+          type: string
+          description: Some specific header
+      types: # <4>
+        application-json:
+          description: Output type as Json object
+          mediaType: application/json
+          schema: # <5>
+            type: object
+            description: The Json object representing the my-sample source 
output
+            properties:
+              # ...
+          dependencies: # <6>
+            - "camel:jackson"
+        text-plain:
+          description: Output type as plain text
+          mediaType: text/plain
+  template:
+    from:
+      uri: ...
+      steps:
+        - to: "kamelet:sink"
+----
+<1> Declared output data types of this Kamelet source
+<2> The output data type used by default
+<3> Declaration of output headers with header name, type and description 
information
+<4> List of supported output types
+<5> Optional Json schema describing the `application-json` data type
+<6> Optional list of additional dependencies that are required by the data 
type.
+
+The sample Kamelet above declares two supported output data types 
`application-json` and `text-plain`.
+Each declared data type is backed by a specific Apache Camel 
https://camel.apache.org/manual/transformer.html[transformer] implementation 
that is capable of producing the specific output.
+The respective transformer implementation may be provided by the Kamelet as a 
utility extension or by the underlying Apache Camel component.
+
+As a result the user may now choose the output data type when referencing the 
Kamelet in a binding.
+
+.my-sample-source-binding.yaml
+[source,yaml]
+----
+apiVersion: camel.apache.org/v1
+kind: Pipe
+metadata:
+  name: my-sample-source-binding
+spec:
+  source:
+    ref:
+      kind: Kamelet
+      apiVersion: camel.apache.org/v1
+      name: my-sample-source
+    data-types: # <1>
+      out:
+        format: text-plain # <2>
+  sink:
+    uri: "log:info"
+----
+<1> Chose the output data type on the Kamelet source reference in a Pipe.
+<2> Select `text-plain` as an output data type of the `my-sample-source` 
Kamelet.
+
+The very same concept of data types can also be used on Kamelet sinks and 
input data types.
+As soon as the user chooses a specific input data type for a Kamelet the Pipe 
processing will try to resolve a matching transformer implementation and apply 
its logic.
+
+You may also use a `data-type-action` Kamelet in your Pipe binding in order to 
apply a specific data type transformation at any step.
+
+.my-sample-source-binding.yaml
+[source,yaml]
+----
+apiVersion: camel.apache.org/v1
+kind: Pipe
+metadata:
+  name: my-sample-source-binding
+spec:
+  source:
+    ref:
+      kind: Kamelet
+      apiVersion: camel.apache.org/v1
+      name: my-sample-source
+    data-types:
+      out:
+        format: application-json # <1>
+  steps:
+    - ref:
+        kind: Kamelet
+        apiVersion: camel.apache.org/v1alpha1
+        name: json-deserialize-action # <2>
+    - ref:
+        kind: Kamelet
+        apiVersion: camel.apache.org/v1alpha1
+        name: resolve-pojo-schema-action # <3>
+      properties:
+        mimeType: "avro/binary"
+        schema: >
+          { "name": "User", "type": "record", "namespace": "demo.kamelets", 
"fields": [{ "name": "id", "type": "string" }, { "name": "firstname", "type": 
"string" }, { "name": "lastname", "type": "string" }, { "name": "age", "type": 
"int" }] }
+    - ref:
+        kind: Kamelet
+        apiVersion: camel.apache.org/v1alpha1
+        name: data-type-action # <4>
+      properties:
+        scheme: "camel"
+        format: "avro-binary"
+  sink:
+    uri: "log:info"
+----
+<1> Chose the output data `application-json` type on the Kamelet source.
+<2> Deserialize the Json object with `json-deserialize-action`.
+<3> Declare a Avro schema
+<4> Use the `data-type-action` Kamelet to transform the Json object into Avro 
using the formerly declared schema
+
+The Pipe in the sample above uses a combination of Kamelet output data type, 
Json deserialization and Avro binary data type to transform the Kamelet source 
output.
+
+All referenced data types are backed by a specific transformer implementation 
either provided by the Kamelet itself or by pure Apache Camel functionality.
+
 == Creating a complex Kamelet
 
 We're now going to create a Kamelet with a high degree of complexity, to show 
how the Kamelet model can be used also to go over the
@@ -1290,7 +1428,7 @@ This will create a new integration that forwards the 
Apache Camel logo to your p
 The most obvious way to test a Kamelet is via an e2e tests that verifies if 
the Kamelet respects its specification.
 
 https://github.com/citrusframework/yaks[YAKS] is the framework of choice for 
such e2e tests. You can find more information and
-documentation starting from the YAKS github repository. Here we'll provide 
examples for the Kamelets above.
+documentation starting from the https://github.com/citrusframework/yaks[YAKS 
GitHub repository]. Here we'll provide examples for the Kamelets above.
 
 === Testing a source
 
@@ -1335,7 +1473,7 @@ We're also going to use the CLI:
 [source]
 ----
 # We assume the Kamelet is already installed in the namespace
-yaks test earthquake-source.feature
+yaks run earthquake-source.feature
 ----
 
 When testing a source, the backbone of the Gherking file that you'll write is 
similar to the one above.
@@ -1343,7 +1481,6 @@ Depending on the source under test, you may need to 
stimulate the production of
 before verifying that the data has been produced
 (in our case, it's better not to try to stimulate an earthquake :D).
 
-
 === Testing a sink
 
 A test for a sink is similar to the one for the source, except that we're 
going to generate data to feed it.
@@ -1433,7 +1570,7 @@ This can be run with the following command:
 [source]
 ----
 # We assume that both the webhook-source and the telegram-sink kamelet are 
already present in the namespace
-yaks test telegram-sink.feature --resource webhook-to-telegram.yaml --resource 
telegram-credentials.properties
+yaks run telegram-sink.feature --resource webhook-to-telegram.yaml --resource 
telegram-credentials.properties
 ----
 
 If everything goes well, you should receive a message during the test 
execution.
diff --git a/docs/modules/ROOT/pages/kamelets/kamelets-user.adoc 
b/docs/modules/ROOT/pages/kamelets/kamelets-user.adoc
index a9befa474..18cb23a10 100644
--- a/docs/modules/ROOT/pages/kamelets/kamelets-user.adoc
+++ b/docs/modules/ROOT/pages/kamelets/kamelets-user.adoc
@@ -388,6 +388,102 @@ This Pipe explicitly defines an URI where data is going 
to be pushed.
 NOTE: the `uri` option is also conventionally used in Knative to specify a 
non-kubernetes destination.
 To comply with the Knative specifications, in case an "http" or "https" URI is 
used, Camel will send https://cloudevents.io/[CloudEvents] to the destination.
 
+=== Binding with data types
+
+When referencing Kamelets in a binding users may choose from one of the 
supported input/output data types provided by the Kamelet.
+The supported data types are declared on the Kamelet itself and give 
additional information about used header names, content type and content schema.
+
+.my-sample-source-to-log.yaml
+[source,yaml]
+----
+apiVersion: camel.apache.org/v1
+kind: Pipe
+metadata:
+  name: my-sample-source-to-log
+spec:
+  source:
+    ref:
+      kind: Kamelet
+      apiVersion: camel.apache.org/v1
+      name: my-sample-source
+    data-types: # <1>
+      out:
+        format: text-plain # <2>
+  sink:
+    uri: "log:info"
+----
+<1> Specify the output data type on the referenced Kamelet source.
+<2> Select `text-plain` as an output data type of the `my-sample-source` 
Kamelet.
+
+The very same Kamelet `my-sample-source` may also provide a CloudEvents 
specific data type as an output which fits perfect for binding to a Knative 
broker.
+
+.my-sample-source-to-knative.yaml
+[source,yaml]
+----
+apiVersion: camel.apache.org/v1
+kind: Pipe
+metadata:
+  name: my-sample-source-to-knative
+spec:
+  source:
+    ref:
+      kind: Kamelet
+      apiVersion: camel.apache.org/v1
+      name: my-sample-source
+    data-types:
+      out:
+        format: application-cloud-events # <1>
+  sink:
+    ref:
+      kind: Broker
+      apiVersion: eventing.knative.dev/v1
+      name: default
+----
+<1> Select `application-cloud-events` as an output data type of the 
`my-sample-source` Kamelet.
+
+Information about the supported data types can be found on the Kamelet itself.
+
+.my-sample-source.kamelet.yaml
+[source,yaml]
+----
+apiVersion: camel.apache.org/v1
+kind: Kamelet
+metadata:
+  name: my-sample-source
+  labels:
+    camel.apache.org/kamelet.type: "source"
+spec:
+  definition:
+# ...
+  dataTypes:
+    out: # <1>
+      default: text-plain # <2>
+      types: # <3>
+        text-plain:
+          description: Output type as plain text.
+          mediaType: text/plain
+        application-cloud-events:
+          description: CloudEvents specific representation of the Kamelet 
output.
+          mediaType: application/cloudevents+json
+          schema: # <4>
+            # ...
+          dependencies: # <5>
+            - "camel:cloudevents"
+
+  template:
+    from:
+      uri: ...
+      steps:
+        - to: "kamelet:sink"
+----
+<1> Declared output data types of this Kamelet source
+<2> The output data type used by default
+<3> List of supported output types
+<4> Optional Json schema describing the `application/cloudevents+json` data 
type
+<5> Optional list of additional dependencies that are required by the data 
type.
+
+This way users may choose the best Kamelet data type for a specific use case 
when referencing Kamelets in a binding.
+
 === Error Handling
 
 You can configure an error handler in order to specify what to do when some 
event ends up with failure. See 
xref:kamelets/kameletbindings-error-handler.adoc[Pipes Error Handler User 
Guide] for more detail.

Reply via email to