org.apache.velocity.app

Class VelocityEngine

Implemented Interfaces:
RuntimeConstants

public class VelocityEngine
extends java.lang.Object
implements 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.

Please ensure that you call one of the init() variants. This is critical for proper behavior.

Coming soon : 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 almost certainly won't function in the way you intend, so please make sure to call init().

Version:
$Id: VelocityEngine.java,v 1.5 2002/01/03 12:41:19 geirm Exp $

Author:
Geir Magnusson Jr.

Nested Class Summary

Field Summary

private RuntimeInstance
ri

Fields inherited from interface org.apache.velocity.runtime.RuntimeConstants

COUNTER_INITIAL_VALUE, COUNTER_NAME, DEBUG_PREFIX, DEFAULT_RUNTIME_DIRECTIVES, DEFAULT_RUNTIME_PROPERTIES, ENCODING_DEFAULT, ERRORMSG_END, ERRORMSG_START, ERROR_PREFIX, FILE_RESOURCE_LOADER_CACHE, FILE_RESOURCE_LOADER_PATH, INFO_PREFIX, INPUT_ENCODING, INTERPOLATE_STRINGLITERALS, LOGSYSTEM_LOG4J_EMAIL_BUFFER_SIZE, LOGSYSTEM_LOG4J_EMAIL_FROM, LOGSYSTEM_LOG4J_EMAIL_SERVER, LOGSYSTEM_LOG4J_EMAIL_SUBJECT, LOGSYSTEM_LOG4J_EMAIL_TO, LOGSYSTEM_LOG4J_FILE_BACKUPS, LOGSYSTEM_LOG4J_FILE_SIZE, LOGSYSTEM_LOG4J_PATTERN, LOGSYSTEM_LOG4J_REMOTE_HOST, LOGSYSTEM_LOG4J_REMOTE_PORT, LOGSYSTEM_LOG4J_SYSLOGD_FACILITY, LOGSYSTEM_LOG4J_SYSLOGD_HOST, NUMBER_OF_PARSERS, OUTPUT_ENCODING, PARSER_POOL_SIZE, PARSE_DIRECTIVE_MAXDEPTH, RESOURCE_LOADER, RESOURCE_MANAGER_CACHE_CLASS, RESOURCE_MANAGER_CLASS, 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, UNKNOWN_PREFIX, VM_CONTEXT_LOCALSCOPE, VM_LIBRARY, VM_LIBRARY_AUTORELOAD, VM_MESSAGES_ON, VM_PERM_ALLOW_INLINE, VM_PERM_ALLOW_INLINE_REPLACE_GLOBAL, VM_PERM_INLINE_LOCAL, WARN_PREFIX

Method Summary

