| ## Configuration Properties Changes between Engine 2.0 and Engine 2.1+ |
| |
| Velocity Engine configuration property names have been reviewed in Engine 2.1 for clarity and consistency. |
| |
| **Old property names are still functional but have been deprecated** and will be removed in Engine 3.0. Velocity will emit warnings in the logs when old property names are used. |
| |
| ### Changes Summary |
| |
| 2.0 property name | 2.1+ property name | Property purpose |
| ------------------|------------------ |----------------- |
| runtime.log.instance | *unchanged* | org.slf4j.Logger instance |
| runtime.log.name | *unchanged* | org.slf4j.Logger name |
| runtime.log.invalid.references | runtime.log.log_invalid_references | whether to log invalid references |
| *n/a* | runtime.log.log_invalid_method_calls (since 2.1) | whether to log invalid method calls |
| resource.loader | resource.loaders | list of resource loader names |
| <name>.resource.loader.<prop> | resource.loader.<name>.<prop> | property of a named resource loader |
| <name>.resource.loader.modificationCheckInterval | resource.loader.<name>.modification_check_interval | modification check interval of a named resource loader |
| resource.manager.instance | *unchanged* | resource manager live instance |
| resource.manager.class | *unchanged* | resource manager class |
| resource.manager.cache.class | *unchanged* | resource manager cache class |
| resource.manager.defaultcache.size | resource.manager.cache.default_size | resource manager default cache size |
| resource.manager.logwhenfound | resource.manager.log_when_found | whether to log when a resource is found |
| <scope>.provide.scope.control | context.scope_control.<scope> | enabling scope control object in the context for a specific scope |
| runtime.string.interning | runtime.string_interning | whether to use string interning |
| directive.define.max.depth | directive.define.max_depth | max depth for the `#define` directive |
| directive.foreach.maxloops | directive.foreach.max_loops | maximum number of loops of a `#foreach` directive |
| directive.foreach.skip.invalid | directive.foreach.skip_invalid | whether to skip bad iterables |
| directive.if.emptycheck | directive.if.empty_check | whether the `#if` directive checks objects for emptiness |
| directive.include.output.errormsg.start | directive.include.output_error_start (deprecated) | error message prefix for `#include` and `#parse` |
| directive.include.output.errormsg.end | directive.include.output_error_end (deprecated) | error message suffix for `#include` and `#parse` |
| directive.parse.max.depth | directive.parse.max_depth | max depth for the `#parse` directive |
| userdirective (undocumented) | runtime.custom_directives | list of custom directives |
| eventhandler.referenceinsertion.class | event_handler.reference_insertion.class | list of reference insertion event handler classes |
| eventhandler.methodexception.class | event_handler.method_exception.class | list of method exception event handler classes |
| eventhandler.include.class | event_handler.include.class | list of file inclusion event handler classes |
| eventhandler.invalidreferences.class | event_handler.invalid_references.class | list of invalid reference event handler classes |
| velocimacro.library | velocimacro.library.path | path to the velocimacro library template |
| velocimacro.library.autoreload | *unchanged* | whether to autoreload library |
| velocimacro.permissions.allow.inline | velocimacro.inline.allow | whether to allow inline velocimacros |
| velocimacro.permissions.allow.inline.to.replace.global | velocimacro.inline.replace_global | whether inline macros override global ones |
| velocimacro.permissions.allow.inline.local.scope | velocimacro.inline.local_scope | whether inline macros have a local scope |
| velocimacro.arguments.strict | *unchanged* | expect strict argments number |
| velocimacro.messages.on (unused) | *deprecated* | obsolete property |
| *n/a* | velocimacro.arguments.preserve_literals (since 2.1) | (1.7 BC flag) whether invalid references is literal provided argument or argument name ; note: deprecated in 2.2 in favor of velocimacro.enable_bc_mode |
| velocimacro.max.depth | velocimacro.max_depth | velocimacros max calling depth |
| velocimacro.body.reference | velocimacro.body_reference | name of the reference holding the body passed to a block macro |
| runtime.references.strict | runtime.strict_mode.enable | enables strict rendering mode |
| runtime.references.strict.escape | runtime.strict_mode.escape | toggles modified escaping in strict rendering mode |
| runtime.introspector.uberspect | introspector.uberspect.class | list of chained uberspectors classnames |
| introspector.restrict.packages | *unchanged* | restricted packages for SecureIntrospector |
| introspector.restrict.classes | *unchanged* | restricted classes for SecureIntrospector |
| runtime.conversion.handler.class (since 2.0) | introspector.conversion_handler.class | method arguments conversion handler classname |
| *n/a* | introspector.conversion_handler.instance (since 2.1) | method arguments conversion handler instance |
| runtime.interpolate.string.literals | runtime.interpolate_string_literals | whether to interpolate string literals in double quotes |
| runtime.strict.math | runtime.strict_math | switch for ignoring nulls in math equations vs throwing exceptions |
| context.autoreference.key | context.self_reference_key | key upon which a context should be accessible within itself |
| *n/a* | parser.allow_hyphen_in_identifiers (since 2.1) | whether to allow '`-`' in identifiers (1.7 BC flag) |
| parser.pool.class | *unchanged* | parser pool class |
| space.gobbling | parser.space_gobbling | space gobbling mode |
| |
| Also, the default velocimacro library template has been renamed from `VM_global_library.vm` to `velocimacros.vtl` ; Velocity will check for the old default path if the new one is not found. |
| |
| ## New Properties Description |
| |
| Velocity Engine 2.1 introduces the following new properties: |
| |
| - `velocimacro.arguments.preserve_literals`: 1.7.x backward compatibility flag: if true, when a macro has to dispay an invalid argument, it displays the literal name of the reference passed to the macro, not the literal name of the argument ; note: deprecated in 2.2 in favor of velocimacro.enable_bc_mode. |
| - `parser.allow_hyphen_in_identifiers`: 1.7.x backward compatibility flag: if true, allow Velocity identifiers to contain an hyphen '`-`' in identifiers (a minus sign in a mathematical expression will then sometimes need a space around it, as was needed in 1.7.x). |
| - `runtime.log.log_invalid_method_calls`: whether to log invalid method calls |
| - `introspector.conversion_handler.instance`: live instance of an `org.apache.velocity.util.introspection.TypeConversionHandler` (or of a deprecated org.apache.velocity.util.introspection.ConversionHandler) |
| |
| |