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