This is an automated email from the ASF dual-hosted git repository.
lburgazzoli pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel-k-runtime.git
commit 1a45f5366a1b4ca07f8a4fcb6c9b02869afad612
Author: lburgazzoli <lburgazz...@gmail.com>
AuthorDate: Mon Aug 24 15:57:22 2020 +0200
Document Knative component #247
---
camel-knative/camel-knative-api/pom.xml | 1 -
camel-knative/camel-knative/pom.xml | 13 ++
.../knative/KnativeComponentConfigurer.java | 5 +
.../apache/camel/component/knative/knative.json | 7 +-
.../src/main/docs/knative-component.adoc | 238 +++++++++++++++++++++
.../camel/component/knative/KnativeComponent.java | 5 +-
.../camel/component/knative/KnativeEndpoint.java | 6 +-
pom.xml | 10 +
8 files changed, 277 insertions(+), 8 deletions(-)
diff --git a/camel-knative/camel-knative-api/pom.xml
b/camel-knative/camel-knative-api/pom.xml
index ec1d00a..1e11e7d 100644
--- a/camel-knative/camel-knative-api/pom.xml
+++ b/camel-knative/camel-knative-api/pom.xml
@@ -84,7 +84,6 @@
<plugin>
<groupId>org.apache.camel</groupId>
<artifactId>camel-package-maven-plugin</artifactId>
- <version>${camel-version}</version>
<configuration>
<failFast>false</failFast>
</configuration>
diff --git a/camel-knative/camel-knative/pom.xml
b/camel-knative/camel-knative/pom.xml
index a0152c9..f6a3701 100644
--- a/camel-knative/camel-knative/pom.xml
+++ b/camel-knative/camel-knative/pom.xml
@@ -105,6 +105,19 @@
</executions>
</plugin>
<plugin>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-package-maven-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>update-readme</id>
+ <goals>
+ <goal>update-readme</goal>
+ </goals>
+ <phase>process-classes</phase>
+ </execution>
+ </executions>
+ </plugin>
+ <plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<version>${build-helper-maven-plugin-version}</version>
diff --git
a/camel-knative/camel-knative/src/generated/java/org/apache/camel/component/knative/KnativeComponentConfigurer.java
b/camel-knative/camel-knative/src/generated/java/org/apache/camel/component/knative/KnativeComponentConfigurer.java
index fb57da7..1168e20 100644
---
a/camel-knative/camel-knative/src/generated/java/org/apache/camel/component/knative/KnativeComponentConfigurer.java
+++
b/camel-knative/camel-knative/src/generated/java/org/apache/camel/component/knative/KnativeComponentConfigurer.java
@@ -23,6 +23,8 @@ public class KnativeComponentConfigurer extends
PropertyConfigurerSupport implem
case "basicPropertyBinding":
target.setBasicPropertyBinding(property(camelContext, boolean.class, value));
return true;
case "bridgeerrorhandler":
case "bridgeErrorHandler":
target.setBridgeErrorHandler(property(camelContext, boolean.class, value));
return true;
+ case "environmentpath":
+ case "environmentPath":
target.setEnvironmentPath(property(camelContext, java.lang.String.class,
value)); return true;
case "lazystartproducer":
case "lazyStartProducer":
target.setLazyStartProducer(property(camelContext, boolean.class, value));
return true;
case "transport": target.setTransport(property(camelContext,
org.apache.camel.component.knative.spi.KnativeTransport.class, value)); return
true;
@@ -37,6 +39,7 @@ public class KnativeComponentConfigurer extends
PropertyConfigurerSupport implem
Map<String, Object> answer = new CaseInsensitiveMap();
answer.put("basicPropertyBinding", boolean.class);
answer.put("bridgeErrorHandler", boolean.class);
+ answer.put("environmentPath", java.lang.String.class);
answer.put("lazyStartProducer", boolean.class);
answer.put("transport",
org.apache.camel.component.knative.spi.KnativeTransport.class);
answer.put("transportOptions", java.util.Map.class);
@@ -51,6 +54,8 @@ public class KnativeComponentConfigurer extends
PropertyConfigurerSupport implem
case "basicPropertyBinding": return target.isBasicPropertyBinding();
case "bridgeerrorhandler":
case "bridgeErrorHandler": return target.isBridgeErrorHandler();
+ case "environmentpath":
+ case "environmentPath": return target.getEnvironmentPath();
case "lazystartproducer":
case "lazyStartProducer": return target.isLazyStartProducer();
case "transport": return target.getTransport();
diff --git
a/camel-knative/camel-knative/src/generated/resources/org/apache/camel/component/knative/knative.json
b/camel-knative/camel-knative/src/generated/resources/org/apache/camel/component/knative/knative.json
index c1c562a..8e0f5ed 100644
---
a/camel-knative/camel-knative/src/generated/resources/org/apache/camel/component/knative/knative.json
+++
b/camel-knative/camel-knative/src/generated/resources/org/apache/camel/component/knative/knative.json
@@ -3,7 +3,7 @@
"kind": "component",
"name": "knative",
"title": "Knative",
- "description": "This component allows to interact with KNative events.",
+ "description": "This component allows to interact with Knative.",
"deprecated": false,
"firstVersion": "3.0.0",
"label": "cloud,eventing",
@@ -21,6 +21,7 @@
"lenientProperties": false
},
"componentProperties": {
+ "environmentPath": { "kind": "property", "displayName": "Environment
Path", "group": "common", "label": "", "required": false, "type": "string",
"javaType": "java.lang.String", "deprecated": false, "secret": false,
"description": "The path ot the environment definition" },
"transport": { "kind": "property", "displayName": "Transport", "group":
"common", "label": "", "required": false, "type": "object", "javaType":
"org.apache.camel.component.knative.spi.KnativeTransport", "deprecated": false,
"secret": false, "defaultValue": "http", "description": "The transport
implementation." },
"transportOptions": { "kind": "property", "displayName": "Transport
Options", "group": "common", "label": "", "required": false, "type": "object",
"javaType": "java.util.Map<java.lang.String, java.lang.Object>", "deprecated":
false, "secret": false, "description": "Transport options." },
"bridgeErrorHandler": { "kind": "property", "displayName": "Bridge Error
Handler", "group": "consumer", "label": "consumer", "required": false, "type":
"boolean", "javaType": "boolean", "deprecated": false, "secret": false,
"defaultValue": false, "description": "Allows for bridging the consumer to the
Camel routing Error Handler, which mean any exceptions occurred while the
consumer is trying to pickup incoming messages, or the likes, will now be
processed as a message and handled by [...]
@@ -28,8 +29,8 @@
"basicPropertyBinding": { "kind": "property", "displayName": "Basic
Property Binding", "group": "advanced", "label": "advanced", "required": false,
"type": "boolean", "javaType": "boolean", "deprecated": false, "secret": false,
"defaultValue": false, "description": "Whether the component should use basic
property binding (Camel 2.x) or the newer property binding with additional
capabilities" }
},
"properties": {
- "type": { "kind": "path", "displayName": "Type", "group": "common",
"label": "", "required": false, "type": "object", "javaType":
"org.apache.camel.component.knative.spi.Knative.Type", "enum": [ "endpoint",
"channel", "event" ], "deprecated": false, "secret": false, "description": "The
Knative type" },
- "name": { "kind": "path", "displayName": "Name", "group": "common",
"label": "", "required": false, "type": "string", "javaType":
"java.lang.String", "deprecated": false, "secret": false, "description": "The
Knative name" },
+ "type": { "kind": "path", "displayName": "Type", "group": "common",
"label": "", "required": false, "type": "object", "javaType":
"org.apache.camel.component.knative.spi.Knative.Type", "enum": [ "endpoint",
"channel", "event" ], "deprecated": false, "secret": false, "description": "The
Knative resource type" },
+ "name": { "kind": "path", "displayName": "Name", "group": "common",
"label": "", "required": false, "type": "string", "javaType":
"java.lang.String", "deprecated": false, "secret": false, "description": "The
name that identifies the Knative resource" },
"ceOverride": { "kind": "parameter", "displayName": "Ce Override",
"group": "common", "label": "", "required": false, "type": "object",
"javaType": "java.util.Map<java.lang.String, java.lang.Object>", "prefix":
"ce.override.", "deprecated": false, "secret": false, "configurationClass":
"org.apache.camel.component.knative.KnativeConfiguration",
"configurationField": "configuration", "description": "CloudEvent headers to
override" },
"cloudEventsSpecVersion": { "kind": "parameter", "displayName": "Cloud
Events Spec Version", "group": "common", "label": "", "required": false,
"type": "string", "javaType": "java.lang.String", "enum": [ "0.1", "0.2",
"0.3", "1.0" ], "deprecated": false, "secret": false, "defaultValue": "1.0",
"configurationClass":
"org.apache.camel.component.knative.KnativeConfiguration",
"configurationField": "configuration", "description": "Set the version of the
cloudevents spec." },
"cloudEventsType": { "kind": "parameter", "displayName": "Cloud Events
Type", "group": "common", "label": "", "required": false, "type": "string",
"javaType": "java.lang.String", "deprecated": false, "secret": false,
"defaultValue": "org.apache.camel.event", "configurationClass":
"org.apache.camel.component.knative.KnativeConfiguration",
"configurationField": "configuration", "description": "Set the event-type
information of the produced events." },
diff --git a/camel-knative/camel-knative/src/main/docs/knative-component.adoc
b/camel-knative/camel-knative/src/main/docs/knative-component.adoc
new file mode 100644
index 0000000..4b0d15c
--- /dev/null
+++ b/camel-knative/camel-knative/src/main/docs/knative-component.adoc
@@ -0,0 +1,238 @@
+[[knative-component]]
+= Knative Component
+:docTitle: Knative
+:artifactId: camel-knative
+:description: This component allows to interact with Knative.
+:since: 3.0
+:supportLevel: Preview
+:component-header: Both producer and consumer are supported
+
+*Since Camel {since}*
+
+*{component-header}*
+
+The Knative component provides support for interacting with
https://knative.dev/[Knative].
+
+Maven users will need to add the following dependency to their `pom.xml`
+for this component.
+
+[source,xml]
+------------------------------------------------------------
+<dependency>
+ <groupId>org.apache.camel.k</groupId>
+ <artifactId>camel-knative</artifactId>
+ <version>x.x.x</version>
+ <!-- use the same version as your Camel K version -->
+</dependency>
+------------------------------------------------------------
+
+== URI format
+
+[source]
+----
+knative:type/name[?options]
+----
+
+You can append query options to the URI in the following format:
+
+[source]
+------------------------------------------------------------
+?option=value&option=value&...
+------------------------------------------------------------
+
+== Options
+
+// component options: START
+The Knative component supports 17 options, which are listed below.
+
+
+
+[width="100%",cols="2,5,^1,2",options="header"]
+|===
+| Name | Description | Default | Type
+| *ceOverride* (common) | CloudEvent headers to override | | Map
+| *cloudEventsSpecVersion* (common) | Set the version of the cloudevents spec.
The value can be one of: 0.1, 0.2, 0.3, 1.0 | 1.0 | String
+| *cloudEventsType* (common) | Set the event-type information of the produced
events. | org.apache.camel.event | String
+| *configuration* (common) | Set the configuration. | | KnativeConfiguration
+| *environment* (common) | The environment | | KnativeEnvironment
+| *environmentPath* (common) | The path ot the environment definition | |
String
+| *filters* (common) | Set the filters. | | Map
+| *serviceName* (common) | The name of the service to lookup from the
KnativeEnvironment. | | String
+| *transport* (common) | The transport implementation. | | KnativeTransport
+| *transportOptions* (common) | Set the transport options. | | Map
+| *bridgeErrorHandler* (consumer) | Allows for bridging the consumer to the
Camel routing Error Handler, which mean any exceptions occurred while the
consumer is trying to pickup incoming messages, or the likes, will now be
processed as a message and handled by the routing Error Handler. By default the
consumer will use the org.apache.camel.spi.ExceptionHandler to deal with
exceptions, that will be logged at WARN or ERROR level and ignored. | false |
boolean
+| *replyWithCloudEvent* (consumer) | Transforms the reply into a cloud event
that will be processed by the caller. When listening to events from a Knative
Broker, if this flag is enabled, replies will be published to the same Broker
where the request comes from (beware that if you don't change the type of the
received message, you may create a loop and receive your same reply). When this
flag is disabled, CloudEvent headers are removed from the reply. | false |
boolean
+| *reply* (consumer) | If the consumer should construct a full reply to
knative request. | true | Boolean
+| *lazyStartProducer* (producer) | Whether the producer should be started lazy
(on the first message). By starting lazy you can use this to allow CamelContext
and routes to startup in situations where a producer may otherwise fail during
starting and cause the route to fail being started. By deferring this startup
to be lazy then the startup failure can be handled during routing messages via
Camel's routing error handlers. Beware that when the first message is processed
then creating and [...]
+| *apiVersion* (advanced) | The version of the k8s resource referenced by the
endpoint. | | String
+| *basicPropertyBinding* (advanced) | Whether the component should use basic
property binding (Camel 2.x) or the newer property binding with additional
capabilities | false | boolean
+| *kind* (advanced) | The type of the k8s resource referenced by the endpoint.
| | String
+|===
+// component options: END
+
+// endpoint options: START
+The Knative endpoint is configured using URI syntax:
+
+----
+knative:type/name
+----
+
+with the following path and query parameters:
+
+=== Path Parameters (2 parameters):
+
+
+[width="100%",cols="2,5,^1,2",options="header"]
+|===
+| Name | Description | Default | Type
+| *type* | The Knative resource type. The value can be one of: endpoint,
channel, event | | Type
+| *name* | The name that identifies the Knative resource | | String
+|===
+
+
+=== Query Parameters (17 parameters):
+
+
+[width="100%",cols="2,5,^1,2",options="header"]
+|===
+| Name | Description | Default | Type
+| *ceOverride* (common) | CloudEvent headers to override | | Map
+| *cloudEventsSpecVersion* (common) | Set the version of the cloudevents spec.
The value can be one of: 0.1, 0.2, 0.3, 1.0 | 1.0 | String
+| *cloudEventsType* (common) | Set the event-type information of the produced
events. | org.apache.camel.event | String
+| *environment* (common) | The environment | | KnativeEnvironment
+| *filters* (common) | Set the filters. | | Map
+| *serviceName* (common) | The name of the service to lookup from the
KnativeEnvironment. | | String
+| *transportOptions* (common) | Set the transport options. | | Map
+| *bridgeErrorHandler* (consumer) | Allows for bridging the consumer to the
Camel routing Error Handler, which mean any exceptions occurred while the
consumer is trying to pickup incoming messages, or the likes, will now be
processed as a message and handled by the routing Error Handler. By default the
consumer will use the org.apache.camel.spi.ExceptionHandler to deal with
exceptions, that will be logged at WARN or ERROR level and ignored. | false |
boolean
+| *replyWithCloudEvent* (consumer) | Transforms the reply into a cloud event
that will be processed by the caller. When listening to events from a Knative
Broker, if this flag is enabled, replies will be published to the same Broker
where the request comes from (beware that if you don't change the type of the
received message, you may create a loop and receive your same reply). When this
flag is disabled, CloudEvent headers are removed from the reply. | false |
boolean
+| *exceptionHandler* (consumer) | To let the consumer use a custom
ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this
option is not in use. By default the consumer will deal with exceptions, that
will be logged at WARN or ERROR level and ignored. | | ExceptionHandler
+| *exchangePattern* (consumer) | Sets the exchange pattern when the consumer
creates an exchange. The value can be one of: InOnly, InOut, InOptionalOut | |
ExchangePattern
+| *reply* (consumer) | If the consumer should construct a full reply to
knative request. | true | Boolean
+| *lazyStartProducer* (producer) | Whether the producer should be started lazy
(on the first message). By starting lazy you can use this to allow CamelContext
and routes to startup in situations where a producer may otherwise fail during
starting and cause the route to fail being started. By deferring this startup
to be lazy then the startup failure can be handled during routing messages via
Camel's routing error handlers. Beware that when the first message is processed
then creating and [...]
+| *apiVersion* (advanced) | The version of the k8s resource referenced by the
endpoint. | | String
+| *basicPropertyBinding* (advanced) | Whether the endpoint should use basic
property binding (Camel 2.x) or the newer property binding with additional
capabilities | false | boolean
+| *kind* (advanced) | The type of the k8s resource referenced by the endpoint.
| | String
+| *synchronous* (advanced) | Sets whether synchronous processing should be
strictly used, or Camel is allowed to use asynchronous processing (if
supported). | false | boolean
+|===
+// endpoint options: END
+
+
+== Supported Knative resources
+
+The component support the following Knative resources you can target or
exposes using the `type` path parameter:
+
+- **channel** allow producing or consuming events to or from a
https://knative.dev/docs/eventing/channels/[**Knative Channel**]
+- **endpoint** allow exposing or targeting serverless workloads using
https://knative.dev/docs/serving/spec/knative-api-specification-1.0/#service[**Knative
Services**]
+- **event** allow producing or consuming events to or from a
https://knative.dev/docs/eventing/broker[**Knative Broker**]
+
+== Knative Environment
+
+As the Knative component hides the technical details of how to communicate
with Knative services to the user (protocols, addresses, etc.), it needs some
metadata that describe the Knative environment to set-up the low level
transport details. In order to do so, the component needs a so called `Knative
Environment` which is essence is a Json document made by a number of `service`
elements which looks like the below example:
+
+[source,json]
+------------------------------------------------------------
+{
+ "services": [
+ {
+ "type": "channel|endpoint|event", <1>
+ "name": "", <2>
+ "metadata": {
+ "service.url": "http://my-service.svc.cluster.local"; <3>
+ "knative.event.type": "", <4>
+ "camel.endpoint.kind": "source|sink", <5>
+ }
+ }, {
+ ...
+ }
+ ]
+}
+------------------------------------------------------------
+<1> the type of the Knative resource
+<2> the name of the resource
+<3> the url of the service to invoke (for producer only)
+<4> the Knative event type received or produced by the component
+<5> the type of the Camel Endpoint associated to this Knative resource
(source=consumer, sink=producer)
+
+The `metadata` fields has some additional advanced fields:
+
+[width="100%",cols="1,5,3",options="header"]
+|===
+| Name | Description | Example
+| *filter.*
+| The prefix to define filters to be applied to the incoming message headers.
+| ```filter.ce.source=my-source```
+
+| *knative.kind*
+| The type of the k8s resource referenced by the endpoint.
+| ```knative.kind=InMemoryChannel```
+
+| *knative.apiVersion*
+| The version of the k8s resource referenced by the endpoint
+| ```knative.apiVersion=messaging.knative.dev/v1beta1```
+
+| *knative.apiVersion*
+| The version of the k8s resource referenced by the endpoint.
+| ```knative.apiVersion=messaging.knative.dev/v1beta1```
+
+| *knative.reply*
+| If the consumer should construct a full reply to knative request.
+| ```knative.reply=false```
+
+| *ce.override.*
+| The prefix to define CloudEvents values that have to be overridden.
+| ```ce.override.ce-type=MyType```
+
+|===
+
+== Knative Transport
+
+As today the component only support `http` as transport as it is the only
supported protocol on Knative side but the transport is pluggable by
implementing the following interface:
+
+[source,java]
+----
+
+public interface KnativeTransport extends Service {
+ /**
+ * Create a camel {@link org.apache.camel.Producer} in place of the
original endpoint for a specific protocol.
+ *
+ * @param endpoint the endpoint for which the producer should be created
+ * @param configuration the general transport configuration
+ * @param service the service definition containing information about how
make reach the target service.
+ * @return
+ */
+ Producer createProducer(
+ Endpoint endpoint,
+ KnativeTransportConfiguration configuration,
+ KnativeEnvironment.KnativeServiceDefinition service);
+
+ /**
+ * Create a camel {@link org.apache.camel.Producer} in place of the
original endpoint for a specific protocol.
+ *
+ * @param endpoint the endpoint for which the consumer should be created.
+ * @param configuration the general transport configuration
+ * @param service the service definition containing information about how
make the route reachable from knative.
+ * @return
+ */
+ Consumer createConsumer(
+ Endpoint endpoint,
+ KnativeTransportConfiguration configuration,
+ KnativeEnvironment.KnativeServiceDefinition service, Processor
processor);
+}
+----
+
+== Examples
+
+[source,java]
+----
+CamelContext context = new DefaultCamelContext();
+
+KnativeComponent component = context.getComponent("knative",
KnativeComponent.class);
+component.getConfiguration().setEnvironmentPath("classpath:knative.json"); //
<1>
+
+RouteBuilder.addRoutes(context, b -> {
+ b.from("knative:endpoint/myEndpoint") // <2>
+ .to("log:info");
+});
+----
+<1> set the location of the `Knative Environment` file
+<2> expose knative service
diff --git
a/camel-knative/camel-knative/src/main/java/org/apache/camel/component/knative/KnativeComponent.java
b/camel-knative/camel-knative/src/main/java/org/apache/camel/component/knative/KnativeComponent.java
index d863be5..078168f 100644
---
a/camel-knative/camel-knative/src/main/java/org/apache/camel/component/knative/KnativeComponent.java
+++
b/camel-knative/camel-knative/src/main/java/org/apache/camel/component/knative/KnativeComponent.java
@@ -40,13 +40,16 @@ import org.slf4j.LoggerFactory;
public class KnativeComponent extends DefaultComponent {
private static final Logger LOGGER =
LoggerFactory.getLogger(KnativeComponent.class);
+ @Metadata
private KnativeConfiguration configuration;
+
+ @Metadata
private String environmentPath;
@Metadata(defaultValue = "http")
private Knative.Protocol protocol = Knative.Protocol.http;
- @Metadata(defaultValue = "http")
+ @Metadata
private KnativeTransport transport;
@Metadata
diff --git
a/camel-knative/camel-knative/src/main/java/org/apache/camel/component/knative/KnativeEndpoint.java
b/camel-knative/camel-knative/src/main/java/org/apache/camel/component/knative/KnativeEndpoint.java
index b846cc8..9cac875 100644
---
a/camel-knative/camel-knative/src/main/java/org/apache/camel/component/knative/KnativeEndpoint.java
+++
b/camel-knative/camel-knative/src/main/java/org/apache/camel/component/knative/KnativeEndpoint.java
@@ -41,7 +41,7 @@ import org.apache.camel.support.PropertyBindingSupport;
import org.apache.camel.util.ObjectHelper;
/**
- * This component allows to interact with KNative events.
+ * This component allows to interact with Knative.
*/
@UriEndpoint(
firstVersion = "3.0.0",
@@ -50,9 +50,9 @@ import org.apache.camel.util.ObjectHelper;
title = "Knative",
label = "cloud,eventing")
public class KnativeEndpoint extends DefaultEndpoint {
- @UriPath(description = "The Knative type")
+ @UriPath(description = "The Knative resource type")
private final Knative.Type type;
- @UriPath(description = "The Knative name")
+ @UriPath(description = "The name that identifies the Knative resource")
private final String name;
private final CloudEventProcessor cloudEvent;
@UriParam
diff --git a/pom.xml b/pom.xml
index a7febd7..5429468 100644
--- a/pom.xml
+++ b/pom.xml
@@ -246,6 +246,16 @@
<artifactId>maven-javadoc-plugin</artifactId>
<version>${maven-javadoc-plugin-version}</version>
</plugin>
+ <plugin>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-component-maven-plugin</artifactId>
+ <version>${camel-version}</version>
+ </plugin>
+ <plugin>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-package-maven-plugin</artifactId>
+ <version>${camel-version}</version>
+ </plugin>
</plugins>
</pluginManagement>
<plugins>
