CAMEL-23302: camel-xslt - Auto-disable content cache in routes-reload (dev) mode

[ammachado]

Description

CAMEL-23302: camel-xslt - Auto-disable content cache in routes-reload (dev) mode

When camel.main.routesReloadEnabled=true (set automatically by camel run --dev), Camel now sets contentCache to false on resource-based components (components exposing contentCache option, such as xslt, freemarker, velocity, mustache, jte, jolt, jslt, jsonata, json-validator, json-patch, mvel, chunk, stringtemplate, language) so that edits to the resource file are picked up on the next message without restarting the route.

Co-Authored-By: Claude Opus 4.7 noreply@anthropic.com

Target

• I checked that the commit is targeting the correct branch (Camel 4 uses the main branch)

Tracking

• If this is a large change, bug fix, or code improvement, I checked there is a JIRA issue filed for the change (usually before you start working on it).

Apache Camel coding standards and style

• I checked that each commit in the pull request has a meaningful subject line and body.
• I have run mvn clean install -DskipTests locally from root folder and I have committed all auto-generated changes.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds an SPI and Camel Main lifecycle strategy to automatically disable resource contentCache when routes-reload/dev mode is enabled, enabling live reload of resource files (first adopter: camel-xslt).

Changes:

• Introduces ContentCacheAware SPI and DevModeContentCacheStrategy to auto-disable contentCache when camel.main.routesReloadEnabled=true.
• Updates XsltComponent to implement the SPI with tri-state contentCache (null/unset vs explicit true/false), and updates generated metadata/configurer accordingly.
• Documents live reload behavior in the user manual and XSLT component docs, and adds Camel Main tests.

Reviewed changes

Copilot reviewed 8 out of 15 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
docs/user-manual/modules/ROOT/pages/route-reload.adoc	Documents resource live reload behavior when routes-reload is enabled
docs/user-manual/modules/ROOT/pages/camel-jbang.adoc	Documents --dev behavior tying to routesReloadEnabled and content cache
core/camel-main/src/test/java/org/apache/camel/main/MainDevModeContentCacheTest.java	Adds tests for auto-disabling and respecting explicit component-level settings
core/camel-main/src/main/java/org/apache/camel/main/DevModeContentCacheStrategy.java	Adds lifecycle strategy that flips contentCache on component add
core/camel-main/src/main/java/org/apache/camel/main/DefaultConfigurationConfigurer.java	Wires the lifecycle strategy when routes-reload is enabled
core/camel-api/src/main/java/org/apache/camel/spi/ContentCacheAware.java	Adds new SPI for tri-state contentCache
components/camel-xslt/src/main/java/org/apache/camel/component/xslt/XsltComponent.java	Implements SPI and switches contentCache to Boolean tri-state
components/camel-xslt/src/main/docs/xslt-component.adoc	Documents dev-mode live reload behavior for XSLT
components/camel-xslt/src/generated/resources/META-INF/org/apache/camel/component/xslt/xslt.json	Updates generated metadata to java.lang.Boolean
components/camel-xslt/src/generated/java/org/apache/camel/component/xslt/XsltComponentConfigurer.java	Updates configurer to bind/return Boolean tri-state
components/camel-xslt-saxon/src/generated/resources/META-INF/org/apache/camel/component/xslt/saxon/xslt-saxon.json	Updates generated metadata to java.lang.Boolean
components/camel-xj/src/generated/resources/META-INF/org/apache/camel/component/xj/xj.json	Updates generated metadata to java.lang.Boolean
catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/components/xslt.json	Updates catalog metadata to java.lang.Boolean
catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/components/xslt-saxon.json	Updates catalog metadata to java.lang.Boolean
catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/components/xj.json	Updates catalog metadata to java.lang.Boolean

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

🌟 Thank you for your contribution to the Apache Camel project! 🌟
🤖 CI automation will test this PR automatically.

🐫 Apache Camel Committers, please review the following items:

