This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new b2190cda403a camel-velocity - Document how to use Velocity Tools such
as EscapeTool in templates
b2190cda403a is described below
commit b2190cda403aadd6afb47ed556546fce3c44c725
Author: Claus Ibsen <[email protected]>
AuthorDate: Thu Sep 17 21:06:05 2026 +0200
camel-velocity - Document how to use Velocity Tools such as EscapeTool in
templates
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Signed-off-by: Claus Ibsen <[email protected]>
---
.../camel/catalog/docs/velocity-component.adoc | 80 ++++++++++++++++++++++
.../src/main/docs/velocity-component.adoc | 80 ++++++++++++++++++++++
2 files changed, 160 insertions(+)
diff --git
a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/velocity-component.adoc
b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/velocity-component.adoc
index 4238acd8c6c4..cb102bb2f991 100644
---
a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/velocity-component.adoc
+++
b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/velocity-component.adoc
@@ -103,6 +103,86 @@ VelocityContext velocityContext = new
VelocityContext(variableMap);
exchange.getIn().setHeader("CamelVelocityContext", velocityContext);
----
+=== Using Velocity Tools such as EscapeTool
+
+Anything you store in an exchange variable is available to the template via
`$variables`.
+This makes it easy to hand
+https://velocity.apache.org/tools/devel/apidocs/org/apache/velocity/tools/generic/EscapeTool.html[Velocity
Tools]
+such as `EscapeTool` to the template, so special characters can be escaped for
HTML, XML, JSON, SQL, or URLs
+directly in the template, instead of pre-processing the message before calling
the template.
+
+First, add the Velocity Tools dependency to your project (Camel does not ship
it):
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.velocity.tools</groupId>
+ <artifactId>velocity-tools-generic</artifactId>
+ <version>x.x.x</version>
+</dependency>
+----
+
+Then register an `EscapeTool` as a bean, pass it to the template in an
exchange variable, and call it from the template:
+
+[tabs]
+====
+Java::
++
+[source,java]
+----
+from("direct:order")
+ .setVariable("esc", constant(new EscapeTool()))
+ .to("velocity:com/acme/order.vm");
+----
+
+XML::
++
+[source,xml]
+----
+<bean id="esc" class="org.apache.velocity.tools.generic.EscapeTool"/>
+
+<route>
+ <from uri="direct:order"/>
+ <setVariable name="esc">
+ <simple>${ref:esc}</simple>
+ </setVariable>
+ <to uri="velocity:com/acme/order.vm"/>
+</route>
+----
+
+YAML::
++
+[source,yaml]
+----
+- beans:
+ - name: esc
+ type: org.apache.velocity.tools.generic.EscapeTool
+- route:
+ from:
+ uri: direct:order
+ steps:
+ - setVariable:
+ name: esc
+ expression:
+ simple:
+ expression: ${ref:esc}
+ - to:
+ uri: velocity:com/acme/order.vm
+----
+====
+
+.order.vm
+[source,text]
+----
+Dear ${headers.name}. You ordered item $variables.esc.xml(${headers.item}) on
$variables.esc.xml(${body}).
+----
+
+With a body of `Monday & Tuesday` the template renders `Monday & Tuesday`.
+The same works with `$variables.esc.html(...)`, `$variables.esc.json(...)`,
`$variables.esc.sql(...)`, and `$variables.esc.url(...)`.
+
+TIP: A message header works the same way (`setHeader("esc", constant(new
EscapeTool()))` and `$headers.esc` in the template),
+but a variable keeps the tool out of the message, so it is not sent along to
the next endpoint.
+
=== Hot reloading
The Velocity template resource is, by default, hot reloadable for both
diff --git a/components/camel-velocity/src/main/docs/velocity-component.adoc
b/components/camel-velocity/src/main/docs/velocity-component.adoc
index 4238acd8c6c4..cb102bb2f991 100644
--- a/components/camel-velocity/src/main/docs/velocity-component.adoc
+++ b/components/camel-velocity/src/main/docs/velocity-component.adoc
@@ -103,6 +103,86 @@ VelocityContext velocityContext = new
VelocityContext(variableMap);
exchange.getIn().setHeader("CamelVelocityContext", velocityContext);
----
+=== Using Velocity Tools such as EscapeTool
+
+Anything you store in an exchange variable is available to the template via
`$variables`.
+This makes it easy to hand
+https://velocity.apache.org/tools/devel/apidocs/org/apache/velocity/tools/generic/EscapeTool.html[Velocity
Tools]
+such as `EscapeTool` to the template, so special characters can be escaped for
HTML, XML, JSON, SQL, or URLs
+directly in the template, instead of pre-processing the message before calling
the template.
+
+First, add the Velocity Tools dependency to your project (Camel does not ship
it):
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.velocity.tools</groupId>
+ <artifactId>velocity-tools-generic</artifactId>
+ <version>x.x.x</version>
+</dependency>
+----
+
+Then register an `EscapeTool` as a bean, pass it to the template in an
exchange variable, and call it from the template:
+
+[tabs]
+====
+Java::
++
+[source,java]
+----
+from("direct:order")
+ .setVariable("esc", constant(new EscapeTool()))
+ .to("velocity:com/acme/order.vm");
+----
+
+XML::
++
+[source,xml]
+----
+<bean id="esc" class="org.apache.velocity.tools.generic.EscapeTool"/>
+
+<route>
+ <from uri="direct:order"/>
+ <setVariable name="esc">
+ <simple>${ref:esc}</simple>
+ </setVariable>
+ <to uri="velocity:com/acme/order.vm"/>
+</route>
+----
+
+YAML::
++
+[source,yaml]
+----
+- beans:
+ - name: esc
+ type: org.apache.velocity.tools.generic.EscapeTool
+- route:
+ from:
+ uri: direct:order
+ steps:
+ - setVariable:
+ name: esc
+ expression:
+ simple:
+ expression: ${ref:esc}
+ - to:
+ uri: velocity:com/acme/order.vm
+----
+====
+
+.order.vm
+[source,text]
+----
+Dear ${headers.name}. You ordered item $variables.esc.xml(${headers.item}) on
$variables.esc.xml(${body}).
+----
+
+With a body of `Monday & Tuesday` the template renders `Monday & Tuesday`.
+The same works with `$variables.esc.html(...)`, `$variables.esc.json(...)`,
`$variables.esc.sql(...)`, and `$variables.esc.url(...)`.
+
+TIP: A message header works the same way (`setHeader("esc", constant(new
EscapeTool()))` and `$headers.esc` in the template),
+but a variable keeps the tool out of the message, so it is not sent along to
the next endpoint.
+
=== Hot reloading
The Velocity template resource is, by default, hot reloadable for both
