This is an automated email from the ASF dual-hosted git repository.
oalsafi pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/master by this push:
new b3fde1b CAMEL-14634: Add component-dsl doc (#3862)
b3fde1b is described below
commit b3fde1bb7f910f3369d7ded51fbdb2cb525842e9
Author: Omar Al-Safi <omars...@gmail.com>
AuthorDate: Wed May 27 15:07:09 2020 +0200
CAMEL-14634: Add component-dsl doc (#3862)
---
docs/user-manual/modules/ROOT/nav.adoc | 1 +
.../modules/ROOT/pages/component-dsl.adoc | 70 ++++++++++++++++++++++
docs/user-manual/modules/ROOT/pages/index.adoc | 1 +
3 files changed, 72 insertions(+)
diff --git a/docs/user-manual/modules/ROOT/nav.adoc
b/docs/user-manual/modules/ROOT/nav.adoc
index b5d5096..ab64c7f 100644
--- a/docs/user-manual/modules/ROOT/nav.adoc
+++ b/docs/user-manual/modules/ROOT/nav.adoc
@@ -12,6 +12,7 @@
** xref:configuring-camel.adoc[Configuring Camel]
** xref:configuring-route-startup-ordering-and-autostartup.adoc[Configuring
route startup ordering and autostartup]
** xref:creating-a-new-spring-based-camel-route.adoc[Creating a new Spring
based Camel Route]
+** xref:component-dsl.adoc[Component-dsl]
** xref:Endpoint-dsl.adoc[Endpoint-dsl]
** xref:examples.adoc[Examples]
** xref:graceful-shutdown.adoc[Graceful Shutdown]
diff --git a/docs/user-manual/modules/ROOT/pages/component-dsl.adoc
b/docs/user-manual/modules/ROOT/pages/component-dsl.adoc
new file mode 100644
index 0000000..cbec439
--- /dev/null
+++ b/docs/user-manual/modules/ROOT/pages/component-dsl.adoc
@@ -0,0 +1,70 @@
+[[Component-DSL]]
+= Component DSL
+
+Component-DSL is a new API that allows using type safe construction of Camel
components and inject them directly to Camel Context instead of initializing
through a constructor.
+
+The following is an example of Kafka component that is constructed using the
typical constructor initialization:
+
+[source,java]
+----
+KafkaComponent kafka = new KafkaComponent();
+kafka.setBrokers("localhost:9090");
+
+camelContext.addComponent("kafka", kafka);
+----
+
+The same Java statement can be rewritten in the following more readable way
using the new `ComponentsBuilderFactory` that allows the access to all
component DSLs in Camel:
+
+[source,java]
+----
+ComponentsBuilderFactory.kafka()
+ .brokers("{{kafka.host}}:{{kafka.port}}")
+ .register(camelContext, "kafka");
+----
+
+In order to explain it better, we can break down the above Java statement into
3 parts:
+
+. `ComponentsBuilderFactory.kafka()`: This will initialize the DSL for
`camel-kafka` component.
+. `.brokers("{{kafka.host}}:{{kafka.port}}")`: This is the equivalent setter
of `kafka.setBrokers("localhost:9090")` using DSL fluent builder.
+. `.register(camelContext, "kafka")`: Here we register directly the component
under name `kafka` into Camel context, of course you can use any component name
you like, just like `addComponent` API.
+
+== The fluent DSL now provides type safety for parameters
+Similar to the Endpoint DSL, uses the meta model, which is extracted from the
source using an annotation processor and
+written in various JSON files, to generate a fluent DSL for each component.
This fluent DSL provides type safety for parameters.
+It further allows leveraging the Java editor code completion to access the
list of available parameters for the each component.
+
+== Build component without registering into Camel context
+
+In the above Java statement, we registered the component directly into Camel
context. However, the Component DSL also allows you to just build the component
and return the object instance, for example:
+
+[source,java]
+----
+KafkaComponent kafka = ComponentsBuilderFactory.kafka()
+ .brokers("{{kafka.host}}:{{kafka.port}}")
+ .build(camelContext);
+----
+
+In the above Java statement, the context was passed into the `build` API in
order to resolve any placeholders that are assigned in the context, e.g:
`{{kafka.host}}:{{kafka.port}}`. However, if you don't have any placeholders or
don't need to have the component closely connected to the Camel context, this
can be done as follows:
+
+[source,java]
+----
+KafkaComponent kafka = ComponentsBuilderFactory.kafka()
+ .brokers("{{kafka.host}}:{{kafka.port}}")
+ .build();
+----
+
+== How to use
+
+In order to use this feature, Maven users will need to add the following
dependency to their `pom.xml` for this component:
+
+[source,xml]
+.pom.xml
+----
+<dependency>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-componentdsl</artifactId>
+ <version>x.x.x</version>
+</dependency>
+----
+
+And then use it just like how we demonstrated it earlier in this page.
\ No newline at end of file
diff --git a/docs/user-manual/modules/ROOT/pages/index.adoc
b/docs/user-manual/modules/ROOT/pages/index.adoc
index f9dd240..04c2d30 100644
--- a/docs/user-manual/modules/ROOT/pages/index.adoc
+++ b/docs/user-manual/modules/ROOT/pages/index.adoc
@@ -39,6 +39,7 @@ For a deeper and better understanding of Apache Camel, an
xref:faq:what-is-camel
* xref:architecture.adoc[Architecture]
* xref:{eip-vc}:eips:enterprise-integration-patterns.adoc[Enterprise
Integration Patterns]
* xref:Endpoint-dsl.adoc[Endpoint-dsl]
+* xref:component-dsl.adoc[Component-dsl]
* xref:dsl.adoc[DSL]
* xref:components::index.adoc[Components]
* xref:components:dataformats:index.adoc[Data Formats]
