[jira] [Created] (CAMEL-24770) docs - Java, XML and properties examples in the documentation are out of date or wrong

["Claus Ibsen (Jira)" <ji...@apache.org>]

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)