Claus Ibsen created CAMEL-23789:
-----------------------------------
Summary: 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
Reporter: Claus Ibsen
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)
