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 ab57e61 CAMEL-16861: Cleanup docs
ab57e61 is described below
commit ab57e61fd1ccb606e111f447708c3674cdf09c8d
Author: Claus Ibsen <[email protected]>
AuthorDate: Tue Nov 2 10:52:36 2021 +0100
CAMEL-16861: Cleanup docs
---
.../modules/ROOT/pages/Endpoint-dsl.adoc | 31 +++++++++++----------
docs/user-manual/modules/ROOT/pages/component.adoc | 3 ++
.../modules/ROOT/pages/defaulterrorhandler.adoc | 5 ++--
.../modules/ROOT/pages/endpoint-annotations.adoc | 5 ++--
docs/user-manual/modules/ROOT/pages/endpoint.adoc | 32 ++++++++++++++++++++--
5 files changed, 54 insertions(+), 22 deletions(-)
diff --git a/docs/user-manual/modules/ROOT/pages/Endpoint-dsl.adoc
b/docs/user-manual/modules/ROOT/pages/Endpoint-dsl.adoc
index 70d30b2..5937fd5 100644
--- a/docs/user-manual/modules/ROOT/pages/Endpoint-dsl.adoc
+++ b/docs/user-manual/modules/ROOT/pages/Endpoint-dsl.adoc
@@ -1,9 +1,11 @@
= Endpoint DSL
-Endpoint-dsl is a new API that allows using type-safe endpoint
xref:uris.adoc[URL] configurations.
+Endpoint-DSL is a builder API that allows using type-safe endpoint
xref:uris.adoc[URL] configurations.
The DSL can be accessed in several ways, but the main one is to switch to
using an `EndpointRouteBuilder` instead of the usual
-`RouteBuilder`. It provides access to all endpoint builders which are defined
through inheritance on the
`org.apache.camel.builder.endpoint.EndpointRouteBuilder`.
+`RouteBuilder`. This builder provides access to all of Camel endpoint builders
which are defined through inheritance on the
`org.apache.camel.builder.endpoint.EndpointRouteBuilder`.
+
+== Using Endpoint DSL
The following is an example of an FTP route using the standard `RouteBuilder`
Java DSL:
@@ -21,7 +23,7 @@ public class MyRoutes extends RouteBuilder {
----
The same Java statement can be rewritten in the following more type-safe and
readable way using
-the new `EndpointRouteBuilder` that allows using the Endpoint DSL:
+the new `EndpointRouteBuilder` that allows using the Endpoint-DSL:
[source,java]
----
@@ -37,21 +39,20 @@ public class MyRoutes extends EndpointRouteBuilder {
}
----
-== The fluent DSL now provides type safety for parameters
+=== Type Safety
-The above example of 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 endpoint.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 every endpoint.
+Similar to the xref:component-dsl.adoc[Component DSL], uses the meta-model,
which is extracted from the source and
+written in various JSON files, to generate a fluent DSL for each component.
This fluent DSL provides type safety for parameters.
-== Using custom component names
+=== Using custom component names
-The endpoint-dsl uses the default name of the component, so in the example
above the name is `ftp`.
-There can be use-cases where you may have multiple Camel components of the
same type registered with different names.
+The Endpoint-DSL uses the default name of the xref:component.adoc[Component],
so in the example above the name is `ftp`.
+There can be use-cases where you may have multiple Camel
xref:components::index.adoc[components] of the same type registered with
different names.
An example is if you have two JMS broker systems (for example ActiveMQ and
WebSphereMQ).
-Then you can setup two Camel JMS components with unique names such as: `myAMQ`
and `myWMQ`
+Then you can set up two Camel JMS components with unique names such as:
`myAMQ` and `myWMQ`
-The endpoint-dsl can use these names with the `jms` fluent builder as shown:
+The Endpoint-DSL can use these names with the `jms` fluent builder as shown:
[source,java]
----
@@ -62,7 +63,7 @@ from(jms("myWMQ", "cheese").concurrentConsumers(5))
Notice how we can refer to their names as the first parameter in the `jms`
fluent builder.
The example would then consume messages from WebSphereMQ queue named cheese
and route to ActiveMQ on a queue named smelly.
-== Using endpoint-dsl outside route builders
+=== Using Endpoint-DSL outside route builders
You can use the type-safe endpoint-dsl outside route builders with:
@@ -129,10 +130,10 @@ If you use Spring Boot, CDI, or Quarkus etc then you
should use their kind of an
That's not the point of this example, it is the Endpoint DSL to configure the
MQTT endpoint (camel-paho).
The endpoint is configured the same way as before by the type-safe
endpoint-dsl by static importing the `paho`,
and then use its fluent builder methods to configure. Notice how the returned
type is `EndpointProducerBuilder`.
-That type is not an `Endpoint` instance as its not resolved (eg its only a
builder for an endpoint).
+That type is not an `Endpoint` instance as it's not resolved (i.e. it's only a
builder for an endpoint).
This means that the builder can be code and compiled before `CamelContext` is
created and started.
-At runtime we want to use this endpoint to send messages to MQTT server; this
is done in the `sendToSensor`
+At runtime, we want to use this endpoint to send messages to MQTT server; this
is done in the `sendToSensor`
method where we are using `FluentProducerTemplate` that is capable of using
the `EndpointProducerBuilder` as
the endpoint in shown with: `.to(mqtt)`.
diff --git a/docs/user-manual/modules/ROOT/pages/component.adoc
b/docs/user-manual/modules/ROOT/pages/component.adoc
index d5a0015..5f3ca9a 100644
--- a/docs/user-manual/modules/ROOT/pages/component.adoc
+++ b/docs/user-manual/modules/ROOT/pages/component.adoc
@@ -40,3 +40,6 @@ to use raw values for password options, and using
xref:using-propertyplaceholder.adoc[property placeholders] etc.
====
+== See Also
+
+- List of all Camel xref:components::index.adoc[Components]
\ No newline at end of file
diff --git a/docs/user-manual/modules/ROOT/pages/defaulterrorhandler.adoc
b/docs/user-manual/modules/ROOT/pages/defaulterrorhandler.adoc
index 1c309de..41f32e5 100644
--- a/docs/user-manual/modules/ROOT/pages/defaulterrorhandler.adoc
+++ b/docs/user-manual/modules/ROOT/pages/defaulterrorhandler.adoc
@@ -1,8 +1,9 @@
= DefaultErrorHandler
-This is the default error handler in Camel.
+This is the default xref:error-handler.adoc[Error Handler] in Camel.
-The default error handler have the same power as the
xref:components:eips:dead-letter-channel.adoc[Dead Letter Channel],
+The default xref:error-handler.adoc[Error Handler] has the same power
+as the xref:components:eips:dead-letter-channel.adoc[Dead Letter Channel],
however it does *not* support a _dead letter queue_, which is
the only difference between the two of them.
diff --git a/docs/user-manual/modules/ROOT/pages/endpoint-annotations.adoc
b/docs/user-manual/modules/ROOT/pages/endpoint-annotations.adoc
index 43bbf77..4cbf6c6 100644
--- a/docs/user-manual/modules/ROOT/pages/endpoint-annotations.adoc
+++ b/docs/user-manual/modules/ROOT/pages/endpoint-annotations.adoc
@@ -2,7 +2,8 @@
You can annotate xref:endpoint.adoc[Endpoint] and
xref:component.adoc[Component]
classes, so that their configuration documentation can be
-automatically generated by Maven tooling via the
`camel-component-maven-plugin` plugin,
+automatically generated by Maven tooling via the
+xref:camel-component-maven-plugin.adoc[Camel Component Maven Plugin]
into the `src/main/generated` folder.
The documentation is then included into the jar as JSON schema files.
@@ -17,7 +18,7 @@ with all the latest options on the Camel
xref:components::index.adoc[Components]
|Annotation |Description
|`@UriEndpoint` |Specifies that an endpoint is annotated with `@UriParam`
and/or `@UriParams` annotations. Also specifies the default scheme to use
-in the generated documentation, and other informations.
+in the generated documentation, and other information.
|`@UriParam` |Used to annotate a parameter value; usually specified via
?foo=bar syntax in the URI strings in Camel. Used currently only on
diff --git a/docs/user-manual/modules/ROOT/pages/endpoint.adoc
b/docs/user-manual/modules/ROOT/pages/endpoint.adoc
index 76731bf..6815ba9 100644
--- a/docs/user-manual/modules/ROOT/pages/endpoint.adoc
+++ b/docs/user-manual/modules/ROOT/pages/endpoint.adoc
@@ -4,10 +4,36 @@ Camel supports the
xref:components:eips:message-endpoint.adoc[Message Endpoint]
using the
https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/Endpoint.html[Endpoint]
interface.
-Endpoints are usually created by a Component and Endpoints are usually referred
-to in the xref:dsl.adoc[DSL] via their xref:uris.adoc[URIs].
+Endpoints are created by a xref:component.adoc[Component] and these endpoints
are referred
+to in the xref:dsl.adoc[DSL] via their endpoint xref:uris.adoc[URIs].
-From an `Endpoint` you can use the following methods:
+== Example
+
+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:manual::uris.adoc[URIs]:
+
+[source,java]
+----
+from("file:messages/foo")
+ .to("jms:queue:foo");
+----
+
+And in XML:
+
+[source,xml]
+----
+<route>
+ <from uri="file:messages/foo"/>
+ <to uri="jms:queue:foo"/>
+</route>
+----
+
+== Endpoint API
+
+You will almost never have the need for creating endpoints manually via Java
API.
+
+From an `Endpoint` you can use the following Java API methods to create
producers or consumers to the endpoint:
*
https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/Endpoint.html#createProducer--[`createProducer()`]
will create a
