Velocity Engine

Docs

Developers

Community

Translations (outdated)

Velocity News Feed

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)