• First-time contributors require MANUAL approval for the GitHub Actions to run
• You can use the command /component-test (camel-)component-name1 (camel-)component-name2.. to request a test from the test bot although they are normally detected and executed by CI.
• You can label PRs using skip-tests and test-dependents to fine-tune the checks executed by this PR.
• Build and test logs are available in the summary page. Only Apache Camel committers have access to the summary.

⚠️ Be careful when sharing logs. Review their contents before sharing them publicly.

[gnodet]

Nice work on this PR! The tri-state Boolean approach for the ContentCacheAware SPI is a clean design, and the lifecycle strategy is the right integration point for dev-mode behavior.

A few items — see inline comments for specific suggestions:

1. Binary backward compatibility (setter signature change): see inline suggestion on XsltComponent.java
2. Class visibility: DevModeContentCacheStrategy could be package-private (see inline)
3. JIRA link: Consider adding [CAMEL-23302](https://issues.apache.org/jira/browse/CAMEL-23302) to the PR description body
4. Upgrade guide: Since ContentCacheAware is a new public SPI in camel-api, consider mentioning it in the 4.21 upgrade guide so other component authors know they can opt in

Claude Code on behalf of Guillaume Nodet

[Croway]

@ammachado there are uncommitted changes

There are uncommitted changes
HEAD detached at pull/23127/merge
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   dsl/camel-componentdsl/src/generated/java/org/apache/camel/builder/component/dsl/XjComponentBuilderFactory.java
	modified:   dsl/camel-componentdsl/src/generated/java/org/apache/camel/builder/component/dsl/XsltComponentBuilderFactory.java
	modified:   dsl/camel-componentdsl/src/generated/java/org/apache/camel/builder/component/dsl/XsltSaxonComponentBuilderFactory.java

You can cd dsl && man clean install -DskipTests once camel-xslt is built locally to quickly generate those files

[gnodet]

Alternative approach worth considering: use the existing PropertyConfigurer API instead of a new SPI

Rather than introducing ContentCacheAware in camel-api and migrating components one by one, the DevModeContentCacheStrategy could use the existing generated PropertyConfigurer to detect and set the contentCache property on any component that has it:

@Override
public void onComponentAdd(String name, Component component) {
    PropertyConfigurer configurer = PluginHelper.getConfigurerResolver(component.getCamelContext())
        .resolvePropertyConfigurer(name + "-component", component.getCamelContext());
    if (configurer instanceof PropertyConfigurerGetter getter) {
        Object val = getter.getOptionValue(component, "contentCache", true);
        if (Boolean.TRUE.equals(val)) {
            configurer.configure(component.getCamelContext(), component, "contentCache", false, true);
            LOG.info("Routes-reload is enabled: disabling contentCache on component '{}' for live resource reload", name);
        }
    }
}

Advantages:

• No new SPI interface in camel-api (smaller API surface)
• Works immediately for all ~13 components with contentCache (freemarker, velocity, mustache, jte, jolt, jslt, jsonata, json-validator, json-patch, mvel, chunk, stringtemplate, language) — no per-component migration needed
• No boolean → Boolean field change, so no binary compatibility concern
• The timing works for the common case: user properties via camel.component.<name>.contentCache=true are bound after onComponentAdd, so they naturally override the strategy's change

Downside:

• Cannot distinguish "default true" from "user explicitly set true programmatically before adding the component to the context" (e.g., component.setContentCache(true); context.addComponent(...)). The strategy would wrongly override it in that scenario. The tri-state Boolean (null = unset) in the current PR handles this edge case correctly.
• That said, programmatic pre-registration configuration is uncommon with Camel Main, which is the primary consumer of this feature.

Not a blocker — just flagging the trade-off for consideration.

Claude Code on behalf of Guillaume Nodet

[github-actions]

🧪 CI tested the following changed modules:

• components/camel-xslt
• core/camel-main
• docs

ℹ️ Dependent modules were not tested because the total number of affected modules exceeded the threshold (50). Use the test-dependents label to force testing all dependents.

Build reactor — dependencies compiled but only changed modules were tested (3 modules)

• Camel :: Docs
• Camel :: Main
• Camel :: XSLT

---

⚙️ View full build and test results