org.apache.velocity.app

Class Velocity

java.lang.Object

org.apache.velocity.app.Velocity

All Implemented Interfaces:

DeprecatedRuntimeConstants, RuntimeConstants

public class Velocity
extends Object
implements RuntimeConstants

This class provides services to the application developer, such as:

• Simple Velocity Runtime engine initialization methods.
• Functions to apply the template engine to streams and strings to allow embedding and dynamic template generation.
• Methods to access Velocimacros directly.

While the most common way to use Velocity is via templates, as Velocity is a general-purpose template engine, there are other uses that Velocity is well suited for, such as processing dynamically created templates, or processing content streams.

The methods herein were developed to allow easy access to the Velocity facilities without direct spelunking of the internals. If there is something you feel is necessary to add here, please, send a patch.

Version:

$Id$

Author:

Geir Magnusson Jr., Christoph Reck, Jason van Zyl

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.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_KEY_COLUMN, 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, 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

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

Constructor Summary

Constructors

Constructor and Description
Velocity()

Method Summary

Modifier and Type	Method and Description
static void	addProperty(String key, Object value) Add a Velocity Runtime property.
static void	clearProperty(String key) Clear a Velocity Runtime property.
static boolean	evaluate(Context context, Writer writer, String logTag, Reader reader) Renders the input reader using the context into the output writer.
static boolean	evaluate(Context context, Writer out, String logTag, String instring) renders the input string using the context into the output writer.
static org.slf4j.Logger	getLog() Returns the current logger.
static Object	getProperty(String key) Get a Velocity Runtime property.
static Template	getTemplate(String name) Returns a Template from the Velocity resource management system.
static Template	getTemplate(String name, String encoding) Returns a Template from the Velocity resource management system.
static void	init() initialize the Velocity runtime engine, using the default properties of the Velocity distribution
static void	init(Properties p) initialize the Velocity runtime engine, using default properties plus the properties in the passed in java.util.Properties object
static void	init(String propsFilename) initialize the Velocity runtime engine, using default properties plus the properties in the properties file passed in as the arg
static 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.
void	loadDirective(String directiveClass) Instantiates and loads the directive with some basic checks.
static boolean	mergeTemplate(String templateName, String encoding, Context context, Writer writer) Merges a template and puts the rendered stream into the writer
void	removeDirective(String name) Remove a directive.
static void	reset() Resets the instance, so Velocity can be re-initialized again.
static boolean	resourceExists(String resourceName) Determines whether a resource is accessible via the currently configured resource loaders.
static void	setApplicationAttribute(Object key, Object value) Set the an ApplicationAttribue, which is an Object set by the application which is accessible from any component of the system that gets a RuntimeServices.
static void	setProperties(Properties configuration) Set an entire configuration at once.
static void	setProperty(String key, Object value) Set a Velocity Runtime property.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Velocity

public Velocity()

Method Detail

init

public static void init()

initialize the Velocity runtime engine, using the default properties of the Velocity distribution

reset

public static void reset()

Resets the instance, so Velocity can be re-initialized again.

Since:

2.0.0

init

public static void init(String propsFilename)

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

public static void init(Properties p)

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

public static void setProperty(String key,
                               Object value)

Set a Velocity Runtime property.

Parameters:

key - The property key.

value - The property value.

addProperty

public static void addProperty(String key,
                               Object value)

Add a Velocity Runtime property.

Parameters:

key - The property key.

value - The property value.

clearProperty

public static void clearProperty(String key)

Clear a Velocity Runtime property.

Parameters:

key - of property to clear

setProperties

public static void setProperties(Properties configuration)

Set an entire configuration at once.

Parameters:

configuration - A configuration object.

Since:

2.0

getProperty

public static Object getProperty(String key)

Get a Velocity Runtime property.

Parameters:

key - property to retrieve

Returns:

property value or null if the property not currently set

evaluate

public static 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 string

out - Writer in which to render the output

logTag - string to be used as the template name for log messages in case of error

instring - 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 static 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 string

writer - Writer in which to render the output

logTag - string to be used as the template name for log messages in case of error

reader - 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 static 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 call

logTag - string to be used for template name in case of error. if null, the vmName will be used

params - 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 static 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 merge

encoding - encoding used in template

context - filled context to be used in merge

writer - writer to write template into

Returns:

true if successful, false otherwise. Errors logged to velocity 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

getTemplate

public static Template getTemplate(String name)
                            throws ResourceNotFoundException,
                                   ParseErrorException

Returns a Template 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 static Template getTemplate(String name,
                                   String encoding)
                            throws ResourceNotFoundException,
                                   ParseErrorException

Returns a Template 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

public static boolean resourceExists(String resourceName)

Determines whether a resource is accessible via the currently configured resource loaders. Resource is the generic description of templates, static content, etc.

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.

Parameters:

resourceName - The name of the resource to search for.

Returns:

Whether the resource was located.

getLog

public static org.slf4j.Logger getLog()

Returns the current logger.

Returns:

A convenience Logger instance.

Since:

1.5

setApplicationAttribute

public static void setApplicationAttribute(Object key,
                                           Object value)

Set the an ApplicationAttribue, which is an Object set by the application which is 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 loaders 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 stored

value - object to store under this key

removeDirective

public void removeDirective(String name)

Remove a directive.

Parameters:

name - name of the directive.

loadDirective

public void loadDirective(String directiveClass)

Instantiates and loads the directive with some basic checks.

Parameters:

directiveClass - classname of directive to load