Upgrading - Contents¶

Upgrading from earlier versions¶

Release with the same major number (1.x, 2.x) are intended to be drop-in replacements. However, in most cases the versions of dependency jars must be adjusted because newer versions of Velocity might require updates.

Upgrading from Velocity 1.x to the latest 2.x version for busy people¶

To maximize backward compatibility of the last Velocity 2.x with Velocity 1.x, be sure to include the following lines in your Velocity configuration:

# No automatic conversion of methods arguments
introspector.conversion_handler.class = none

# Use backward compatible space gobbling
parser.space_gobbling = bc

# Have #if($foo) only returns false if $foo is false or null
directive.if.empty_check = false

# Allow '-' in identifiers (since 2.1)
parser.allow_hyphen_in_identifiers = true

# Enable backward compatibility mode for Velocimacros
velocimacro.enable_bc_mode = true

# When using an invalid reference handler, also include quiet references (since 2.2)
event_handler.invalid_references.quiet = true

# When using an invalid reference handler, also include null references (since 2.2)
event_handler.invalid_references.null = true

# When using an invalid reference handler, also include tested references (since 2.2)
event_handler.invalid_references.tested = true

# Let the range operator expressions '[ x..y ]' return mutable lists (since 2.4)
runtime.immutable_ranges = false

Also, please note that since version 2.1, Velocity requires Java JDK 1.8+ for building and Java JRE 1.8+ at runtime.

Upgrading from Velocity 2.4.1 to Velocity 2.5¶

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).
• 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.

VTL Changes¶

Syntax 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:

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 counts as output text.

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:

runtime.deprecation.warn = true

The next minor release will turn it on by default.

Upgrading from Velocity 2.3 to Velocity 2.4.1¶

Behavior / API Changes¶

• New 1.7.x backward compatibility configuration flag runtime.immutable_ranges

VTL Changes¶

• The comparison '1' == '1.0' was returning true since Velocity 2.0 because of an overzealous String to Number conversion, which also had a performance impact. If a template relies on such a behaviour, it will need to be fixed.
• With the runtime.immutable_ranges=false configuration, the VTL range operator [x..y] returns a mutable list.

Upgrading from Velocity 2.2 to Velocity 2.3¶

No specific change needed.

Upgrading from Velocity 2.1 to Velocity 2.2¶

Behavior / API Changes¶

• The references with alternate values like ${foo|'foo'} won't trigger any invalid reference event if their alternate value is valid.
• New runtime.log.track_location debugging configuration flag (defaults to false). When true, logs VTL stacktrace on errors and populate slf4j template location MDC tags.
• New 1.7.x backward compatibility configuration flags for event handlers, see above section.
• When active, the conversion handler will automatcally convert BigInteger and BigDecimal values towards/from expected method arguments types, see method arguments conversion.

VTL Changes¶

• The new velocity-custom-parser-example maven module demonstrates how to buid a custom VTL parser which uses alternatives to the following four VTL syntax characters: $, #, @ and *.

Dependency Changes¶

• commons-lang3 has been upgraded to 3.9.
• slf4j-api has been upgraded to 1.7.30.

Upgrading from Velocity 2.0 to Velocity 2.1¶

Behavior / API Changes¶

• inside a macro, since 2.0, the rendering of null arguments uses the local reference literal. To revert to the 1.7 behavior, you can set the boolean property velocimacro.preserve.arguments.literals to true. The macros will then use the provided argument literals in such cases.
• the org.apache.util.introspection.ConversionHandler interface (introduced in 2.0) has been deprecated in favor of the org.apache.util.introspection.TypeConversionHandler interface. The new interface let one specify converters towards a java.lang.reflect.Type rather than a java.lang.class.
• most names of Velocity configuration properties have changed ; old names are still functional but will emit a deprecation warning in the log. See the Configuration Changes in Velocity 2.1 page.

VTL Changes¶

• since 2.0 the hypen ( - ) cannot be used in variable names anymore, but in 2.1, this behavior can be restored for backward compatibility with 1.7 by setting the new parser.allow_hyphen_in_identifiers boolean property to true
• it's now possible to provide default values for references, using the syntax ${name|'John Doe'}. The right part can be any valid VTL expression.
• the #foreach() directive accepts an #else block which is evaluated when the loop is empty: #foreach(...) ... #else ... #end.

Dependency Changes¶

• Velocity 2.1 now requires JDK 1.8+ for building and JRE 1.8+ at runtime.
• commons-lang3 has been upgraded to 3.8.1.
• slf4j-api has been upgraded to 1.7.26.

Upgrading from Velocity 1.7 to Velocity 2.0¶

Behavior / API Changes¶

• velocity is now using the SLF4J logging facade. Hence, all methods accepting or returning a logger now use the org.slf4j.Logger object. Velocity uses a logger name of org.apache.velocity (configurable with the runtime.log.name configuration entry), and several other childen loggers.
• the internal Context API now enforces String keys everywhere, this may break custom Context implementations at compile-time.
• invalid reference events are now more sparsely sent; they're not sent if any of the following conditions is met (the 1.x behavior did send invalid reference events in all those cases):
  • the reference is a quiet reference
  • the reference could be successfully evaluated but resulted in a null value
  • the reference is tested for validity inside an #if / #elseif statement
