Title: Apache Velocity Engine - Upgrading
## 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
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.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
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` 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.
### 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`.
+ 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.