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

<div class="note">
Please note that the maven repository path has changed:
<ul>
  <li>former path: <code>org/apache/velocity/velocity/1.7.<i>x</i></code></li>
  <li>new path: <code>org/apache/velocity/velocity-engine-core/2.0[.<i>x</i>]</code></li>
</ul>
</div>

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()`.
+ 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.
+ 2.0 follows a [standard operators precedence rule](https://docs.oracle.com/javase/tutorial/java/nutsandbolts/operators.html), 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](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.</li>

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.