• all events do now receive the current Velocity Context as a first argument. The signatures of the MethodExceptionEventHandler, ReferenceInsertionEventHandler and IncludeEventHandler events have changed, and the ContextAware interface has been suppressed, as long as the NullSetEventHandler event which is obsolete.
• The ResourceLoader class API has replaced InputStream getters by Reader getters: InputStream ResourceLoader.getResourceStream(String name) has been replaced by a Reader ResourceLoader.getResourceReader(String name, String encoding).
• the default encoding ('ISO-8859-1' in 1.x) is now UTF-8.
• the MethodException event handler now receives an additional argument providing template name and location infos.
• Initialization methods in Velocity and VelocityEngine taking an ExtendedProperties have been removed (but setProperties(Properties) methods are still here). All occurences of the org.apache.commons.collections.ExtendedProperties class in the runtime internal initialization API have been replaced by org.apache.velocity.util.ExtProperties.
• the macros are now using a 'call by sharing' convention (which means that all arguments are evaluated once at start, and that the macro receives a copy of the reference to each argument).
• the UberspectLoggable interface has been removed.
• the directive.if.tostring.nullcheck configuration property has been superseded by the directive.if.emptycheck (warning: renamed as directive.if.empty_check in 2.1) property, which defaults to true. It means that all empty objects (strings and collections) as long as zero numbers, do evaluate to false (see the complete boolean context evaluation rules.). You may want to set directive.if.emptycheck to false to maximize backward compatibility with 1.x.
• inside a macro, the rendering of null arguments uses the local reference literal (see 2.1 for an 1.7 compatibility flag).

VTL Changes¶

• the hypen ( - ) cannot be used in variable names anymore (see 2.1 for an 1.7 compatibility flag).
• method arguments can be arithmetic expressions
• method arguments are now converted as needed between all main basic Java standard types (booleans, numbers and strings). If you want to revert to the 1.x behavior, set the property runtime.conversion.handler.class = none.
• space gobbling (to control the indentation of generated code) is now configurable via the space.gobbling configuration key, which can take the following values: none, bc (aka. backward compatible), lines and structured. See the related documentation section for details. To maximize backward compatibility with 1.x, set it to bc.
• the #foreach predefined references $velocityCount and $velocityHasNext have been removed. Use $foreach.count (1-based), $foreach.index (0-based) and foreach.hasNext().
• Velocimacro arguments are now evaluated only once (instead of each time they were referenced inside the macro body as was the case for v1.7) and passed by value (or more precisely as reference after evaluation).
• Velocimacros do not anymore have a proxy context of their own - if they do insert new values in the context, and then call an external code changing those values, they will now see the new values (see 2.2 for the velocimacro.enable_bc_mode backward compatibility flag).
• 2.x follows a standard operators precedence rule, whereas with 1.7 the expression ! "$foo" == 'bar' will, wrongly, evaluate the equality before the unary negation.

Dependency Changes¶

• Velocity now requires a JDK version of 1.7 or higher.
• commons-collections and commons-logging aren't needed any more at runtime.
• there's a new runtime dependency, slf4j-api 1.7.25.
• you'll need an SLF4J binding.
• commons-lang has to be upgraded to 3.5.

Upgrading from Velocity 1.6.x to Velocity 1.7.x¶

There are no changes in the dependencies since Velocity 1.6

• Deprecated $velocityCount; please use $foreach.count or $foreach.index
• Deprecated $velocityHasNext; please use $foreach.hasNext, $foreach.first or $foreach.last
• Deprecated velocimacro.context.localscope setting; please get/set local #macro references as members of the provided $macro scope control instead. (e.g. #set( $macro.foo = 'bar' ) and $macro.foo )
• Deprecated directive.evaluate.context.class setting; please get/set local #evaluate references as members of the provided $evaluate scope control instead. (e.g. #set( $evaluate.foo = 'bar' ) and $evaluate.foo )
• Deprecated #literal directive; please use #[[this syntax]]# instead.
• Changed #stop to end template rendering rather than template parsing.
• Removed obsolete Veltag (use VelocityViewTag in VelocityTools project)
• Removed obsolete WebMacro conversion code.

Upgrading from Velocity 1.5.x to Velocity 1.6.x¶

• Commons Collections has been upgraded to version 3.2.1.
• Commons Lang has been upgraded to version 2.4.
• Commons Logging is required for compiling and using CommonsLogLogChute.

Upgrading from Velocity 1.4 or earlier¶

• JDOM has been upgraded to version 1.0.
• Commons Collections has been upgraded to version 3.1.
• Commons Lang 2.1 has been added.

Optional: + Apache Ant 1.6 or better is required for rebuilding. + JavaCC 3.2 is recommended to compile the parser files. + HSQLDB 1.7.1 is required for running unit tests.