Velocity Engine

Docs

Developers

Community

Translations (outdated)

Velocity News Feed

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.7.x to Velocity 2.0.x

For busy people: To maximize backward compatibility with Velocity 1.x, be sure to include the following lines in your Velocity configuration:

runtime.conversion.handler = none
space.gobbling = bc

and check the Dependencies change below.

Read below for futher details.

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

    The 1.x behavior did send invalid reference events in all those cases.

  • The ResourceLoader class has been deprecated in favor of a ResourceLoader2 class, in which the InputStream ResourceLoader.getResourceStream(String name) has been replaced by a Reader ResourceLoader.getResourceReader(String name, String encoding). Since ResourceLoader inherits from ResourceLoader2, the change remains backward compatible, but custom resource loaders should be upgraded to avoid deprecattion warnings.

  • the default encoding ('ISO-8859-1' in 1.x) is now read from the standard file.encoding Java system property.
  • the MethodException event handler now receives an additional argument providing template name and location infos.
  • all occurences of the class org.apache.commons.collections.ExtendedProperties in the initialization API have been replaced by org.apache.velocity.util.ExtProperties.

VTL Changes:

  • the hypen ( - ) cannot be used in variable names anymore
  • 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 = none.
  • space gobbling (to control the indentation of generated code) is now configurable via the space.gobbing 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.

Dependencies changes:

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

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

Upgrading from Velocity 1.4 or earlier

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.