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
commit 3375577c0c8a7c26998cb84cfc79de1e4d47d942 Author: Claus Ibsen <[email protected]> AuthorDate: Tue Aug 10 14:43:31 2021 +0200 Polish and cleanup documentation --- .../modules/ROOT/pages/Endpoint-dsl.adoc | 18 +-- .../modules/ROOT/pages/endpoint-annotations.adoc | 37 +++--- docs/user-manual/modules/ROOT/pages/endpoint.adoc | 32 +++--- .../modules/ROOT/pages/error-handler.adoc | 126 ++++++++++----------- 4 files changed, 105 insertions(+), 108 deletions(-) diff --git a/docs/user-manual/modules/ROOT/pages/Endpoint-dsl.adoc b/docs/user-manual/modules/ROOT/pages/Endpoint-dsl.adoc index b351360..9cf3d85 100644 --- a/docs/user-manual/modules/ROOT/pages/Endpoint-dsl.adoc +++ b/docs/user-manual/modules/ROOT/pages/Endpoint-dsl.adoc @@ -1,9 +1,12 @@ [[Endpoint-DSL]] = Endpoint DSL -Endpoint-dsl is a new API that allows using type-safe endpoint URL configurations. +Endpoint-dsl is a new API that allows using type-safe endpoint xref:uris.adoc[URL] configurations. -The following is an example of an FTP route using the standard `RouteBuilder`: +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`. + +The following is an example of an FTP route using the standard `RouteBuilder` Java DSL: [source,java] ---- @@ -18,8 +21,8 @@ public class MyRoutes extends RouteBuilder { } ---- -The same Java statement can be rewritten in the following more readable way using -the new `EndpointRouteBuilder` that allows using the endpoint DSL: +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: [source,java] ---- @@ -39,7 +42,7 @@ public class MyRoutes extends EndpointRouteBuilder { 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 the each endpoint. +It further allows leveraging the Java editor code completion to access the list of available parameters for every endpoint. == Using custom component names @@ -135,10 +138,7 @@ method where we are using `FluentProducerTemplate` that is capable of using the the endpoint in shown with: `.to(mqtt)`. -== How to use - -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`. +== Dependency Maven users will need to add the following dependency to their `pom.xml` for this component: diff --git a/docs/user-manual/modules/ROOT/pages/endpoint-annotations.adoc b/docs/user-manual/modules/ROOT/pages/endpoint-annotations.adoc index ce781c8..43bbf77 100644 --- a/docs/user-manual/modules/ROOT/pages/endpoint-annotations.adoc +++ b/docs/user-manual/modules/ROOT/pages/endpoint-annotations.adoc @@ -1,41 +1,42 @@ -= Endpoint Annotations += Component Endpoint Annotations -You can annotate xref:endpoint.adoc[Endpoint] and -Consumer classes so that their configuration documentation can be -automatically generated by the camel-package-maven-plugin (rather like -maven plugin goals get their parameters documented automatically). +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, +into the `src/main/generated` folder. -The documentation is then included into the jar as -org/apache/camel/component/scheme/scheme.adoc where scheme is the -component name. +The documentation is then included into the jar as JSON schema files. -== Supported annotations +The Camel project uses this to automatic keep the website documentation up-to-date +with all the latest options on the Camel xref:components::index.adoc[Components]. + +== Supported Annotations [width="100%",cols="50%,50%",options="header",] |======================================================================= |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 +|`@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. -|@UriParam |Used to annotate a parameter value; usually specified via +|`@UriParam` |Used to annotate a parameter value; usually specified via ?foo=bar syntax in the URI strings in Camel. Used currently only on field declarations but in the future could be used on setter methods too. If no name is specified then the name of the field/setter property is used. -|@UriParams |Specifies that a field is a nested object of one or more +|`@UriParams` |Specifies that a field is a nested object of one or more configuration parameters; then the class of this field should be -annotated with one or more @UriParam or @UriParams annotations +annotated with one or more `@UriParam` or `@UriParams` annotations -|@Metadata | Used for special situations to provide additional information +|`@Metadata` | Used for special situations to provide additional information. |======================================================================= For example see the `TimerEndpoint` from the `camel-timer` component and -notice how its using these annotations. +notice how it is using these annotations. Not only are the annotations useful for automatically generating the documentation; we can use them to refine the validation of the code -during configuration and they can be useful for tool providers so they +during configuration and can be useful for tooling providers, so they can more easily introspect the configuration options. diff --git a/docs/user-manual/modules/ROOT/pages/endpoint.adoc b/docs/user-manual/modules/ROOT/pages/endpoint.adoc index 3d2fbc5..5483582 100644 --- a/docs/user-manual/modules/ROOT/pages/endpoint.adoc +++ b/docs/user-manual/modules/ROOT/pages/endpoint.adoc @@ -1,27 +1,29 @@ [[Endpoint-Endpoints]] = Endpoints -Camel supports the Message Endpoint pattern -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 DSL via their URIs. +Camel supports the xref:{eip-vc}:eips:message-endpoint.adoc[Message Endpoint] pattern +using the https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/Endpoint.html[Endpoint] +interface. -From an Endpoint you can use the following methods +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]. -* https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/Endpoint.html#createProducer--[createProducer()] +From an `Endpoint` you can use the following methods: + +* https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/Endpoint.html#createProducer--[`createProducer()`] will create a https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/Producer.html[Producer] -for sending message exchanges to the endpoint -* https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/Endpoint.html#createConsumer-org.apache.camel.Processor-[createConsumer()] -implements the Event Driven Consumer +for sending message exchanges to the endpoint. + +* https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/Endpoint.html#createConsumer-org.apache.camel.Processor[`createConsumer()`] +implements the xref:{eip-vc}:eips:eventDrivenConsumer-eip.adoc[Event Driven Consumer] pattern for consuming message exchanges from the endpoint via a https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/Processor.html[Processor] when creating a -https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/Consumer.html[Consumer] -* https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/Endpoint.html#createPollingConsumer--[createPollingConsumer()] -implements the Polling Consumer pattern for +https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/Consumer.html[Consumer]. + +* https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/Endpoint.html#createPollingConsumer[`createPollingConsumer()`] +implements the xref:{eip-vc}:eips:polling-consumer.adoc[Polling Consumer] pattern for consuming message exchanges from the endpoint via a -https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/PollingConsumer.html[PollingConsumer] +https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/PollingConsumer.html[PollingConsumer]. diff --git a/docs/user-manual/modules/ROOT/pages/error-handler.adoc b/docs/user-manual/modules/ROOT/pages/error-handler.adoc index 6b410dd..f31f903 100644 --- a/docs/user-manual/modules/ROOT/pages/error-handler.adoc +++ b/docs/user-manual/modules/ROOT/pages/error-handler.adoc @@ -3,15 +3,15 @@ Camel supports pluggable https://www.javadoc.io/doc/org.apache.camel/camel-base/current/org/apache/camel/processor/ErrorHandler.html[ErrorHandler] -strategies to deal with errors processing an -Event Driven Consumer. An alternative -is to specify the error handling directly in the DSL -using the Exception Clause. +strategies to deal with errors processing an xref:{eip-vc}:eips:eventDrivenConsumer-eip.adoc[Event Driven Consumer]. -For introduction and background material see -Error handling in Camel. +An alternative is to specify the error handling directly in the xref:dsl.adoc[DSL] +using the xref:exception-clause.adoc[Exception Clause]. -*Exception Clause* +For introduction and background material see xref:error-handler.adoc[Error handling] +in Camel. + +== Exception Clause Using Error Handler combined with Exception Clause is a very powerful @@ -19,7 +19,7 @@ combination. We encourage end-users to use this combination in your error handling strategies. See samples and Exception Clause. -*Using try ... catch ... finally* +== Using try ... catch ... finally Related to error handling is the xref:try-catch-finally.adoc[Try Catch Finally] as DSL you can use directly in your route. Its basically a @@ -28,7 +28,6 @@ more power. The current implementations Camel provides out of the box are: -[[ErrorHandler-Nontransacted]] == Non transacted * DefaultErrorHandler is the default @@ -40,7 +39,6 @@ attempting to redeliver the message exchange a number of times before sending it to a dead letter endpoint * NoErrorHandler for no error handling -[[ErrorHandler-Transacted]] == Transacted * TransactionErrorHandler is the @@ -52,7 +50,6 @@ entire set of rules or a specific routing rule as we show in the next examples. Error handling rules are inherited on each routing rule within a single RouteBuilder -[[ErrorHandler-ShortSummaryoftheprovidedErrorHandlers]] == Short Summary of the provided Error Handlers === DefaultErrorHandler @@ -69,21 +66,7 @@ most 6 times using 1 second delay, and if the exchange failed it will be logged at ERROR level. You can configure the default dead letter endpoint to use: - -or in Spring DSL - -[source,xml] ------------------------------------------------------------------------------------------------------ -<bean id="deadLetterErrorHandler" class="org.apache.camel.builder.DeadLetterChannelBuilder"> - <property name="deadLetterUri" value="log:dead"/> -</bean> - -<camelContext errorHandlerRef="deadLetterErrorHandler" xmlns="http://camel.apache.org/schema/spring";> - ... -</camelContext> ------------------------------------------------------------------------------------------------------ - -or also from *Camel 2.3.0 onwards* +or in XML DSL: [source,xml] -------------------------------------------------------------------------------------------------- @@ -94,7 +77,6 @@ or also from *Camel 2.3.0 onwards* </camel:camelContext> -------------------------------------------------------------------------------------------------- -[[ErrorHandler-NoErrorHandler]] === No Error Handler The no error handler is to be used for disabling error handling. @@ -104,18 +86,7 @@ The no error handler is to be used for disabling error handling. errorHandler(noErrorHandler()); ------------------------------- -or in Spring DSL - -[source,xml] ---------------------------------------------------------------------------------------------- -<bean id="noErrorHandler" class="org.apache.camel.builder.NoErrorHandlerBuilder"/> - -<camelContext errorHandlerRef="noErrorHandler" xmlns="http://camel.apache.org/schema/spring";> - ... -</camelContext> ---------------------------------------------------------------------------------------------- - -or also from *Camel 2.3.0 onwards* +or in XML DSL: [source,xml] --------------------------------------------------------------- @@ -126,26 +97,24 @@ or also from *Camel 2.3.0 onwards* </camel:camelContext> --------------------------------------------------------------- -[[ErrorHandler]] === TransactionErrorHandler The TransactionErrorHandler is the default error handler in Camel for transacted routes. TIP:If you have marked a route as transacted using the *transacted* DSL then -Camel will automatic use a +Camel will automatically use a TransactionErrorHandler. It will try to lookup the global/per route configured error handler and use it if -its a `TransactionErrorHandlerBuilder` instance. If not Camel will -automatic create a temporary +it is a `TransactionErrorHandlerBuilder` instance. If not Camel will +automatically create a temporary TransactionErrorHandler that overrules the default error handler. This is convention over configuration. -[[ErrorHandler-Featuressupportbyvariouss]] == Features support by various Error Handlers -Here is a breakdown of which features is supported by the +Here is a breakdown of which features are supported by the Error Handler(s): [width="100%",cols="20%,80%",options="header",] @@ -207,18 +176,17 @@ Dead Letter Channel |======================================================================= -See Exception Clause documentation for -documentation of some of the features above. +See xref:exception-clause.adoc[Exception Clause] documentation for +additional documentation of the faatures above. -[[ErrorHandler-Scopes]] == Scopes -The error handler is scoped as either +The error handler is scoped as either: -* global (within the RouteBuilder) -* per route +- CamelContext - _Globally_ in XML or _globally only_ within the same `RouteBuilder` in Java DSL +- Route - _Individually per route_ -The following example shows how you can register a global error handler: +The following example shows how you can register a global error handler for the `RouteBuilder`: [source,java] --------------------------------------------------------------- @@ -252,7 +220,6 @@ RouteBuilder builder = new RouteBuilder() { }; --------------------------------------------------------------- -[[ErrorHandler-Springbasedconfiguration]] == Spring based configuration *Java DSL vs. Spring DSL* @@ -260,21 +227,19 @@ The error handler is configured a bit differently in Java DSL and Spring DSL. Spring DSL relies more on standard Spring bean configuration whereas Java DSL uses fluent builders. - The error handler can be configured as a spring bean and scoped in: -* global (the camelContext tag) -* per route (the route tag) -* or per policy (the policy/transacted tag) +* global (the `<camelContext>` tag) +* per route (the `<route>` tag) +* or per policy (the `<policy>`/`<transacted>` tag) The error handler is configured with the `errorHandlerRef` attribute. -TIP:*Error Handler Hierarchy* +TIP: *Error Handler Hierarchy* + The error handlers is inherited, so if you only have set a global error handler then its use everywhere. But you can override this in a route and use another error handler. -[[ErrorHandler-Springbasedconfigurationsample]] === Spring based configuration sample In this sample we configure a xref:{eip-vc}:eips:dead-letter-channel.adoc[Dead Letter @@ -282,22 +247,51 @@ Channel] on the route that should redeliver at most 3 times and use a little delay before retrying. First we configure the reference to *myDeadLetterErrorHandler* using the `errorHandlerRef` attribute on the `route` tag. +[source,xml] +---- + <camelContext xmlns="http://camel.apache.org/schema/spring";> + <template id="myTemplate"/> + <!-- set the errorHandlerRef to our DeadLetterChannel, this applies for this route only --> + <route errorHandlerRef="myDeadLetterErrorHandler"> + <from uri="direct:in"/> + <process ref="myFailureProcessor"/> + <to uri="mock:result"/> + </route> + </camelContext> +---- + Then we configure *myDeadLetterErrorHandler* that is our Dead Letter Channel. This configuration -is standard Spring using the bean element. + - And finally we have another spring bean for the redelivery policy where +is standard Spring using the bean element. +And finally we have another spring bean for the redelivery policy where we can configure the options for how many times to redeliver, delays etc. -From Camel 2.3.0, camel provides a customer bean configuration for the -Error Handler, you can find the examples here. +[source,xml] +---- + <!-- here we configure our DeadLetterChannel --> + <bean id="myDeadLetterErrorHandler" class="org.apache.camel.builder.DeadLetterChannelBuilder"> + <!-- exchanges is routed to mock:dead in cased redelivery failed --> + <property name="deadLetterUri" value="mock:dead"/> + <!-- reference the redelivery policy to use --> + <property name="redeliveryPolicy" ref="myRedeliveryPolicyConfig"/> + </bean> + + <!-- here we set the redelivery settings --> + <bean id="myRedeliveryPolicyConfig" class="org.apache.camel.processor.errorhandler.RedeliveryPolicy"> + <!-- try redelivery at most 3 times, after that the exchange is dead and its routed to the mock:dead endpoint --> + <property name="maximumRedeliveries" value="3"/> + <!-- delay 250ms before redelivery --> + <property name="redeliveryDelay" value="250"/> + </bean> +---- -[[ErrorHandler-Usingthetransactionalerrorhandler]] == Using the transactional error handler The transactional error handler is based on spring transaction. This -requires the usage of the camel-spring component. + - See Transactional Client that has many +requires the usage of the camel-spring or camel-jta component. + +See xref:{eip-vc}:eips:transactional-client.adoc[Transactional Client] that has many samples for how to use and transactional behavior and configuration with this error handler.
