Class VelocityEngine
- All Implemented Interfaces:
DeprecatedRuntimeConstants
,RuntimeConstants
This class provides a separate new-able instance of the Velocity template engine. The alternative model for use is using the Velocity class which employs the singleton model.
Velocity will call the parameter-less init() at the first use of this class if the init() wasn't explicitly called. While this will ensure that Velocity functions, it probably won't function in the way you intend, so it is strongly recommended that you call an init() method yourself if you use the default constructor.
- Version:
- $Id$
-
Nested Class Summary
Nested classes/interfaces inherited from interface org.apache.velocity.runtime.RuntimeConstants
RuntimeConstants.SpaceGobbling
-
Field Summary
Fields inherited from interface org.apache.velocity.runtime.DeprecatedRuntimeConstants
OLD_CHECK_EMPTY_OBJECTS, OLD_CONTEXT_AUTOREFERENCE_KEY, OLD_CONVERSION_HANDLER_CLASS, OLD_CUSTOM_DIRECTIVES, OLD_DEFINE_DIRECTIVE_MAXDEPTH, OLD_DS_RESOURCE_LOADER_DATASOURCE, OLD_DS_RESOURCE_LOADER_KEY_COLUMN, OLD_DS_RESOURCE_LOADER_TEMPLATE_COLUMN, OLD_DS_RESOURCE_LOADER_TIMESTAMP_COLUMN, OLD_ERRORMSG_END, OLD_ERRORMSG_START, OLD_EVENTHANDLER_INCLUDE, OLD_EVENTHANDLER_INVALIDREFERENCES, OLD_EVENTHANDLER_METHODEXCEPTION, OLD_EVENTHANDLER_REFERENCEINSERTION, OLD_FILE_RESOURCE_LOADER_CACHE, OLD_FILE_RESOURCE_LOADER_PATH, OLD_INPUT_ENCODING, OLD_INTERPOLATE_STRINGLITERALS, OLD_MAX_NUMBER_LOOPS, OLD_PARSE_DIRECTIVE_MAXDEPTH, OLD_RESOURCE_LOADER_CHECK_INTERVAL, OLD_RESOURCE_LOADERS, OLD_RESOURCE_MANAGER_DEFAULTCACHE_SIZE, OLD_RESOURCE_MANAGER_LOGWHENFOUND, OLD_RUNTIME_LOG_REFERENCE_LOG_INVALID, OLD_RUNTIME_REFERENCES_STRICT, OLD_RUNTIME_REFERENCES_STRICT_ESCAPE, OLD_SKIP_INVALID_ITERATOR, OLD_SPACE_GOBBLING, OLD_STRICT_MATH, OLD_UBERSPECT_CLASSNAME, OLD_VM_BODY_REFERENCE, OLD_VM_ENABLE_BC_MODE, OLD_VM_LIBRARY, OLD_VM_LIBRARY_DEFAULT, OLD_VM_MAX_DEPTH, OLD_VM_PERM_ALLOW_INLINE, OLD_VM_PERM_ALLOW_INLINE_REPLACE_GLOBAL, OLD_VM_PERM_INLINE_LOCAL
Fields inherited from interface org.apache.velocity.runtime.RuntimeConstants
CHECK_EMPTY_OBJECTS, CONTEXT_AUTOREFERENCE_KEY, CONTEXT_SCOPE_CONTROL, CONVERSION_HANDLER_CLASS, CONVERSION_HANDLER_INSTANCE, CUSTOM_DIRECTIVES, DEFAULT_PARSER_CLASS, DEFAULT_RUNTIME_DIRECTIVES, DEFAULT_RUNTIME_LOG_NAME, DEFAULT_RUNTIME_PROPERTIES, DEFINE_DIRECTIVE_MAXDEPTH, DS_RESOURCE_LOADER_DATASOURCE, DS_RESOURCE_LOADER_DATASOURCE_URL, DS_RESOURCE_LOADER_KEY_COLUMN, DS_RESOURCE_LOADER_STMT_POOL_MAX_SIZE, DS_RESOURCE_LOADER_TABLE, DS_RESOURCE_LOADER_TEMPLATE_COLUMN, DS_RESOURCE_LOADER_TIMESTAMP_COLUMN, ENCODING_DEFAULT, ERRORMSG_END, ERRORMSG_START, EVENTHANDLER_INCLUDE, EVENTHANDLER_INVALIDREFERENCES, EVENTHANDLER_INVALIDREFERENCES_NULL, EVENTHANDLER_INVALIDREFERENCES_QUIET, EVENTHANDLER_INVALIDREFERENCES_TESTED, EVENTHANDLER_METHODEXCEPTION, EVENTHANDLER_REFERENCEINSERTION, FILE_RESOURCE_LOADER_CACHE, FILE_RESOURCE_LOADER_PATH, IMMUTABLE_RANGES, INPUT_ENCODING, INTERPOLATE_STRINGLITERALS, INTROSPECTOR_RESTRICT_CLASSES, INTROSPECTOR_RESTRICT_PACKAGES, MAX_NUMBER_LOOPS, NUMBER_OF_PARSERS, PARSE_DIRECTIVE_MAXDEPTH, PARSER_CLASS, PARSER_HYPHEN_ALLOWED, PARSER_POOL_CLASS, PARSER_POOL_SIZE, PROVIDE_SCOPE_CONTROL, RESOURCE_LOADER, RESOURCE_LOADER_CACHE, RESOURCE_LOADER_CHECK_INTERVAL, RESOURCE_LOADER_CLASS, RESOURCE_LOADER_IDENTIFIER, RESOURCE_LOADER_INSTANCE, RESOURCE_LOADER_PATHS, RESOURCE_LOADERS, RESOURCE_MANAGER_CACHE_CLASS, RESOURCE_MANAGER_CLASS, RESOURCE_MANAGER_DEFAULTCACHE_SIZE, RESOURCE_MANAGER_INSTANCE, RESOURCE_MANAGER_LOGWHENFOUND, RUNTIME_LOG_INSTANCE, RUNTIME_LOG_METHOD_CALL_LOG_INVALID, RUNTIME_LOG_NAME, RUNTIME_LOG_REFERENCE_LOG_INVALID, RUNTIME_LOG_TRACK_LOCATION, RUNTIME_REFERENCES_STRICT, RUNTIME_REFERENCES_STRICT_ESCAPE, RUNTIME_STRING_INTERNING, SKIP_INVALID_ITERATOR, SPACE_GOBBLING, STRICT_MATH, UBERSPECT_CLASSNAME, VM_ARGUMENTS_STRICT, VM_BODY_REFERENCE, VM_ENABLE_BC_MODE, VM_LIBRARY, VM_LIBRARY_AUTORELOAD, VM_LIBRARY_DEFAULT, VM_MAX_DEPTH, VM_MESSAGES_ON, VM_PERM_ALLOW_INLINE, VM_PERM_ALLOW_INLINE_REPLACE_GLOBAL, VM_PERM_INLINE_LOCAL
-
Constructor Summary
ConstructorDescriptionInit-less CTORVelocityEngine
(String propsFilename) Construct a VelocityEngine with the initial properties defined in the file propsFilenameConstruct a VelocityEngine instance with the specified initial properties. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addProperty
(String key, Object value) Add a Velocity Runtime property.void
clearProperty
(String key) Clear a Velocity Runtime property.boolean
Renders the input reader using the context into the output writer.boolean
renders the input string using the context into the output writer.Return an application attribute (which can be any Object) that was set by the application in order to be accessible from any component of the system that gets a RuntimeServices.org.slf4j.Logger
getLog()
Returns the current slf4j logger.getProperty
(String key) Get a Velocity Runtime property.getTemplate
(String name) Returns aTemplate
from the Velocity resource management system.getTemplate
(String name, String encoding) Returns aTemplate
from the Velocity resource management system.void
init()
initialize the Velocity runtime engine, using the default properties of the Velocity distributionvoid
initialize the Velocity runtime engine, using default properties plus the properties in the properties file passed in as the argvoid
init
(Properties p) initialize the Velocity runtime engine, using default properties plus the properties in the passed in java.util.Properties objectboolean
Invokes a currently registered Velocimacro with the params provided and places the rendered stream into the writer.void
loadDirective
(String directiveClass) Instantiates and loads the directive with some basic checks.boolean
mergeTemplate
(String templateName, String encoding, Context context, Writer writer) merges a template and puts the rendered stream into the writervoid
removeDirective
(String name) Remove a directive.void
reset()
Resets the instance, so Velocity can be re-initialized again.boolean
resourceExists
(String resourceName) Determines if a resource is accessible via the currently configured resource loaders.void
setApplicationAttribute
(Object key, Object value) Sets an application attribute (which can be any Object) that will be accessible from any component of the system that gets a RuntimeServices.void
setProperties
(String propsFilename) Set an entire configuration at once from a named properties filevoid
setProperties
(Properties configuration) Set an entire configuration at once from a Properties configurationvoid
setProperty
(String key, Object value) Set a Velocity Runtime property.
-
Constructor Details
-
VelocityEngine
public VelocityEngine()Init-less CTOR -
VelocityEngine
Construct a VelocityEngine with the initial properties defined in the file propsFilename- Parameters:
propsFilename
- properties filename
-
VelocityEngine
Construct a VelocityEngine instance with the specified initial properties.- Parameters:
p
- properties
-
-
Method Details
-
init
public void init()initialize the Velocity runtime engine, using the default properties of the Velocity distribution -
reset
public void reset()Resets the instance, so Velocity can be re-initialized again.- Since:
- 2.0.0
-
init
initialize the Velocity runtime engine, using default properties plus the properties in the properties file passed in as the arg- Parameters:
propsFilename
- file containing properties to use to initialize the Velocity runtime
-
init
initialize the Velocity runtime engine, using default properties plus the properties in the passed in java.util.Properties object- Parameters:
p
- Properties object containing initialization properties
-
setProperty
Set a Velocity Runtime property.- Parameters:
key
-value
-
-
addProperty
Add a Velocity Runtime property.- Parameters:
key
-value
-
-
clearProperty
Clear a Velocity Runtime property.- Parameters:
key
- of property to clear
-
setProperties
Set an entire configuration at once from a Properties configuration- Parameters:
configuration
-- Since:
- 2.0
-
setProperties
Set an entire configuration at once from a named properties file- Parameters:
propsFilename
- properties filename- Since:
- 2.1
-
getProperty
Get a Velocity Runtime property.- Parameters:
key
- property to retrieve- Returns:
- property value or null if the property not currently set
-
evaluate
public boolean evaluate(Context context, Writer out, String logTag, String instring) throws ParseErrorException, MethodInvocationException, ResourceNotFoundException renders the input string using the context into the output writer. To be used when a template is dynamically constructed, or want to use Velocity as a token replacer.- Parameters:
context
- context to use in rendering input stringout
- Writer in which to render the outputlogTag
- string to be used as the template name for log messages in case of errorinstring
- input string containing the VTL to be rendered- Returns:
- true if successful, false otherwise. If false, see Velocity runtime log
- Throws:
ParseErrorException
- The template could not be parsed.MethodInvocationException
- A method on a context object could not be invoked.ResourceNotFoundException
- A referenced resource could not be loaded.
-
evaluate
public boolean evaluate(Context context, Writer writer, String logTag, Reader reader) throws ParseErrorException, MethodInvocationException, ResourceNotFoundException Renders the input reader using the context into the output writer. To be used when a template is dynamically constructed, or want to use Velocity as a token replacer.- Parameters:
context
- context to use in rendering input stringwriter
- Writer in which to render the outputlogTag
- string to be used as the template name for log messages in case of errorreader
- Reader containing the VTL to be rendered- Returns:
- true if successful, false otherwise. If false, see Velocity runtime log
- Throws:
ParseErrorException
- The template could not be parsed.MethodInvocationException
- A method on a context object could not be invoked.ResourceNotFoundException
- A referenced resource could not be loaded.- Since:
- Velocity v1.1
-
invokeVelocimacro
public boolean invokeVelocimacro(String vmName, String logTag, String[] params, Context context, Writer writer) Invokes a currently registered Velocimacro with the params provided and places the rendered stream into the writer.
Note : currently only accepts args to the VM if they are in the context.- Parameters:
vmName
- name of Velocimacro to calllogTag
- string to be used for template name in case of error. if null, the vmName will be usedparams
- keys for args used to invoke Velocimacro, in java format rather than VTL (eg "foo" or "bar" rather than "$foo" or "$bar")context
- Context object containing data/objects used for rendering.writer
- Writer for output stream- Returns:
- true if Velocimacro exists and successfully invoked, false otherwise.
-
mergeTemplate
public boolean mergeTemplate(String templateName, String encoding, Context context, Writer writer) throws ResourceNotFoundException, ParseErrorException, MethodInvocationException merges a template and puts the rendered stream into the writer- Parameters:
templateName
- name of template to be used in mergeencoding
- encoding used in templatecontext
- filled context to be used in mergewriter
- writer to write template into- Returns:
- true if successful, false otherwise. Errors logged to velocity log
- Throws:
ResourceNotFoundException
ParseErrorException
MethodInvocationException
- Since:
- Velocity v1.1
-
getTemplate
Returns aTemplate
from the Velocity resource management system.- Parameters:
name
- The file name of the desired template.- Returns:
- The template.
- Throws:
ResourceNotFoundException
- if template not found from any available source.ParseErrorException
- if template cannot be parsed due to syntax (or other) error.
-
getTemplate
public Template getTemplate(String name, String encoding) throws ResourceNotFoundException, ParseErrorException Returns aTemplate
from the Velocity resource management system.- Parameters:
name
- The file name of the desired template.encoding
- The character encoding to use for the template.- Returns:
- The template.
- Throws:
ResourceNotFoundException
- if template not found from any available source.ParseErrorException
- if template cannot be parsed due to syntax (or other) error.- Since:
- Velocity v1.1
-
resourceExists
Determines if a resource is accessible via the currently configured resource loaders.
Note that the current implementation will not change the state of the system in any real way - so this cannot be used to pre-load the resource cache, as the previous implementation did as a side-effect.
The previous implementation exhibited extreme laziness and sloth, and the author has been flogged.- Parameters:
resourceName
- name of the resource to search for- Returns:
- true if found, false otherwise
- Since:
- 1.5
-
getLog
public org.slf4j.Logger getLog()Returns the current slf4j logger. Its namespace defaults toorg.apache.velocity
if it hasn't been configured using the propertyruntime.log.name
or the propertyruntime.log.instance
.- Returns:
- A Logger object.
- Since:
- 1.5
-
setApplicationAttribute
Sets an application attribute (which can be any Object) that will be accessible from any component of the system that gets a RuntimeServices. This allows communication between the application environment and custom pluggable components of the Velocity engine, such as ResourceLoaders and Loggers.
Note that there is no enforcement or rules for the key used - it is up to the application developer. However, to help make the intermixing of components possible, using the target Class name (e.g. com.foo.bar ) as the key might help avoid collision.
- Parameters:
key
- object 'name' under which the object is storedvalue
- object to store under this key
-
getApplicationAttribute
Return an application attribute (which can be any Object) that was set by the application in order to be accessible from any component of the system that gets a RuntimeServices. This allows communication between the application environment and custom pluggable components of the Velocity engine, such as ResourceLoaders and Loggers.
- Parameters:
key
- object 'name' under which the object is stored- Returns:
- value object to store under this key
- Since:
- 1.5
-
removeDirective
Remove a directive.- Parameters:
name
- name of the directive.
-
loadDirective
Instantiates and loads the directive with some basic checks.- Parameters:
directiveClass
- classname of directive to load
-