Claus Ibsen created CAMEL-24770:
-----------------------------------
Summary: docs - Java, XML and properties examples in the
documentation are out of date or wrong
Key: CAMEL-24770
URL: https://issues.apache.org/jira/browse/CAMEL-24770
Project: Camel
Issue Type: Task
Components: documentation
Reporter: Claus Ibsen
CAMEL-24710 validated the YAML route examples of the pages bundled in
camel-catalog. Measuring the other example kinds on 2026-09-16 (catalog pages
plus the user manual): 4,053 Java blocks, 2,717 XML blocks, 339 properties
blocks. Checked: the literal endpoint URIs (6,189 in Java, 4,317 in XML) and
Simple expressions (453) against the catalog, every XML {{<route>}} fragment
(1,838) with the camel-xml-io parser, the {{camel.*}} property keys, and a list
of Camel 2/3 API leftovers in Java. The user manual's YAML examples (230
blocks, 204 route files on 68 pages) were not covered by CAMEL-24710 either and
are measured here too.
Verified against the code, the examples that are wrong:
* Java using API removed in Camel 4: {{.inOut()}} (jms), {{.setFaultBody}}
(cxf), {{createRegistry()}} (lucene); {{getOut()}} (spring-ws, deprecated);
curly quotes in the jt400 Java and XML examples
* XML the XML DSL parser rejects: {{claimCheck headerName}} (is {{key}}),
datasonnet {{resultTypeName}} (is {{resultType}}), failover {{stickyMode}} (is
{{sticky}}), threads {{executorServiceRef}} (is {{executorService}}),
{{<univocity-csv>}} / {{-fixed}} / {{-tsv}} (are {{<univocityCsv>}}...),
{{<bindy ref>}} / {{<crypto ref>}}, {{<to method=...>}} (validate-eip),
{{<simple>...</xpath>}} (selective-consumer), unescaped {{&}} in XML attributes
(ftp, hivemq, mail, endpoint)
* Endpoint URIs: {{timer:java?period=1000,repeatCount=1}} (xpath), keycloak
{{setUserPassword}} (is {{resetUserPassword}}), azure-storage-blob
{{commitBlockBlobList}} (is {{commitBlobBlockList}}), ai-resource
{{aws2-s3://...?fileName=...&operation=getObject}} (the producer reads the key
from the header), consumer options on producers and vice versa (rocketmq, jooq,
virtual-threads), bean references without {{#}} (rss, http)
* Properties: {{camel.main.logInflightExchangesOnTimeout}} (is
{{shutdownLogInflightExchangesOnTimeout}}), a stray {{;}} (stream-caching), the
zookeeper cluster service keys (master)
* User manual YAML: a header that is an exchange property
(route-configuration), an unbalanced quote in a Simple (validator), YAML that
does not parse (camel-report-maven-plugin), string concatenation in a value
(improving-the-documentation)
Found on the way, for CAMEL-24748: the hardcoded operation enums of
azure-storage-blob (missing listBlobVersions, setBlobLegalHold,
setBlobImmutabilityPolicy) and git (missing pushTag) are stale.
The examples must all be right before the catalog MCP serves them as samples
and the build fails on an invalid one; the guards (user manual YAML in
CatalogDocExamplesTest, an XML guard on the parsed route fragments and their
URIs, the Java literal URIs and Simple) follow once the examples pass.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
