You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by da...@apache.org on 2026/09/14 08:19:20 UTC

(camel) branch main updated: CAMEL-24713: user manual - fix the YAML examples that do not validate; camel-yaml-dsl - add delayer to route (#26390)

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 1bd86b010266 CAMEL-24713: user manual - fix the YAML examples that do not validate; camel-yaml-dsl - add delayer to route (#26390)
1bd86b010266 is described below

commit 1bd86b010266fb3e57a6740e33dfce96e957d89c
Author: Claus Ibsen <cl...@gmail.com>
AuthorDate: Mon Sep 14 10:19:14 2026 +0200

    CAMEL-24713: user manual - fix the YAML examples that do not validate; camel-yaml-dsl - add delayer to route (#26390)
    
    * CAMEL-24713: user manual - fix the YAML examples that do not validate; camel-yaml-dsl - add delayer to route
    
    Every [source,yaml] route example of the user manual now passes the YAML DSL validator (186 blocks; the 17 that remain invalid are the old-syntax blocks of the upgrade guides and other pages that are deliberately not Camel YAML). This is a prerequisite for generating the camel_catalog_sample fallback (eip-samples.json) from the docs in the build.
    
    Doc fixes (11 pages, 18 blocks):
    - oncompletion.adoc, error-handler.adoc: route scoped onCompletion/onException written as steps; YAML has no route scope, so use a routeConfiguration the route refers to (or the top-level entry when the Java example is global). executorServiceRef -> executorService.
    - exception-advanced.adoc, exception-handling-patterns.adoc, try-catch-finally.adoc: redeliveryPolicy and onWhen are properties of onException/doCatch, not steps; beanType -> type.
    - transformer.adoc, validator.adoc: inputType is a route property, not a step; endpointTransformer has no parameters, put them on the uri.
    - routes.adoc: jaxb needs contextPath. rest-dsl-openapi.adoc: bindingMode is an enum. route-template-bean-binding.adoc: a template bean needs type. virtual-threads.adoc: threads has no steps.
    
    delay-interceptor.adoc was right but the YAML DSL lacked the route delayer option that the model has: added to RouteDefinitionDeserializer, schema regenerated (camel-yaml-dsl and the camel-catalog mirror), covered in RoutesTest.
    
    Co-Authored-By: Claude Opus 5 (1M context) <no...@anthropic.com>
    Signed-off-by: Claus Ibsen <cl...@gmail.com>
    
    * CAMEL-24713: oncompletion.adoc - the YAML prose names the executorService option like its example
    
    Co-Authored-By: Claude Opus 5 (1M context) <no...@anthropic.com>
    Signed-off-by: Claus Ibsen <cl...@gmail.com>
    
    ---------
    
    Signed-off-by: Claus Ibsen <cl...@gmail.com>
    Co-authored-by: Claude Opus 5 (1M context) <no...@anthropic.com>
---
 .../camel/catalog/schemas/camelYamlDsl-model.json  |  9 ++++
 .../modules/ROOT/pages/error-handler.adoc          | 25 ++++-----
 .../modules/ROOT/pages/exception-advanced.adoc     | 12 ++---
 .../ROOT/pages/exception-handling-patterns.adoc    |  6 +--
 .../modules/ROOT/pages/oncompletion.adoc           | 62 +++++++++++++---------
 .../modules/ROOT/pages/rest-dsl-openapi.adoc       |  2 +-
 .../ROOT/pages/route-template-bean-binding.adoc    |  2 +
 docs/user-manual/modules/ROOT/pages/routes.adoc    |  3 +-
 .../modules/ROOT/pages/transformer.adoc            | 16 +++---
 .../modules/ROOT/pages/try-catch-finally.adoc      |  6 +--
 docs/user-manual/modules/ROOT/pages/validator.adoc |  6 +--
 .../modules/ROOT/pages/virtual-threads.adoc        |  7 ++-
 .../deserializers/RouteDefinitionDeserializer.java |  5 ++
 .../resources/schema/camelYamlDsl-canonical.json   |  4 ++
 .../resources/schema/camelYamlDsl-model.json       |  9 ++++
 .../generated/resources/schema/camelYamlDsl.json   |  4 ++
 .../org/apache/camel/dsl/yaml/RoutesTest.groovy    |  2 +
 17 files changed, 111 insertions(+), 69 deletions(-)

diff --git a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/schemas/camelYamlDsl-model.json b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/schemas/camelYamlDsl-model.json
index bdb568662433..b82ef585f419 100644
--- a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/schemas/camelYamlDsl-model.json
+++ b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/schemas/camelYamlDsl-model.json
@@ -6978,6 +6978,15 @@
         "group" : "advanced",
         "label" : "advanced",
         "default" : "false"
+      }, {
+        "name" : "delayer",
+        "type" : "string",
+        "description" : "Whether to slow down processing messages by a given delay in msec.",
+        "displayName" : "Delayer",
+        "kind" : "attribute",
+        "index" : 12,
+        "group" : "advanced",
+        "label" : "advanced"
       }, {
         "name" : "errorHandlerRef",
         "type" : "string",
diff --git a/docs/user-manual/modules/ROOT/pages/error-handler.adoc b/docs/user-manual/modules/ROOT/pages/error-handler.adoc
index 0caebab478cb..b5af1a4d6beb 100644
--- a/docs/user-manual/modules/ROOT/pages/error-handler.adoc
+++ b/docs/user-manual/modules/ROOT/pages/error-handler.adoc
@@ -319,13 +319,13 @@ YAML::
         redeliveryPolicy:
           maximumRedeliveries: 3
           redeliveryDelay: 250
-    steps:
-      - process:
-          ref: myFailureProcessor
-      - to:
-          uri: mock:result
     from:
       uri: direct:in
+      steps:
+        - process:
+            ref: myFailureProcessor
+        - to:
+            uri: mock:result
 ----
 ====
 
@@ -467,23 +467,24 @@ YAML::
 +
 [source,yaml]
 ----
+- onException:
+    # in case of io exception then try to redeliver up till 2 times
+    # (do not use any delay due faster unit testing)
+    exception:
+      - java.io.IOException
+    redeliveryPolicy:
+      maximumRedeliveries: 2
+      redeliveryDelay: 0
 - route:
     from:
       uri: direct:start
       steps:
-        - onException:
-            exception:
-              - java.io.IOException
-        - redeliveryPolicy:
-            maximumRedeliveries: 2
-            redeliveryDelay: 0
         - to:
             uri: mock:a
         - to:
             uri: direct:sub
         - to:
             uri: mock:c
-
 - route:
     errorHandler:
       noErrorHandler: {}
diff --git a/docs/user-manual/modules/ROOT/pages/exception-advanced.adoc b/docs/user-manual/modules/ROOT/pages/exception-advanced.adoc
index 44d3e09e18c5..144861f65914 100644
--- a/docs/user-manual/modules/ROOT/pages/exception-advanced.adoc
+++ b/docs/user-manual/modules/ROOT/pages/exception-advanced.adoc
@@ -206,14 +206,12 @@ YAML::
 - onException:
     exception:
       - com.foo.MyUserException
+    redeliveryPolicy:
+      maximumRedeliveries: 1
+      redeliveryDelay: 0
+    onWhen:
+      simple: "${header.user} != null"
     steps:
-      - redeliveryPolicy:
-          maximumRedeliveries: 1
-          redeliveryDelay: 0
-      - onWhen:
-          expression:
-            simple:
-              expression: "${header.user} != null"
       - to:
           uri: mock:error
 - onException:
diff --git a/docs/user-manual/modules/ROOT/pages/exception-handling-patterns.adoc b/docs/user-manual/modules/ROOT/pages/exception-handling-patterns.adoc
index 27d86ae6c4d0..8f4d84d210e0 100644
--- a/docs/user-manual/modules/ROOT/pages/exception-handling-patterns.adoc
+++ b/docs/user-manual/modules/ROOT/pages/exception-handling-patterns.adoc
@@ -281,7 +281,7 @@ And the same example in YAML DSL
 ----
 - beans:
   - name: "orderService"
-    beanType: "org.apache.camel.spring.processor.onexception.OrderService"
+    type: "org.apache.camel.spring.processor.onexception.OrderService"
 - errorHandler:
     deadLetterChannel:
       deadLetterUri: mock:error
@@ -291,9 +291,9 @@ And the same example in YAML DSL
     handled:
       constant:
         expression: "true"
+    redeliveryPolicy:
+      maximumRedeliveries: 1
     steps:
-      - redeliveryPolicy:
-          maximumRedeliveries: 1
       - bean:
           ref: orderService
           method: orderFailed
diff --git a/docs/user-manual/modules/ROOT/pages/oncompletion.adoc b/docs/user-manual/modules/ROOT/pages/oncompletion.adoc
index 81984e74a7c0..58d590981be0 100644
--- a/docs/user-manual/modules/ROOT/pages/oncompletion.adoc
+++ b/docs/user-manual/modules/ROOT/pages/oncompletion.adoc
@@ -88,18 +88,24 @@ XML::
 
 YAML::
 +
+In YAML a route scoped `onCompletion` is declared in a `routeConfiguration` that the route refers to, so it only applies to that route.
++
 [source,yaml]
 ----
+- routeConfiguration:
+    id: myConfig
+    onCompletion:
+      - onCompletion:
+          steps:
+            - to:
+                uri: log:sync
+            - to:
+                uri: mock:sync
 - route:
+    routeConfigurationId: myConfig
     from:
       uri: direct:start
       steps:
-        - onCompletion:
-            steps:
-              - to:
-                  uri: log:sync
-              - to:
-                  uri: mock:sync
         - process:
             ref: myProcessor
         - to:
@@ -156,17 +162,21 @@ YAML::
 +
 [source,yaml]
 ----
+- routeConfiguration:
+    id: myConfig
+    onCompletion:
+      - onCompletion:
+          onFailureOnly: "true"
+          steps:
+            - to:
+                uri: log:sync
+            - to:
+                uri: mock:sync
 - route:
+    routeConfigurationId: myConfig
     from:
       uri: direct:start
       steps:
-        - onCompletion:
-            onFailureOnly: "true"
-            steps:
-              - to:
-                  uri: log:sync
-              - to:
-                  uri: mock:sync
         - process:
             ref: myProcessor
         - to:
@@ -290,20 +300,22 @@ YAML::
 +
 [source,yaml]
 ----
+- routeConfiguration:
+    id: myConfig
+    onCompletion:
+      - onCompletion:
+          onWhen:
+            simple: "${body} contains 'Hello'"
+          steps:
+            - to:
+                uri: log:sync
+            - to:
+                uri: mock:sync
 - route:
+    routeConfigurationId: myConfig
     from:
       uri: direct:start
       steps:
-        - onCompletion:
-            steps:
-              - onWhen:
-                  expression:
-                    simple:
-                      expression: "${body} contains 'Hello'"
-              - to:
-                  uri: log:sync
-              - to:
-                  uri: mock:sync
         - to:
             uri: log:original
         - to:
@@ -372,12 +384,12 @@ YAML::
 ----
 +
 You can also refer to a specific thread pool
-to be used, using the `executorServiceRef` option
+to be used, using the `executorService` option
 +
 [source,yaml]
 ----
 - onCompletion:
-    executorServiceRef: myThreadPool
+    executorService: myThreadPool
     steps:
       - to:
           uri: mock:before
diff --git a/docs/user-manual/modules/ROOT/pages/rest-dsl-openapi.adoc b/docs/user-manual/modules/ROOT/pages/rest-dsl-openapi.adoc
index 9983bcaa769f..88d138fd57af 100644
--- a/docs/user-manual/modules/ROOT/pages/rest-dsl-openapi.adoc
+++ b/docs/user-manual/modules/ROOT/pages/rest-dsl-openapi.adoc
@@ -455,7 +455,7 @@ YAML::
 [source,yaml]
 ----
 - restConfiguration:
-    bindingMode: true
+    bindingMode: json
     bindingPackageScan: sample.petstore.model
 ----
 
diff --git a/docs/user-manual/modules/ROOT/pages/route-template-bean-binding.adoc b/docs/user-manual/modules/ROOT/pages/route-template-bean-binding.adoc
index bee62f0330af..9c8b6ae1ac5f 100644
--- a/docs/user-manual/modules/ROOT/pages/route-template-bean-binding.adoc
+++ b/docs/user-manual/modules/ROOT/pages/route-template-bean-binding.adoc
@@ -361,6 +361,7 @@ Notice how the Groovy code can be inlined directly in the route template in DSL
       - name: "bucket"
     beans:
       - name: "myClient"
+        type: "software.amazon.awssdk.services.s3.S3Client"
         scriptLanguage: "groovy"
         script: |
             import software.amazon.awssdk.services.s3.S3Client
@@ -543,6 +544,7 @@ YAML::
       - name: "bucket"
     beans:
       - name: "myClient"
+        type: "software.amazon.awssdk.services.s3.S3Client"
         scriptLanguage: "bean"
         script: "com.foo.MyAwsHelper?method=createS3Client"
     from:
diff --git a/docs/user-manual/modules/ROOT/pages/routes.adoc b/docs/user-manual/modules/ROOT/pages/routes.adoc
index ccaad5f3d31b..a2398252b001 100644
--- a/docs/user-manual/modules/ROOT/pages/routes.adoc
+++ b/docs/user-manual/modules/ROOT/pages/routes.adoc
@@ -252,7 +252,8 @@ YAML::
       uri: "direct:in"
       steps:
         - unmarshal:
-            jaxb: {}
+            jaxb:
+              contextPath: com.foo.model
         - to:
             uri: direct:out
 ----
diff --git a/docs/user-manual/modules/ROOT/pages/transformer.adoc b/docs/user-manual/modules/ROOT/pages/transformer.adoc
index ac8f5c3b45cb..9b56b4569338 100644
--- a/docs/user-manual/modules/ROOT/pages/transformer.adoc
+++ b/docs/user-manual/modules/ROOT/pages/transformer.adoc
@@ -80,11 +80,11 @@ YAML::
 [source,yaml]
 ----
 - route:
+    inputType:
+      urn: myScheme:myTransformer
     from:
       uri: direct:abc
       steps:
-        - inputType:
-            urn: myScheme:myTransformer
         - to:
             uri: "log:abc"
 ----
@@ -194,9 +194,7 @@ YAML::
 ----
 - transformers:
     endpointTransformer:
-      uri: component:componentPathOptions
-      parameters:
-        mappingFile: myMapping.xml
+      uri: component:componentPathOptions?mappingFile=myMapping.xml
       fromType: xml
       toType: json
 ----
@@ -414,19 +412,19 @@ YAML::
 [source,yaml]
 ----
 - route:
+    inputType:
+      urn: xml:ABCOrder
     from:
       uri: direct:abc
       steps:
-        - inputType:
-            urn: xml:ABCOrder
         - to:
             uri: direct:xyz
 - route:
+    inputType:
+      urn: xml:XYZOrder
     from:
       uri: direct:xyz
       steps:
-        - inputType:
-            urn: xml:XYZOrder
         - to:
             uri: somewhere:else
 ----
diff --git a/docs/user-manual/modules/ROOT/pages/try-catch-finally.adoc b/docs/user-manual/modules/ROOT/pages/try-catch-finally.adoc
index dc70a4048b11..52462957ed12 100644
--- a/docs/user-manual/modules/ROOT/pages/try-catch-finally.adoc
+++ b/docs/user-manual/modules/ROOT/pages/try-catch-finally.adoc
@@ -163,11 +163,9 @@ YAML::
                   exception:
                     - java.io.IOException
                     - java.lang.IllegalStateException
+                  onWhen:
+                    simple: "${exception.message} contains 'Damn'"
                   steps:
-                    - onWhen:
-                        expression:
-                          simple:
-                            expression: "${exception.message} contains 'Damn'"
                     - to:
                         uri: mock:catch
               - doCatch:
diff --git a/docs/user-manual/modules/ROOT/pages/validator.adoc b/docs/user-manual/modules/ROOT/pages/validator.adoc
index f92328296c45..4d200a787dd4 100644
--- a/docs/user-manual/modules/ROOT/pages/validator.adoc
+++ b/docs/user-manual/modules/ROOT/pages/validator.adoc
@@ -244,12 +244,12 @@ YAML::
 [source,yaml]
 ----
 - route:
+    inputType:
+      urn: xml:ABCOrder
+      validate: "true"
     from:
       uri: direct:abc
       steps:
-        - inputType:
-            urn: xml:ABCOrder
-            validate: "true"
         - log:
             message: "${body}"
 ----
diff --git a/docs/user-manual/modules/ROOT/pages/virtual-threads.adoc b/docs/user-manual/modules/ROOT/pages/virtual-threads.adoc
index 50e7a0e9583a..ff84c1dea1c5 100644
--- a/docs/user-manual/modules/ROOT/pages/virtual-threads.adoc
+++ b/docs/user-manual/modules/ROOT/pages/virtual-threads.adoc
@@ -208,10 +208,9 @@ YAML::
     from:
       uri: platform-http:/api/orders
       steps:
-        - threads:
-            steps:
-              - to:
-                  uri: jpa:Order
+        - threads: {}
+        - to:
+            uri: jpa:Order
 ----
 ====
 
diff --git a/dsl/camel-yaml-dsl/camel-yaml-dsl-deserializers/src/main/java/org/apache/camel/dsl/yaml/deserializers/RouteDefinitionDeserializer.java b/dsl/camel-yaml-dsl/camel-yaml-dsl-deserializers/src/main/java/org/apache/camel/dsl/yaml/deserializers/RouteDefinitionDeserializer.java
index ab0f0868fe06..fa6d7e04cd2d 100644
--- a/dsl/camel-yaml-dsl/camel-yaml-dsl-deserializers/src/main/java/org/apache/camel/dsl/yaml/deserializers/RouteDefinitionDeserializer.java
+++ b/dsl/camel-yaml-dsl/camel-yaml-dsl-deserializers/src/main/java/org/apache/camel/dsl/yaml/deserializers/RouteDefinitionDeserializer.java
@@ -55,6 +55,8 @@ import org.snakeyaml.engine.v2.nodes.NodeTuple;
                   @YamlProperty(name = "messageHistory", type = "boolean"),
                   @YamlProperty(name = "logMask", type = "boolean"),
                   @YamlProperty(name = "trace", type = "boolean"),
+                  @YamlProperty(name = "delayer", type = "string",
+                                description = "Whether to slow down processing messages by a given delay in msec."),
                   @YamlProperty(name = "errorHandlerRef", type = "string"),
                   @YamlProperty(name = "errorHandler", type = "object:org.apache.camel.model.ErrorHandlerDefinition"),
                   @YamlProperty(name = "shutdownRoute", type = "enum:Default,Defer",
@@ -145,6 +147,9 @@ public class RouteDefinitionDeserializer extends YamlDeserializerBase<RouteDefin
                 case "trace":
                     target.setTrace(asText(val));
                     break;
+                case "delayer":
+                    target.setDelayer(asText(val));
+                    break;
                 case "errorHandlerRef":
                     target.setErrorHandlerRef(asText(val));
                     break;
diff --git a/dsl/camel-yaml-dsl/camel-yaml-dsl/src/generated/resources/schema/camelYamlDsl-canonical.json b/dsl/camel-yaml-dsl/camel-yaml-dsl/src/generated/resources/schema/camelYamlDsl-canonical.json
index 4dfb19e8ff52..ca5acb6280f6 100644
--- a/dsl/camel-yaml-dsl/camel-yaml-dsl/src/generated/resources/schema/camelYamlDsl-canonical.json
+++ b/dsl/camel-yaml-dsl/camel-yaml-dsl/src/generated/resources/schema/camelYamlDsl-canonical.json
@@ -4113,6 +4113,10 @@
           "autoStartup" : {
             "type" : "boolean"
           },
+          "delayer" : {
+            "type" : "string",
+            "description" : "Whether to slow down processing messages by a given delay in msec."
+          },
           "description" : {
             "type" : "string"
           },
diff --git a/dsl/camel-yaml-dsl/camel-yaml-dsl/src/generated/resources/schema/camelYamlDsl-model.json b/dsl/camel-yaml-dsl/camel-yaml-dsl/src/generated/resources/schema/camelYamlDsl-model.json
index bdb568662433..b82ef585f419 100644
--- a/dsl/camel-yaml-dsl/camel-yaml-dsl/src/generated/resources/schema/camelYamlDsl-model.json
+++ b/dsl/camel-yaml-dsl/camel-yaml-dsl/src/generated/resources/schema/camelYamlDsl-model.json
@@ -6978,6 +6978,15 @@
         "group" : "advanced",
         "label" : "advanced",
         "default" : "false"
+      }, {
+        "name" : "delayer",
+        "type" : "string",
+        "description" : "Whether to slow down processing messages by a given delay in msec.",
+        "displayName" : "Delayer",
+        "kind" : "attribute",
+        "index" : 12,
+        "group" : "advanced",
+        "label" : "advanced"
       }, {
         "name" : "errorHandlerRef",
         "type" : "string",
diff --git a/dsl/camel-yaml-dsl/camel-yaml-dsl/src/generated/resources/schema/camelYamlDsl.json b/dsl/camel-yaml-dsl/camel-yaml-dsl/src/generated/resources/schema/camelYamlDsl.json
index c7ea8009c56d..a4e1d4bb570a 100644
--- a/dsl/camel-yaml-dsl/camel-yaml-dsl/src/generated/resources/schema/camelYamlDsl.json
+++ b/dsl/camel-yaml-dsl/camel-yaml-dsl/src/generated/resources/schema/camelYamlDsl.json
@@ -5379,6 +5379,10 @@
           "autoStartup" : {
             "type" : "boolean"
           },
+          "delayer" : {
+            "type" : "string",
+            "description" : "Whether to slow down processing messages by a given delay in msec."
+          },
           "description" : {
             "type" : "string"
           },
diff --git a/dsl/camel-yaml-dsl/camel-yaml-dsl/src/test/groovy/org/apache/camel/dsl/yaml/RoutesTest.groovy b/dsl/camel-yaml-dsl/camel-yaml-dsl/src/test/groovy/org/apache/camel/dsl/yaml/RoutesTest.groovy
index eadf95a40c0c..4d3547114189 100644
--- a/dsl/camel-yaml-dsl/camel-yaml-dsl/src/test/groovy/org/apache/camel/dsl/yaml/RoutesTest.groovy
+++ b/dsl/camel-yaml-dsl/camel-yaml-dsl/src/test/groovy/org/apache/camel/dsl/yaml/RoutesTest.groovy
@@ -289,6 +289,7 @@ class RoutesTest extends YamlTestSupport {
                     routePolicyRef: "myPolicy"
                     shutdownRoute: "Defer"
                     shutdownRunningTask: "CompleteAllTasks"
+                    delayer: "200"
                     from:
                       uri: "direct:info"
                       steps:
@@ -305,6 +306,7 @@ class RoutesTest extends YamlTestSupport {
             routePolicyRef == 'myPolicy'
             shutdownRoute == "Defer"
             shutdownRunningTask == "CompleteAllTasks"
+            delayer == '200'
             input.endpointUri == 'direct:info'
 
             with (outputs[0], LogDefinition) {