Skip to content

camel-thymeleaf: deprecate CamelThymeleafServletContext, which nothing reads - #29956

Merged
davsclaus merged 6 commits into
apache:mainfrom
Dhairya-007:fix/thymeleaf-deprecate-servlet-context-header
Nov 15, 2026
Merged

davsclaus merged 6 commits into
apache:mainfrom
Dhairya-007:fix/thymeleaf-deprecate-servlet-context-header

Conversation

@Dhairya-007

Copy link
Copy Markdown
Contributor

Problem

ThymeleafConstants publishes a header that the component never looks up:

@Metadata(description = "The ServletContext for a web application.", javaType = "jakarta.servlet.ServletContext")
public static final String THYMELEAF_SERVLET_CONTEXT = "CamelThymeleafServletContext";

CamelThymeleafServletContext appears nowhere else in the component - not in ThymeleafEndpoint, ThymeleafProducer or ThymeleafComponent, and not in a test. The component does not handle a ServletContext anywhere; the WebApplicationTemplateResolver is built from a field on the endpoint instead:

private JakartaServletWebApplication jakartaServletWebApplication;
...
private ITemplateResolver webApplicationTemplateResolver() {
    WebApplicationTemplateResolver resolver = new WebApplicationTemplateResolver(jakartaServletWebApplication);

which setJakartaServletWebApplication fills in.

That matches the Thymeleaf 3.1 API: the ServletContext-based web context was replaced by IWebApplication / JakartaServletWebApplication, and WebApplicationTemplateResolver takes the latter. So the header has nothing it could be passed to any more - setting it is silently ignored, while the catalog lists it as a supported header with a jakarta.servlet.ServletContext type.

Fix

Deprecate the constant with a deprecationNote pointing at jakartaServletWebApplication, so the catalog stops advertising it. The constant stays, so nothing stops compiling.

The regenerated thymeleaf.json files are included.

…g reads

The header is documented as "The ServletContext for a web application",
but no code in the component looks it up. The web application template
resolver is built from the endpoint's jakartaServletWebApplication
field:

    WebApplicationTemplateResolver resolver
            = new WebApplicationTemplateResolver(jakartaServletWebApplication);

which is set by setJakartaServletWebApplication, and nothing else in the
component touches a ServletContext at all - thymeleaf 3.1 dropped the
ServletContext-based web context in favour of
IWebApplication/JakartaServletWebApplication, which is what the resolver
takes now.

Deprecate the constant with a note pointing at the setter.

@gnodet-bot gnodet-bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM overall — the analysis in the PR description is correct and the fix is minimal. One missing piece before this is ready.

Missing upgrade guide entry. AGENTS.md requires that any deprecation be documented in the upgrade guide. The header CamelThymeleafServletContext is deprecated in this PR but camel-4x-upgrade-guide-4_24.adoc has no entry for it. Other header deprecations in this release (e.g. CamelGoogleVertexAIChatMessages, CamelNeo4jLabel, STS2Constants.SECRET_KEY_ID) all have upgrade guide entries following the same pattern. Please add one — something like:

=== camel-thymeleaf - CamelThymeleafServletContext header is deprecated

The `CamelThymeleafServletContext` header constant is deprecated. It was never read by the component: since Thymeleaf 3.1 the web application template resolver is built from the `jakartaServletWebApplication` set on the endpoint, not from a `ServletContext` passed as a header. Setting this header has been silently ignored since the component was introduced. Use the `jakartaServletWebApplication` endpoint option instead.

This review was generated by an AI agent, Hermès on behalf of @gnodet.

@github-actions

Copy link
Copy Markdown
Contributor

🌟 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.

@davsclaus davsclaus left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! I confirmed THYMELEAF_SERVLET_CONTEXT is never read on main, nor in 4.4.0/4.10.0, and the WEB_APP resolver is built from jakartaServletWebApplication. Deprecation makes sense.

  1. The generated description reads "The ServletContext for a web application.. Deprecation note: ..." (both JSON files). The generator only adds a '.' when the description does not already end with one, so it would write a single period; this looks hand-edited and CI's regen check will probably differ. Could you regenerate it with the build?
  2. ThymeleafEndpointBuilderFactory (dsl/camel-endpointdsl/src/generated/..., thymeleafServletContext()) also needs regenerating, as in #29709.
  3. Please add a short entry to camel-4x-upgrade-guide-4_24.adoc.
  4. [Suggestion] jakartaServletWebApplication is not a URI option, only ThymeleafEndpoint.setJakartaServletWebApplication(...). The note at ThymeleafConstants.java:36-40 could say that, so users know where to set it.

Claude Code on behalf of davsclaus. This review was generated by an AI agent and may contain inaccuracies; please verify all suggestions before applying.

@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

✅ Generated files are up to date

An earlier CI run reported uncommitted generated changes; the latest run no longer does.

@gnodet-bot gnodet-bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Following up on my earlier review — the regen commit addresses the mechanical pieces. One issue remains.

What was addressed:

  • ✅ @Deprecated added to ThymeleafConstants.THYMELEAF_SERVLET_CONTEXT
  • ✅ deprecationNote set correctly in @Metadata
  • ✅ Both catalog JSON files regenerated: deprecated: true and deprecationNote present
  • ✅ ThymeleafEndpointBuilderFactory.thymeleafServletContext() regenerated with @Deprecated

Still open: upgrade guide entry missing

camel-4x-upgrade-guide-4_24.adoc has not been updated. Every header deprecation in this release cycle has a corresponding upgrade guide entry (see e.g. CamelNeo4jLabel, CamelGoogleVertexAIChatMessages). Please add one, e.g.:

=== camel-thymeleaf - CamelThymeleafServletContext header is deprecated

The `CamelThymeleafServletContext` header constant is deprecated. It was never read by the component: since Thymeleaf 3.1 the web application template resolver is built from the `jakartaServletWebApplication` set on the endpoint (via `ThymeleafEndpoint.setJakartaServletWebApplication(...)`), not from a `ServletContext` passed as a header. Setting this header has been silently ignored. Use the `jakartaServletWebApplication` endpoint option instead.

Note: jakartaServletWebApplication is not a URI option — it must be set programmatically on ThymeleafEndpoint (this also addresses davsclaus's point 4 from the previous review).

This review was generated by an AI agent, Hermès on behalf of @gnodet.

@github-actions github-actions Bot added the dsl label Nov 14, 2026

@davsclaus davsclaus left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, the Regen commit fixed the doubled period in both thymeleaf.json files and added @Deprecated to thymeleafServletContext() in ThymeleafEndpointBuilderFactory, so those points are done.

  1. Please add a short entry for the deprecated CamelThymeleafServletContext header to docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_24.adoc.
  2. [Suggestion] ThymeleafConstants.java:37-38: jakartaServletWebApplication is not a URI option; it is set with ThymeleafEndpoint.setJakartaServletWebApplication(...). Naming that setter in the note would tell users where to set it (the JSON files and the endpoint DSL then need regenerating again).

Claude Code on behalf of davsclaus. This review was generated by an AI agent and may contain inaccuracies; please verify all suggestions before applying.

@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

🧪 CI tested the following changed modules:

  • catalog/camel-catalog
  • components/camel-thymeleaf
  • docs
  • dsl/camel-endpointdsl

🔬 Scalpel shadow comparison — Scalpel: 9 of 726 tested, 24 compile-only — current: 9 all tested

Maveniverse Scalpel detected 9 affected modules (current approach: 9).

Skip-tests mode would test 9 modules (4 direct + 8 downstream), skip tests for 24 (generated code, meta-modules)

Modules Scalpel would test (9)
  • camel-jbang-mcp ← downstream of org.apache.camel:camel-catalog
  • camel-jbang-plugin-mcp ← downstream of org.apache.camel:camel-jbang-core
  • camel-jbang-plugin-tui ← downstream of org.apache.camel:camel-catalog
  • camel-jbang-plugin-validate ← downstream of org.apache.camel:camel-yaml-dsl-validator
  • camel-jbang-run ← downstream of org.apache.camel:camel-catalog
  • camel-launcher-container ← downstream of org.apache.camel:camel-launcher
  • camel-thymeleaf ← components/camel-thymeleaf/src/generated/resources/META-INF/org/apache/camel/component/thymeleaf/thymeleaf.json, components/camel-thymeleaf/src/main/java/org/apache/camel/component/thymeleaf/ThymeleafConstants.java
  • camel-yaml-dsl-validator ← downstream of org.apache.camel:camel-catalog
  • camel-yaml-dsl-validator-maven-plugin ← downstream of org.apache.camel:camel-yaml-dsl-validator
Modules with tests skipped (24)
  • apache-camel
  • camel-allcomponents
  • camel-catalog-console
  • camel-catalog-maven
  • camel-catalog-suggest
  • camel-componentdsl
  • camel-endpointdsl-support
  • camel-itest
  • camel-jbang-core
  • camel-jbang-it
  • camel-jbang-main
  • camel-jbang-plugin-edit
  • camel-jbang-plugin-generate
  • camel-jbang-plugin-kubernetes
  • camel-jbang-plugin-test
  • camel-kamelet-main
  • camel-launcher
  • camel-report-maven-plugin
  • camel-route-parser
  • camel-yaml-dsl
  • camel-yaml-dsl-deserializers
  • camel-yaml-dsl-maven-plugin
  • coverage
  • dummy-component

ℹ️ Shadow mode — Scalpel observes but does not affect test execution. Learn more

All tested modules (36 modules, 5m 13s total)

Total reactor time: 5m 13s

Module Duration Status
Camel :: JBang :: Plugin :: TUI 42.5s SUCCESS
Camel :: JBang :: MCP 41.9s SUCCESS
Camel :: JBang :: Plugin :: Validate 21.9s SUCCESS
Camel :: YAML DSL :: Validator 21.9s SUCCESS
Camel :: YAML DSL 20.5s SUCCESS
Camel :: JBang :: Run 19.6s SUCCESS
Camel :: Component DSL 18.7s SUCCESS
Camel :: Catalog :: Camel Catalog 16.9s SUCCESS
Camel :: JBang :: Plugin :: Kubernetes 12.5s SUCCESS
Camel :: Thymeleaf 12.0s SUCCESS
Camel :: Docs 11.3s SUCCESS
Camel :: Kamelet Main 11.2s SUCCESS
Camel :: JBang :: Plugin :: Testing 10.4s SUCCESS
Camel :: YAML DSL :: Deserializers 7.0s SUCCESS
Camel :: JBang :: Plugin :: Generate 6.5s SUCCESS
Camel :: Catalog :: Camel Route Parser 6.5s SUCCESS
Camel :: Catalog :: Camel Report Maven Plugin 6.4s SUCCESS
Camel :: Assembly 4.1s SUCCESS
Camel :: All Components Sync point 3.4s SUCCESS
Camel :: YAML DSL :: Maven Plugins 2.7s SUCCESS
Camel :: Catalog :: Maven 2.7s SUCCESS
Camel :: YAML DSL :: Validator Maven Plugin 1.9s SUCCESS
Camel :: Catalog :: Suggest (deprecated) 1.9s SUCCESS
Camel :: Coverage 1.4s SUCCESS
Camel :: JBang :: Plugin :: MCP 1.2s SUCCESS
Camel :: JBang :: Plugin :: Edit 1.2s SUCCESS
Camel :: JBang :: Main 1.2s SUCCESS
Camel :: Catalog :: Dummy Component 1.0s SUCCESS
Camel :: Endpoint DSL :: Support 1.0s SUCCESS
Camel :: JBang :: Integration tests 0.9s SUCCESS
Camel :: Catalog :: Console 0.9s SUCCESS
Camel :: Launcher :: Container 0.6s SUCCESS
Camel :: Endpoint DSL n/a
Camel :: Integration Tests n/a
Camel :: JBang :: Core n/a
Camel :: Launcher n/a

Top 20 slowest modules:

  • Camel :: JBang :: Plugin :: TUI (42.5s)
  • Camel :: JBang :: MCP (41.9s)
  • Camel :: JBang :: Plugin :: Validate (21.9s)
  • Camel :: YAML DSL :: Validator (21.9s)
  • Camel :: YAML DSL (20.5s)
  • Camel :: JBang :: Run (19.6s)
  • Camel :: Component DSL (18.7s)
  • Camel :: Catalog :: Camel Catalog (16.9s)
  • Camel :: JBang :: Plugin :: Kubernetes (12.5s)
  • Camel :: Thymeleaf (12.0s)
  • Camel :: Docs (11.3s)
  • Camel :: Kamelet Main (11.2s)
  • Camel :: JBang :: Plugin :: Testing (10.4s)
  • Camel :: YAML DSL :: Deserializers (7.0s)
  • Camel :: JBang :: Plugin :: Generate (6.5s)
  • Camel :: Catalog :: Camel Route Parser (6.5s)
  • Camel :: Catalog :: Camel Report Maven Plugin (6.4s)
  • Camel :: Assembly (4.1s)
  • Camel :: All Components Sync point (3.4s)
  • Camel :: YAML DSL :: Maven Plugins (2.7s)

⚙️ View full build and test results

…ade note

jakartaServletWebApplication is a plain field on ThymeleafEndpoint, not
a URI option, so "set on the endpoint" left users looking for a URI
parameter. The note now names
ThymeleafEndpoint.setJakartaServletWebApplication and says it is not a
URI option, and the 4.24 upgrade guide shows the call.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@Dhairya-007

Copy link
Copy Markdown
Contributor Author

Both done, thanks.

  1. Added a === camel-thymeleaf section to camel-4x-upgrade-guide-4_24.adoc, with the WebApplicationTemplateResolver line that shows what the resolver is really built from, and the setJakartaServletWebApplication(JakartaServletWebApplication.buildApplication(servletContext)) call the component's own ThymeleafWebApplicationResolverTest uses.
  2. Good point — it is a plain field on ThymeleafEndpoint, with no @UriParam, so "set on the endpoint" was ambiguous. The note now reads "... built from the JakartaServletWebApplication given to ThymeleafEndpoint.setJakartaServletWebApplication, which is not a URI option", and I regenerated the two thymeleaf.json files and the header javadoc in ThymeleafEndpointBuilderFactory.

# Conflicts:
#	docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_24.adoc

@davsclaus davsclaus left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @Dhairya-007, the note now names ThymeleafEndpoint.setJakartaServletWebApplication and says it is not a URI option. Both thymeleaf.json files and ThymeleafEndpointBuilderFactory are regenerated to match, and the upgrade guide has an entry. One fix to the example in that entry:

  1. camel-4x-upgrade-guide-4_24.adoc:8912: thymeleaf:greeting.html uses the default resolver, CLASS_LOADER (ThymeleafEndpoint.java:73). The JakartaServletWebApplication is only used with resolver=WEB_APP (ThymeleafEndpoint.java:298-299), so as written the example sets an object that is never read. Something like:
ThymeleafEndpoint endpoint = context.getEndpoint("thymeleaf:greeting.html?resolver=WEB_APP", ThymeleafEndpoint.class);
endpoint.setJakartaServletWebApplication(
        JakartaServletWebApplication.buildApplication(servletContext));

The route must use the same URI (to("thymeleaf:greeting.html?resolver=WEB_APP")) to get this endpoint, and the setter must be called before the first message, because the template engine is built on first use.
2. [Suggestion, optional] Same section, :8901-8907: users do not need the internal new WebApplicationTemplateResolver(...) line, and "gets no error and no resolver" is unclear. For example: "The header is never read: with resolver=WEB_APP the templates are resolved from the JakartaServletWebApplication set on the endpoint, and a route that sets the header gets no error and no effect."

Claude Code on behalf of davsclaus. This review was generated by an AI agent and may contain inaccuracies; please verify all suggestions before applying.

…te-servlet-context-header

# Conflicts:
#	docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_24.adoc

@gnodet-bot gnodet-bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Following up on my earlier review — the upgrade guide entry has been added and the setter is now named. One issue in the entry's code example remains open.

Upgrade guide example uses wrong URI (thymeleaf:greeting.html instead of thymeleaf:greeting.html?resolver=WEB_APP)

ThymeleafEndpoint.java:73 sets the default resolver to CLASS_LOADER. The WEB_APP resolver (and therefore JakartaServletWebApplication) is only activated when resolver=WEB_APP is passed (ThymeleafEndpoint.java:298-299). As written, the example calls setJakartaServletWebApplication(...) on a CLASS_LOADER endpoint — the object is set but never read by the component, defeating the purpose of the example. davsclaus already flagged this in the previous round; it has not been fixed in the new commits.

This review was generated by an AI agent, Hermès on behalf of @gnodet.

…4.adoc

Co-authored-by: Guillaume Nodet - AI Bot <gnodet+bot@gmail.com>

@gnodet-bot gnodet-bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The last blocker is fixed: the upgrade guide example now uses thymeleaf:greeting.html?resolver=WEB_APP, which correctly activates the WEB_APP resolver and therefore makes the setJakartaServletWebApplication(...) call meaningful.

Summary of what was done in this PR:

  • ✅ THYMELEAF_SERVLET_CONTEXT constant annotated @Deprecated with a deprecationNote
  • ✅ Both catalog thymeleaf.json files regenerated with deprecated: true and deprecationNote
  • ✅ ThymeleafEndpointBuilderFactory.thymeleafServletContext() regenerated with @Deprecated and updated javadoc
  • ✅ Upgrade guide entry added explaining why the header is deprecated and how to migrate

Good catch and clean fix.

This review was generated by an AI agent, Hermès on behalf of @gnodet.

@davsclaus davsclaus left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @Dhairya-007. The upgrade-guide example now uses thymeleaf:greeting.html?resolver=WEB_APP, so setJakartaServletWebApplication(...) sets the object the WEB_APP resolver reads. That was the last open point; the generated files and the deprecation note were already in order. I approved the CI runs on this head.

Claude Code on behalf of davsclaus. This review was generated by an AI agent and may contain inaccuracies; please verify all suggestions before applying.

@davsclaus davsclaus added this to the 4.24.0 milestone Nov 15, 2026
@davsclaus
davsclaus merged commit 6671787 into apache:main Nov 15, 2026
7 checks passed
@Dhairya-007
Dhairya-007 deleted the fix/thymeleaf-deprecate-servlet-context-header branch November 15, 2026 17:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants