Title: Apache Velocity Engine - Upgrading
## Upgrading - Contents
[TOC]
## 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 2.0 to Velocity 2.1
For busy people: To maximize backward compatibility of Velocity 2.1 with Velocity 1.x, be sure to include the following lines in your Velocity configuration:
:::properties
# 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
# When displaying null arguments literals, use provided arguments literals (since 2.1)
velocimacro.arguments.preserve_literals = true
Also, please note that Velocity 2.1 now requires Java JDK 1.8 for bulding and Java JRE 1.8 at runtime.
### 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`](apidocs/org/apache/velocity/util/introspection/ConversionHandler.html) interface (introduced in 2.0) has been deprecated in favor of the [`org.apache.util.introspection.TypeConversionHandler`](apidocs/org/apache/velocity/util/introspection/TypeConversionHandler.html) 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](configuration-property-changes-in-2.1.html) 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
Please note that the maven repository path has changed:
- former path:
org/apache/velocity/velocity/1.7.x
- new path:
org/apache/velocity/velocity-engine-core/2.x
For busy people: To maximize backward compatibility of Velocity 2.0 with Velocity 1.x, be sure to include the following lines in your Velocity configuration:
:::properties
# No automatic conversion of methods arguments
runtime.conversion.handler.class = none
# Use backward compatible space gobbling
space.gobbling = bc
# Have #if($foo) only returns false if $foo is false or null
directive.if.emptycheck = false
and check the [Dependency changes](#dependencies-changes) 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. Velocity uses a logger name of `org.apache.velocity` (configurable with the `runtime.log.name` configuration entry), and [several other childen loggers](developer-guide.html#logging).
+ 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](configuration.html#if-directive) 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.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`.
+ the #foreach predefined references `$velocityCount` and `$velocityHasNext` have been removed. Use `$foreach.count` (1-based), `$foreach.index` (0-based) and `foreach.hasNext()`.
### 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](dependencies.html).
+ 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](http://commons.apache.org/collections/) has been upgraded to version 3.2.1.
+ [Commons Lang](http://commons.apache.org/lang/) has been upgraded to version 2.4.
+ [Commons Logging](http://commons.apache.org/logging/) is required for compiling and using CommonsLogLogChute.
## Upgrading from Velocity 1.4 or earlier
+ [JDOM](http://www.jdom.org) has been upgraded to version 1.0.
+ [Commons Collections](http://jakarta.apache.org/commons/collections/) has been upgraded to version 3.1.
+ [Commons Lang](http://jakarta.apache.org/commons/lang/) 2.1 has been added.
Optional:
+ [Apache Ant](http://ant.apache.org) 1.6 or better is required for rebuilding.
+ [JavaCC](http://javacc.dev.java.net) 3.2 is recommended to compile the parser files.
+ [HSQLDB](http://www.hsqldb.org) 1.7.1 is required for running unit tests.