Class Velocity
- java.lang.Object
-
- org.apache.velocity.app.Velocity
-
- All Implemented Interfaces:
RuntimeConstants
public class Velocity extends java.lang.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: Velocity.java 898050 2010-01-11 20:15:31Z nbubna $
-
-
Field Summary
-
Fields inherited from interface org.apache.velocity.runtime.RuntimeConstants
COUNTER_INITIAL_VALUE, COUNTER_NAME, DEBUG_PREFIX, DEFAULT_RUNTIME_DIRECTIVES, DEFAULT_RUNTIME_PROPERTIES, DEFINE_DIRECTIVE_MAXDEPTH, DIRECTIVE_IF_TOSTRING_NULLCHECK, ENCODING_DEFAULT, ERROR_PREFIX, ERRORMSG_END, ERRORMSG_START, EVALUATE_CONTEXT_CLASS, EVENTHANDLER_INCLUDE, EVENTHANDLER_INVALIDREFERENCES, EVENTHANDLER_METHODEXCEPTION, EVENTHANDLER_NULLSET, EVENTHANDLER_REFERENCEINSERTION, FILE_RESOURCE_LOADER_CACHE, FILE_RESOURCE_LOADER_PATH, HAS_NEXT_NAME, INFO_PREFIX, INPUT_ENCODING, INTERPOLATE_STRINGLITERALS, INTROSPECTOR_RESTRICT_CLASSES, INTROSPECTOR_RESTRICT_PACKAGES, MAX_NUMBER_LOOPS, NUMBER_OF_PARSERS, OUTPUT_ENCODING, PARSE_DIRECTIVE_MAXDEPTH, PARSER_POOL_CLASS, PARSER_POOL_SIZE, PROVIDE_SCOPE_CONTROL, RESOURCE_LOADER, RESOURCE_MANAGER_CACHE_CLASS, RESOURCE_MANAGER_CLASS, RESOURCE_MANAGER_DEFAULTCACHE_SIZE, RESOURCE_MANAGER_LOGWHENFOUND, RUNTIME_LOG, RUNTIME_LOG_ERROR_STACKTRACE, RUNTIME_LOG_INFO_STACKTRACE, RUNTIME_LOG_LOGSYSTEM, RUNTIME_LOG_LOGSYSTEM_CLASS, RUNTIME_LOG_REFERENCE_LOG_INVALID, RUNTIME_LOG_WARN_STACKTRACE, RUNTIME_REFERENCES_STRICT, RUNTIME_REFERENCES_STRICT_ESCAPE, SET_NULL_ALLOWED, SKIP_INVALID_ITERATOR, STRICT_MATH, TRACE_PREFIX, UBERSPECT_CLASSNAME, UNKNOWN_PREFIX, VM_ARGUMENTS_STRICT, VM_BODY_REFERENCE, VM_CONTEXT_LOCALSCOPE, 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, WARN_PREFIX
-
-
Constructor Summary
Constructors Constructor Description Velocity()
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description static void
addProperty(java.lang.String key, java.lang.Object value)
Add a Velocity Runtime property.static void
clearProperty(java.lang.String key)
Clear a Velocity Runtime property.static void
debug(java.lang.Object message)
Deprecated.Use getLog() and call debug() on it.static void
error(java.lang.Object message)
Deprecated.Use getLog() and call error() on it.static boolean
evaluate(Context context, java.io.Writer writer, java.lang.String logTag, java.io.InputStream instream)
static boolean
evaluate(Context context, java.io.Writer writer, java.lang.String logTag, java.io.Reader reader)
Renders the input reader using the context into the output writer.static boolean
evaluate(Context context, java.io.Writer out, java.lang.String logTag, java.lang.String instring)
renders the input string using the context into the output writer.static Log
getLog()
Returns a convenient Log instance that wraps the current LogChute.static java.lang.Object
getProperty(java.lang.String key)
Get a Velocity Runtime property.static Template
getTemplate(java.lang.String name)
Returns aTemplate
from the Velocity resource management system.static Template
getTemplate(java.lang.String name, java.lang.String encoding)
Returns aTemplate
from the Velocity resource management system.static void
info(java.lang.Object message)
Deprecated.Use getLog() and call info() on it.static void
init()
initialize the Velocity runtime engine, using the default properties of the Velocity distributionstatic void
init(java.lang.String propsFilename)
initialize the Velocity runtime engine, using default properties plus the properties in the properties file passed in as the argstatic void
init(java.util.Properties p)
initialize the Velocity runtime engine, using default properties plus the properties in the passed in java.util.Properties objectstatic boolean
invokeVelocimacro(java.lang.String vmName, java.lang.String logTag, java.lang.String[] params, Context context, java.io.Writer writer)
Invokes a currently registered Velocimacro with the params provided and places the rendered stream into the writer.void
loadDirective(java.lang.String directiveClass)
Instantiates and loads the directive with some basic checks.static boolean
mergeTemplate(java.lang.String templateName, java.lang.String encoding, Context context, java.io.Writer writer)
merges a template and puts the rendered stream into the writerstatic boolean
mergeTemplate(java.lang.String templateName, Context context, java.io.Writer writer)
void
removeDirective(java.lang.String name)
Remove a directive.static boolean
resourceExists(java.lang.String resourceName)
Determines whether a resource is accessable via the currently configured resource loaders.static void
setApplicationAttribute(java.lang.Object key, java.lang.Object value)
Set the an ApplicationAttribue, which is an Object set by the application which is accessable from any component of the system that gets a RuntimeServices.static void
setExtendedProperties(org.apache.commons.collections.ExtendedProperties configuration)
Set an entire configuration at once.static void
setProperty(java.lang.String key, java.lang.Object value)
Set a Velocity Runtime property.static boolean
templateExists(java.lang.String resourceName)
Deprecated.Use resourceExists(String) instead.static void
warn(java.lang.Object message)
Deprecated.Use getLog() and call warn() on it.
-
-
-
Method Detail
-
init
public static void init()
initialize the Velocity runtime engine, using the default properties of the Velocity distribution
-
init
public static void init(java.lang.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(java.util.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(java.lang.String key, java.lang.Object value)
Set a Velocity Runtime property.- Parameters:
key
- The property key.value
- The property value.
-
addProperty
public static void addProperty(java.lang.String key, java.lang.Object value)
Add a Velocity Runtime property.- Parameters:
key
- The property key.value
- The property value.
-
clearProperty
public static void clearProperty(java.lang.String key)
Clear a Velocity Runtime property.- Parameters:
key
- of property to clear
-
setExtendedProperties
public static void setExtendedProperties(org.apache.commons.collections.ExtendedProperties configuration)
Set an entire configuration at once. This is useful in cases where the parent application uses the ExtendedProperties class and the velocity configuration is a subset of the parent application's configuration.- Parameters:
configuration
- A configuration object.
-
getProperty
public static java.lang.Object getProperty(java.lang.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, java.io.Writer out, java.lang.String logTag, java.lang.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 static boolean evaluate(Context context, java.io.Writer writer, java.lang.String logTag, java.io.InputStream instream) throws ParseErrorException, MethodInvocationException, ResourceNotFoundException
Renders the input stream 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 errorinstream
- input stream 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.IOException
- While loading a reference, an I/O problem occured.
-
evaluate
public static boolean evaluate(Context context, java.io.Writer writer, java.lang.String logTag, java.io.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 static boolean invokeVelocimacro(java.lang.String vmName, java.lang.String logTag, java.lang.String[] params, Context context, java.io.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 static boolean mergeTemplate(java.lang.String templateName, Context context, java.io.Writer writer) throws ResourceNotFoundException, ParseErrorException, MethodInvocationException
Deprecated.Merges a template and puts the rendered stream into the writer. The default encoding that Velocity uses to read template files is defined in the property input.encoding and defaults to ISO-8859-1.- Parameters:
templateName
- name of template to be used in mergecontext
- filled context to be used in mergewriter
- 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.
-
mergeTemplate
public static boolean mergeTemplate(java.lang.String templateName, java.lang.String encoding, Context context, java.io.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:
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(java.lang.String name) throws ResourceNotFoundException, ParseErrorException
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 static Template getTemplate(java.lang.String name, java.lang.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
public static boolean resourceExists(java.lang.String resourceName)
Determines whether a resource is accessable 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 Log getLog()
Returns a convenient Log instance that wraps the current LogChute. Use this to log error messages. It has the usual methods.- Returns:
- A convenience Log instance that wraps the current LogChute.
- Since:
- 1.5
-
warn
public static void warn(java.lang.Object message)
Deprecated.Use getLog() and call warn() on it.- Parameters:
message
- The message to log.- See Also:
Log.warn(Object)
-
info
public static void info(java.lang.Object message)
Deprecated.Use getLog() and call info() on it.- Parameters:
message
- The message to log.- See Also:
Log.info(Object)
-
error
public static void error(java.lang.Object message)
Deprecated.Use getLog() and call error() on it.- Parameters:
message
- The message to log.- See Also:
Log.error(Object)
-
debug
public static void debug(java.lang.Object message)
Deprecated.Use getLog() and call debug() on it.- Parameters:
message
- The message to log.- See Also:
Log.debug(Object)
-
setApplicationAttribute
public static void setApplicationAttribute(java.lang.Object key, java.lang.Object value)
Set the an ApplicationAttribue, which is an Object set by the application which is accessable 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 enfocement 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
-
templateExists
public static boolean templateExists(java.lang.String resourceName)
Deprecated.Use resourceExists(String) instead.- Parameters:
resourceName
- Name of the Template to check.- Returns:
- True if the template exists.
- See Also:
resourceExists(String)
-
removeDirective
public void removeDirective(java.lang.String name)
Remove a directive.- Parameters:
name
- name of the directive.
-
loadDirective
public void loadDirective(java.lang.String directiveClass)
Instantiates and loads the directive with some basic checks.- Parameters:
directiveClass
- classname of directive to load
-
-