void
addProperty(String key, Object value)
Add a Velocity Runtime property.
void
clearProperty(String key)
Clear a Velocity Runtime property.
void
debug(Object message)
Log a debug message.
void
error(Object message)
Log an error message.
boolean
evaluate(Context context, Writer writer, String logTag, InputStream instream)
Deprecated. Use
boolean
evaluate(Context context, Writer writer, String logTag, Reader reader)
Renders the input reader using the context into the output writer.
boolean
evaluate(Context context, Writer out, String logTag, String instring)
renders the input string using the context into the output writer.
Object
getProperty(String key)
Get a Velocity Runtime property.
Template
getTemplate(String name)
Returns a Template from the Velocity resource management system.
Template
getTemplate(String name, String encoding)
Returns a Template from the Velocity resource management system.
void
info(Object message)
Log an info message.
void
init()
initialize the Velocity runtime engine, using the default properties of the Velocity distribution
void
init(Properties p)
initialize the Velocity runtime engine, using default properties plus the properties in the passed in java.util.Properties object
void
init(String propsFilename)
initialize the Velocity runtime engine, using default properties plus the properties in the properties file passed in as the arg
boolean
invokeVelocimacro(String vmName, String logTag, params[] , Context context, Writer writer)
Invokes a currently registered Velocimacro with the parms provided and places the rendered stream into the writer.
boolean
mergeTemplate(String templateName, String encoding, Context context, Writer writer)
merges a template and puts the rendered stream into the writer
boolean
mergeTemplate(String templateName, Context context, Writer writer)
Deprecated. Use
void
setApplicationAttribute(Object key, 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.
void
setConfiguration(Configuration configuration)
Deprecated. Use
void
setExtendedProperties(ExtendedProperties configuration)
Set an entire configuration at once.
void
setProperty(String key, Object value)
Set a Velocity Runtime property.
boolean
templateExists(String templateName)
Determines if a template is accessable via the currently configured resource loaders.
void
warn(Object message)
Log a warning message.

Field Details

ri

private RuntimeInstance ri

Method Details

addProperty

public void addProperty(String key,
                        Object value)
Add a Velocity Runtime property.

Parameters:


clearProperty

public void clearProperty(String key)
Clear a Velocity Runtime property.

Parameters:
key - of property to clear


debug

public void debug(Object message)
Log a debug message.

Parameters:


error

public void error(Object message)
Log an error message.

Parameters:


evaluate

public boolean evaluate(Context context,
                        Writer writer,
                        String logTag,
                        InputStream instream)
            throws ParseErrorException,
                   MethodInvocationException,
                   ResourceNotFoundException,
                   IOException

Deprecated. Use

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. evaluate( Context context, Writer writer, String logTag, Reader reader )

Parameters:
context - context to use in rendering input string
logTag - string to be used as the template name for log messages in case of error
instream - input stream containing the VTL to be rendered

Returns:
true if successful, false otherwise. If false, see Velocity runtime log


evaluate

public boolean evaluate(Context context,
                        Writer writer,
                        String logTag,
                        Reader reader)
            throws ParseErrorException,
                   MethodInvocationException,
                   ResourceNotFoundException,
                   IOException
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
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

Since:
Velocity v1.1


evaluate

public boolean evaluate(Context context,
                        Writer out,
                        String logTag,
                        String instring)
            throws ParseErrorException,
                   MethodInvocationException,
                   ResourceNotFoundException,
                   IOException
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


getProperty

public 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


getTemplate

public Template getTemplate(String name)
            throws ResourceNotFoundException,
                   ParseErrorException,
                   Exception
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 Template getTemplate(String name,
                            String encoding)
            throws ResourceNotFoundException,
                   ParseErrorException,
                   Exception
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


info

public void info(Object message)
Log an info message.

Parameters:


init

public void init()
            throws Exception
initialize the Velocity runtime engine, using the default properties of the Velocity distribution


init

public void init(Properties p)
            throws Exception
initialize the Velocity runtime engine, using default properties plus the properties in the passed in java.util.Properties object

Parameters:
p - Proprties object containing initialization properties


init

public void init(String propsFilename)
            throws Exception
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


invokeVelocimacro

public boolean invokeVelocimacro(String vmName,
                                 String logTag,
                                 params[] ,
                                 Context context,
                                 Writer writer)
            throws Exception
Invokes a currently registered Velocimacro with the parms 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
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,
                   Exception
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

Since:
Velocity v1.1


mergeTemplate

public boolean mergeTemplate(String templateName,
                             Context context,
                             Writer writer)
            throws ResourceNotFoundException,
                   ParseErrorException,
                   MethodInvocationException,
                   Exception

Deprecated. Use

merges a template and puts the rendered stream into the writer mergeTemplate( String templateName, String encoding, Context context, Writer writer )

Parameters:
templateName - name of template to be used in merge
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.


setApplicationAttribute

public void setApplicationAttribute(Object key,
                                    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 stored
value - object to store under this key


setConfiguration

public void setConfiguration(Configuration configuration)

Deprecated. Use

Set an entire configuration at once. This is useful in cases where the parent application uses the Configuration class and the velocity configuration is a subset of the parent application's configuration. setExtendedProperties(ExtendedProperties)

Parameters:


setExtendedProperties

public void setExtendedProperties(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:


setProperty

public void setProperty(String key,
                        Object value)
Set a Velocity Runtime property.

Parameters:


templateExists

public boolean templateExists(String templateName)
Determines if a template is accessable 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 lazyness and sloth, and the author has been flogged.

Parameters:
templateName - name of the temlpate to search for

Returns:
true if found, false otherwise


warn

public void warn(Object message)
Log a warning message.

Parameters:


Copyright © 2003 Apache Software Foundation. All Rights Reserved.