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 callsintrospector.conversion_handler.instance: live instance of anorg.apache.velocity.util.introspection.TypeConversionHandler(or of a deprecated org.apache.velocity.util.introspection.ConversionHandler)