Upgrading from earlier versions¶

Release with the same major number (1.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¶

Behavior / API changes:

• 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 output.encoding configuration property has been removed.
• the MethodException event handler now receives an additional argument providing template name and location infos.

VTL Syntax changes:

• the hypen ( - ) cannot be used in variable names anymore
• method arguments can be arithmetic expressions

Dependencies changes:

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

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¶

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