[
https://issues.apache.org/jira/browse/CAMEL-23789?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Claus Ibsen updated CAMEL-23789:
--------------------------------
Fix Version/s: 4.21.0
> Improve component docs code examples to be multi-DSL friendly (XML/YAML tabs)
> -----------------------------------------------------------------------------
>
> Key: CAMEL-23789
> URL: https://issues.apache.org/jira/browse/CAMEL-23789
> Project: Camel
> Issue Type: Improvement
> Components: documentation
> Reporter: Claus Ibsen
> Assignee: Claus Ibsen
> Priority: Major
> Fix For: 4.21.0
>
>
> While adding XML and YAML DSL tabs to component documentation (PR #24081
> added ~480 route examples across ~190 files), a large number of Java DSL code
> snippets could NOT be translated to XML/YAML because they rely on
> Java-specific constructs.
> This is a tracking issue to improve these code examples so they are multi-DSL
> friendly, making documentation more accessible for XML and YAML route
> authors, and easier for AI agents to translate.
> h3. Patterns that block XML/YAML translation
> The following Java-specific patterns in code examples prevent translation to
> XML/YAML DSL tabs:
> * *Java lambdas and anonymous Processor classes* — {{.process(exchange ->
> \{...\})}} and {{new Processor() \{...\}}} are used extensively. Many of
> these could be replaced with simple {{bean}} calls or
> {{setHeader}}/{{setBody}} with {{simple}} expressions.
> * *Java constants for header names* — {{SomeConstants.HEADER_NAME}} instead
> of the actual string value. The docs could show the resolved string values
> directly (e.g. {{CamelAwsS3Key}} instead of {{S3Constants.KEY}}).
> * *Java constants for operations/enums* — {{SomeEnum.VALUE}},
> {{TranslateLanguageEnum.ITALIAN}}, {{VoiceId.JOANNA}}. Could use string
> values instead.
> * *String concatenation for URIs* — {{"uri" + variable}} breaks the ability
> to show the URI in XML/YAML. Could use property placeholders instead.
> * *{{.toF()}} / {{.fromF()}} format strings* — Java-only DSL methods. Could
> be replaced with property placeholders.
> * *Java DataFormat/class variable references* — {{unmarshal(myVar)}},
> {{.avro(JsonNode.class)}}, {{.json(JsonLibrary.Jackson)}}. Could use the DSL
> name directly.
> * *{{template.sendBody()}} / {{consumerTemplate.receiveBody()}}* test API
> calls — Not routes, but shown as usage examples. Could add equivalent
> route-based examples.
> * *{{@BindToRegistry}} / {{@Bean}} / {{@Configuration}}* — Spring/CDI
> annotations for registry setup. Could add XML/YAML bean registration
> equivalents.
> * *{{RouteBuilder}} class definitions wrapping routes* — The route itself is
> tabbable, but it's buried inside a class definition. Could extract just the
> route.
> * *Complex EIP chains* — {{.split(body()).streaming()}}, {{.loopDoWhile()}},
> {{.idempotentConsumer()}} with Java method arguments. Some of these have
> XML/YAML equivalents but are non-trivial.
> * *Bean references via FQN class names* — XML and YAML can reference beans by
> fully qualified class name (e.g. {{<to uri="bean:com.foo.MyBean"/>}}), but
> many AI tools and contributors don't know this pattern well, so examples
> using {{.bean(MyClass.class)}} aren't being translated.
> h3. Suggested improvements
> # *Replace Java constants with string values in examples* — Show the actual
> header/operation name string so XML/YAML users can use it directly. Keep a
> note that Java users can use the constant.
> # *Replace lambdas with bean references where possible* — Use
> {{.bean("myProcessor")}} or {{.to("bean:myProcessor")}} instead of inline
> lambdas, with the bean class shown separately.
> # *Use property placeholders instead of string concatenation* — Replace
> {{"uri" + port}} with {{"uri?port=\{\{myPort\}\}"}}.
> # *Extract routes from RouteBuilder class definitions* — Show just the route
> DSL, not the surrounding Java class boilerplate.
> # *Add bean FQN examples* — Show that XML/YAML can call beans via
> {{bean:com.foo.MyClass}} without requiring registry setup.
> # *Make examples more low-code friendly* — Prefer {{simple}} expressions,
> {{setHeader}}/{{setBody}} with constants, and declarative patterns over
> imperative Java code.
> h3. Files with the most untranslated examples
> ||Component||Untranslated count||
> |camel-pqc|64|
> |camel-langchain4j-agent|50|
> |camel-bindy|49|
> |camel-mina-sftp|48|
> |camel-azure-storage-blob|35|
> |camel-aws2-s3|32|
> |camel-ibm-watsonx-ai|31|
> |camel-openai|30|
> |camel-spring-ai-chat|29|
> |camel-aws-bedrock|29|
> |camel-kafka|27|
> |camel-mongodb|26|
> |camel-salesforce|23|
> |camel-mock|22|
> |camel-dapr|21|
> |camel-jms|20|
> Related PR: https://github.com/apache/camel/pull/24081
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
