You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@velocity.apache.org by cb...@apache.org on 2026/09/25 15:14:02 UTC
(velocity-site) branch main updated: Update engine 2.5 docs
This is an automated email from the ASF dual-hosted git repository.
asf-gitbox-commits pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/velocity-site.git
The following commit(s) were added to refs/heads/main by this push:
new 97365b2b Update engine 2.5 docs
97365b2b is described below
commit 97365b2bbe0cabed67a628e928d1000f1b48911b
Author: Claude Brisson <cl...@renegat.net>
AuthorDate: Fri Sep 25 17:13:53 2026 +0200
Update engine 2.5 docs
---
src/content/engine/2.5/configuration.mdtext | 37 +++++++++++++++++++--------
src/content/engine/2.5/developer-guide.mdtext | 2 ++
src/content/engine/2.5/index.mdtext | 5 ++--
src/content/engine/2.5/upgrading.mdtext | 33 ++++++++++--------------
src/content/engine/2.5/user-guide.mdtext | 12 ++++++++-
src/content/engine/2.5/vtl-reference.mdtext | 11 ++++----
6 files changed, 61 insertions(+), 39 deletions(-)
diff --git a/src/content/engine/2.5/configuration.mdtext b/src/content/engine/2.5/configuration.mdtext
index 87cee6dd..a92fbb01 100644
--- a/src/content/engine/2.5/configuration.mdtext
+++ b/src/content/engine/2.5/configuration.mdtext
@@ -18,7 +18,7 @@ The properties key names have been reviewed in Engine 2.1. Old names are still f
## Configuration Summary Tree
-The following tree gathers all non deprecated configuration properties with their default values.
+The following tree gathers all configuration properties with their default values. None of these defaults is deprecated, except `runtime.strict_math = false` (see below).
:::properties
context. +-- scope_control. +-- define = false
@@ -66,7 +66,7 @@ The following tree gathers all non deprecated configuration properties with thei
+-- log_when_found = true
runtime. +-- custom_directives = *classname*, *classname* ...
- +-- deprecation.warn = false
+ +-- deprecation.warn = true
+-- immutable_ranges = true
+-- interpolate_string_literals = true
+-- log. +-- instance = *Java Object instance*
@@ -88,6 +88,21 @@ The following tree gathers all non deprecated configuration properties with thei
+-- library. +-- autoreload = false
+-- path = velocimacros.vtl
+### Deprecated Settings
+
+The following settings are deprecated since 2.5, in preparation for the next major version. Each of them logs a warning at engine initialization, unless `runtime.deprecation.warn` is set to false.
+
+ :::properties
+ parser. +-- allow_hyphen_in_identifiers = true
+ +-- class = *classname*
+
+ runtime. +-- immutable_ranges = false
+ +-- strict_math = false (the default value: set it to true)
+
+ velocimacro. +-- enable_bc_mode = true
+
+The pre-2.1 property names are deprecated as well, see the [**table of correspondance**](configuration-property-changes-in-2.1.html).
+
## Logging
**`runtime.log.instance`** = *Java Object instance*
@@ -165,7 +180,7 @@ Be aware that it can have a (probably very) small performance impact.
**`directive.parse.max_depth = 10`**
-> Defines the allowable parse depth for a template. A template may #parse() another template which itself may have a #parse() directive. This value prevents runaway #parse() recursion.
+> Defines the allowable nesting depth of `#parse()` and, since 2.5, `#evaluate()`. A template may #parse() another template which itself may have a #parse() directive, and evaluated VTL may itself contain `#evaluate()` or `#parse()`; the two directives share the same nesting stack, so a mixed chain counts together. Once the limit is reached the directive renders nothing and an error is logged instead of the recursion running until the thread's stack is exhausted. A value of 0 or less mea [...]
### custom directives
@@ -240,7 +255,7 @@ The following resource management configuration keys only apply to the default R
**`velocimacro.library.path = velocimacros.vtl `**
-> *Multi-valued key. Will accept CSV for value.* Filename(s) of Velocimacro library to be loaded when the Velocity Runtime engine starts. These Velocimacros are accessable to all templates. The file is assumed to be relative to the root of the file loader resource path. If the default (<code>velocimacro.vtl</code> since 2.1) is not found, the old default (<code>VM_global_library.vm</code>) is also searched for.
+> *Multi-valued key. Will accept CSV for value.* Filename(s) of Velocimacro library to be loaded when the Velocity Runtime engine starts. These Velocimacros are accessable to all templates. The file is assumed to be relative to the root of the file loader resource path. If the default (<code>velocimacros.vtl</code> since 2.1) is not found, the old default (<code>VM_global_library.vm</code>) is also searched for. *Deprecated since 2.5*: the old default name `VM_global_library.vm` is no [...]
**`velocimacro.inline.allow = true`**
@@ -262,7 +277,7 @@ The following resource management configuration keys only apply to the default R
> When set to true, will throw a `ParseErrorException` when parsing a template containing a macro with an invalid number of arguments. Is set to false by default to maintain backwards compatibility with templates written before this feature became available.
-**`velocimacro.enable_bc_mode = false`**
+**`velocimacro.enable_bc_mode = false`** *(deprecated since 2.5)*
> This flag enables Velocimacro backward compatible mode. It has two effects:
>
@@ -279,7 +294,7 @@ The following resource management configuration keys only apply to the default R
> #macro( display $foo ) $foo #end
> #set( $foo = 'hello' )
> #display()
-> will display `$foo`. When B.C. mode is enabled, Velocity will mimic the 1.x behavior which is to use the global context value, that is render `hello`.
+> will display `$foo`. When B.C. mode is enabled, Velocity will mimic the 1.x behavior which is to use the global context value, that is render `hello`. *Deprecated since 2.5*, without replacement: the next major version does not provide this compatibility mode (the 2.0 behaviours above are the only ones); enabling it emits a startup warning.
**`velocimacro.body_reference = false`**
@@ -303,21 +318,21 @@ The following resource management configuration keys only apply to the default R
## Ranges
-**`runtime.immutable_ranges = true`**
+**`runtime.immutable_ranges = true`** *(deprecated since 2.5)*
-> Controls whether the `java.util.List` object return by the VTL range operator [ *a* .. *b* ] is an immutable list (the default since Velocity 2.1) or a mutable list backed by a `java.util.ArrayList` object.
+> Controls whether the `java.util.List` object return by the VTL range operator [ *a* .. *b* ] is an immutable list (the default since Velocity 2.1) or a mutable list backed by a `java.util.ArrayList` object. *Deprecated since 2.5*: ranges are always immutable in the next major version; setting this key to `false` emits a startup warning.
## Math
**`runtime.strict_math = false`**
-> Affects all math operations in VTL. If changed to true, this will cause Velocity to throw a MathException whenever one side of a math operation has a null value (e.g. `#set( $foo = $null * 5 )`) or when trying to divide by zero. If this value is left `false`, then rendering will continue and that math operation will be ignored.
+> Affects all math operations in VTL. If changed to true, this will cause Velocity to throw a MathException whenever one side of a math operation has a null value (e.g. `#set( $foo = $null * 5 )`) or when trying to divide by zero. If this value is left `false`, then rendering will continue and that math operation will be ignored. *Deprecated since 2.5*: the lenient behaviour is going away — the next major version always enforces strict math — so leaving this value `false` emits a startu [...]
## Deprecation Warnings
-**`runtime.deprecation.warn = false`**
+**`runtime.deprecation.warn = true`**
-> When set to true, logs a warning for VTL syntax constructs and configuration options that are deprecated in preparation for the next major version (the informal `$foo.bar` notation in output, the `${foo|default}` operator, the extra `$` in `${$foo}`, and the `parser.allow_hyphen_in_identifiers` option). Off by default, since this is a drop-in minor release and the informal notation is pervasive; enable it to audit a template base ahead of the next major. See the [upgrading guide](upgra [...]
+> When true, logs a warning for the VTL syntax constructs and configuration options that are deprecated in preparation for the next major version: a backslash right before the closing quote of a double-quoted string (use a single-quoted string), the `parser.allow_hyphen_in_identifiers` option, and lenient math (`runtime.strict_math = false`, warned once at initialization). On by default; set it to false to silence them while a template base is being migrated. See the [upgrading guide](up [...]
## Parser Configuration
diff --git a/src/content/engine/2.5/developer-guide.mdtext b/src/content/engine/2.5/developer-guide.mdtext
index b374fbf4..1f894d98 100644
--- a/src/content/engine/2.5/developer-guide.mdtext
+++ b/src/content/engine/2.5/developer-guide.mdtext
@@ -1638,6 +1638,8 @@ Then, in the target project, you have to specify which parser to use from within
For instance, you may want to replace `#` with `%` because the target language (markdown for instance) already makes use of the `#` symbol.
+*Deprecated since 2.5*: the `parser.class` property is deprecated. The next major version keeps the capability by letting an application plug in a lexer, and this property has no effect there; the `$` character will not be configurable at all any more (`#`, `@` and `*` will), so a custom parser relying on `parser.char.dollar` has no future equivalent. The 2.x mechanism above keeps working in 2.x, and a 2.x custom parser class is not reusable there.
+
## Summary
We hope this brief guide was a helpful introduction to using Velocity in your Java projects, and thank you for you interest in Velocity. We welcome any and all comments you may have about this documentation and the Velocity template engine itself.
diff --git a/src/content/engine/2.5/index.mdtext b/src/content/engine/2.5/index.mdtext
index 68472ebe..13f7e0af 100644
--- a/src/content/engine/2.5/index.mdtext
+++ b/src/content/engine/2.5/index.mdtext
@@ -8,11 +8,12 @@ You can check the [Velocity Template Language (VTL) reference](vtl-reference.htm
## Where do I get releases?
-The current stable release version is version 2.4.1.
+The current stable release version is version 2.5.
The release distribution is available as a combined source/binary distribution in `tar.gz` and `zip` formats, and can be downloaded through the [Apache Mirror system](/download.cgi).
-The Velocity jars are also available through the [central Maven repository](https://search.maven.org/artifact/org.apache.velocity/velocity-engine-core/2.4.1/jar).
+The Velocity Engine jars are also available through the [Central Maven repository](
+https://central.sonatype.com/search?q=velocity-engine).
Older releases are archived at the [Apache Velocity archives](http://archive.apache.org/dist/velocity/engine/).
diff --git a/src/content/engine/2.5/upgrading.mdtext b/src/content/engine/2.5/upgrading.mdtext
index 6e4a2ca5..0e6d03ff 100644
--- a/src/content/engine/2.5/upgrading.mdtext
+++ b/src/content/engine/2.5/upgrading.mdtext
@@ -46,33 +46,28 @@ Also, please note that since version 2.1, Velocity requires Java JDK 1.8+ for bu
### Behavior / API Changes
-+ **Spring support modules reorganized.** The `spring-velocity-support` artifact now targets the current, Jakarta-based Spring framework (Spring 6.x and 7.x) on Java 17. Although this is a minor Velocity release, it is a *major* upgrade for that module, which jumps from Spring 5 to Spring 6/7. Applications still on **Spring 5.x / Java 8** must switch their dependency to the new `spring5-velocity-support` artifact (same packages and classes, no code change).
++ **Spring support modules reorganized.** The `spring-velocity-support` artifact now targets the current, Jakarta-based Spring framework (Spring 6.x and 7.x) on Java 17. Although this is a minor Velocity release, it is a *major* upgrade for that module, which jumps from Spring 5 to Spring 6/7. Applications still on **Spring 5.x / Java 8** must switch their dependency to the new `spring5-velocity-support` artifact.
+ New `introspector.restrict.methods` property to restrict only specific method calls in the secure introspector. By default it now blocks `VelocityEngine.init()` and `VelocityEngine.reset()`.
+ `Map.size()` is now invoked instead of any provided `size` property. Templates that defined a `size` property on a map-like object and expected it to shadow the method will see a behavior change.
+ `DatabaseObjectsFactory` is deprecated in favor of `PreparedStatementsFactory`, alongside a connection-leak fix in `DataSourceResourceLoader`.
++ `#evaluate()` now honours the nesting depth limit of `directive.parse.max_depth` (default 10). Both `#parse` and ` #evaluate` push on the same template name stack, so a chain mixing them counts as a whole.
++ Resource names are normalized before a loader sees them: `.` and `..` segments are resolved, and a name that would climb above a configured resource root (`../secret.txt`) is refused as not found.
++ `SecureUberspector` forbids a template to reach a class's static methods through `$value.getClass()` or `$value.class`.
++ Custom parser: the `parser.class` property is deprecated: the next major version will use a pluggable lexer instead, so the [custom parser building process](developer-guide.html#customizing-the-vtl-parser) will provide an equivalent way of customizing the parsing, with one caveat, though: the `$` character will no longer be configurable at all in the next major version, only `#`, `@` and `*` will, so a parser built with `parser.char.dollar` has no future equivalent.
++ SecureUberspector now honours the configured type conversion handler.
### VTL Changes
-#### Syntax deprecations (preparing for the next major version)
+#### Syntax and configuration deprecations (preparing for the next major version)
-The next major version will move to a `${ expression }` model, so VTL constructs that cannot map onto it are deprecated starting with 2.5. Nothing is removed in 2.x — these still work, but they will be dropped in the next major version. Affected forms and their replacements:
+- corner case: support for an interpolated double-quoted string ending with `\` is deprecated.
+- the `velocimacro.enable_bc_mode = true` configuration is deprecated (it allowed null or missing macro arguments to render caller's bare references instead of the macro definition ones, after trying to resolve missing arguments from the caller context).
+- the implicit loading of the 1.x macro libraries file `VM_global_library.vm` is deprecated. Use `velocimacros.vtl` or make its path explicit in the configuration.
+- the `runtime.immutable_ranges = false` configuration is deprecated.
+- the `runtime.strict_math = false` configuration is deprecated. Note that `false` is still the default value for 2.5, so relying on the default value *will* produce a deprecation warning.
+- the `parser.allow_hyphen_in_identifiers` configuration is deprecated.
-| Deprecated | Replacement |
-|---|---|
-| `${foo|'bar'}` (`|` default value) | `#if($foo)$foo#{else}bar#end` |
-| `$foo.bar`, `$foo.m()`, `$foo[i]` **rendered to output** | formal `${foo.bar}` etc. |
-| `${$foo}`, `$!{$foo}` (extra `$` after `{`, re-added in 2.5 for 1.7 BC) | `${foo}` |
-
-Only references **rendered to the output** are affected by the formal-notation deprecation: that is where `$foo.bar` is ambiguous (is `.bar` a property access or literal text?). In any position where the surrounding syntax already delimits the reference — `#set` left- and right-hand sides, directive and macro arguments, indexes, sub-expressions, inside `${ }` — informal notation stays perfectly valid and raises no warning. Note that the content of interpolated double-quoted strings count [...]
-
-One configuration option `parser.allow_hyphen_in_identifiers` is also deprecated for the same reason: `$foo-bar` will become an invalid syntax in the next major release.
-
-These deprecations are **silent by default**. To surface them, set:
-
- :::properties
- runtime.deprecation.warn = true
-
-The **next** minor release will turn it on by default.
+All the corresponding deprecation warning messages can be turned off with `runtime.deprecation.warn = false`.
## Upgrading from Velocity 2.3 to Velocity 2.4.1
diff --git a/src/content/engine/2.5/user-guide.mdtext b/src/content/engine/2.5/user-guide.mdtext
index 7efea73a..07a8374d 100644
--- a/src/content/engine/2.5/user-guide.mdtext
+++ b/src/content/engine/2.5/user-guide.mdtext
@@ -168,7 +168,7 @@ The second flavor of VTL references are properties, and properties have a distin
${customer.Address}
${purchase.Total}
-Note that Velocity does support *informal* expressions like *$customer.Address*, as long as there is no ambiguity with the surrounding context. But this syntax is **deprecated** since Velocity 2.5 (outside of places where there is no ambiguity, like inside a *#set* directive) and will be dropped in the next major version.
+Note that Velocity also supports the *informal* notation *$customer.Address*, as long as there is no ambiguity with the surrounding context.
Take the first example, *${customer.Address}*. It can have two meanings. It can mean, Look in the hashtable identified as *customer* and return the value associated with the key *Address*. But it can also be referring to a method (references that refer to methods will be discussed in the next section); *${customer.Address}* could be an abbreviated way of writing *${customer.getAddress()}*. When your page is requested, Velocity will determine which of these two possibilities makes sense, [...]
@@ -312,6 +312,16 @@ Formal and quiet reference notation can be used together, as demonstrated below.
:::html+velocity
<input type="text" name="email" value="$!{email}"/>
+## Alternate Values
+
+A reference can name an alternate value, rendered in its place when the reference is null, false, zero or empty:
+
+ :::html+velocity
+ <input type="text" name="email" value="${email|'nobody@example.com'}"/>
+ Hello ${customer.name|$anonymous}!
+
+The alternate value is any valid VTL expression, evaluated only when needed. It can only be written in the formal notation, `${ ... }`, and combines with the quiet notation: `$!{email|$fallback}` renders nothing when both are unset.
+
## Strict Rendering Mode
The strict rendering mode is activated by setting the velocity configuration property 'runtime.strict_mode.enable' to true. The general intent of this setting is to make Velocity behave more strictly in cases that are undefined or ambiguous, similar to a programming language, which may be more appropriate for some uses of Velocity. In such undefined or ambiguous cases Velocity will throw an exception. The following discussion outlines the cases in which strict behavior is different fro [...]
diff --git a/src/content/engine/2.5/vtl-reference.mdtext b/src/content/engine/2.5/vtl-reference.mdtext
index cce372ae..1f473daf 100644
--- a/src/content/engine/2.5/vtl-reference.mdtext
+++ b/src/content/engine/2.5/vtl-reference.mdtext
@@ -32,8 +32,7 @@ Examples:
+ Silent shorthand notation: `$!mudSlinger_9`
+ Formal notation: `${mudSlinger_9}`
+ Silent formal notation: `$!{mudSlinger_9}`
-
-*Deprecated since 2.5: the default-value syntax `${mudSlinger_9|$otherWheels}` (use an `#if` block instead) and the extra `$` form `${$mudSlinger_9}`. See the [upgrading guide](upgrading.html).*
++ Formal notation with an alternate value: `${mudSlinger_9|$otherWheels}` — rendered when the reference is null, false, zero or empty; the right-hand side is any valid VTL expression
### Properties
@@ -45,8 +44,8 @@ Examples:
+ Formal notation: `${customer.Address}`
+ Formal notation: `${purchase.Total}`
-
-*Deprecated since 2.5: the informal notation `$customer.Address` (without braces) when rendered to the output, and the default value `${person.name|'John Doe'}`. See the [upgrading guide](upgrading.html).*
++ Informal notation: `$customer.Address`
++ With an alternate value: `${person.name|'John Doe'}`
### Methods
@@ -62,8 +61,8 @@ Examples:
+ Formal notation: `${customer.getAddress()}`
+ Formal notation with parameter list: `${page.setTitle( "My Home Page" )}`
-
-*Deprecated since 2.5: the informal notation `$customer.getAddress()` (without braces) when rendered to the output, and the default value `${page.getTitle()|'Blank Page'}`. See the [upgrading guide](upgrading.html).*
++ Informal notation: `$customer.getAddress()` (formal notation is preferred)
++ With an alternate value: `${page.getTitle()|'Blank Page'}`
VTL Properties can be used as a shorthand notation for VTL Methods that take *get* and *set*. Either *${object.getMethod()}* or *${object.setMethod()}* can be abbreviated as *${object.Method}*. It is generally preferable to use a Property when available. The main difference between Properties and Methods is that you can specify a parameter list to a Method.