org.apache.velocity.app
Class VelocityEngine

java.lang.Object
  |
  +--org.apache.velocity.app.VelocityEngine
All 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.

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, ERROR_PREFIX, ERRORMSG_END, ERRORMSG_START, 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, PARSE_DIRECTIVE_MAXDEPTH, PARSER_POOL_SIZE, 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
 
Constructor Summary
VelocityEngine()
           
 
Method Summary
 void addProperty(java.lang.String key, java.lang.Object value)
          Add a Velocity Runtime property.
 void clearProperty(java.lang.String key)
          Clear a Velocity Runtime property.
 void debug(java.lang.Object message)
          Log a debug message.
 void error(java.lang.Object message)
          Log an error message.
 boolean evaluate(Context context, java.io.Writer writer, java.lang.String logTag, java.io.InputStream instream)
          Deprecated. Use evaluate( Context context, Writer writer, String logTag, Reader reader )
 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.
 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.
 java.lang.Object getProperty(java.lang.String key)
          Get a Velocity Runtime property.
 Template getTemplate(java.lang.String name)
          Returns a Template from the Velocity resource management system.
 Template getTemplate(java.lang.String name, java.lang.String encoding)
          Returns a Template from the Velocity resource management system.
 void info(java.lang.Object message)
          Log an info message.
 void init()
          initialize the Velocity runtime engine, using the default properties of the Velocity distribution
 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
 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
 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 parms provided and places the rendered stream into the writer.
 boolean mergeTemplate(java.lang.String templateName, Context context, java.io.Writer writer)
          merges a template and puts the rendered stream into the writer
 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 writer
 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.
 void setConfiguration(Configuration configuration)
          Deprecated. Use setExtendedProperties( ExtendedProperties )
 void setExtendedProperties(org.apache.commons.collections.ExtendedProperties configuration)
          Set an entire configuration at once.
 void setProperty(java.lang.String key, java.lang.Object value)
          Set a Velocity Runtime property.
 boolean templateExists(java.lang.String templateName)
          Determines if a template is accessable via the currently configured resource loaders.
 void warn(java.lang.Object message)
          Log a warning message.
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait
 

Field Detail

ri

private RuntimeInstance ri
Constructor Detail

VelocityEngine

public VelocityEngine()
Method Detail

init

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

init

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

init

public void init(java.util.Properties p)
          throws java.lang.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

setProperty

public void setProperty(java.lang.String key,
                        java.lang.Object value)
Set a Velocity Runtime property.
Parameters:
String - key
Object - value

addProperty

public void addProperty(java.lang.String key,
                        java.lang.Object value)
Add a Velocity Runtime property.
Parameters:
String - key
Object - value

clearProperty

public void clearProperty(java.lang.String key)
Clear a Velocity Runtime property.
Parameters:
key - of property to clear

setConfiguration

public void setConfiguration(Configuration configuration)
Deprecated. Use setExtendedProperties( ExtendedProperties )

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.
Parameters:
Configuration - configuration

setExtendedProperties

public 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:
ExtendedProperties - configuration

getProperty

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

evaluate

public boolean evaluate(Context context,
                        java.io.Writer writer,
                        java.lang.String logTag,
                        java.io.InputStream instream)
                 throws ParseErrorException,
                        MethodInvocationException,
                        ResourceNotFoundException,
                        java.io.IOException
Deprecated. Use evaluate( Context context, Writer writer, String logTag, Reader reader )

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 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
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,
                        java.io.Writer writer,
                        java.lang.String logTag,
                        java.io.Reader reader)
                 throws ParseErrorException,
                        MethodInvocationException,
                        ResourceNotFoundException,
                        java.io.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
out - 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
Since:
Velocity v1.1

invokeVelocimacro

public boolean invokeVelocimacro(java.lang.String vmName,
                                 java.lang.String logTag,
                                 java.lang.String[] params,
                                 Context context,
                                 java.io.Writer writer)
                          throws java.lang.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
params[] - args used to invoke Velocimacro. In context key format : eg "foo","bar" (rather than "$foo","$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(java.lang.String templateName,
                             Context context,
                             java.io.Writer writer)
                      throws ResourceNotFoundException,
                             ParseErrorException,
                             MethodInvocationException,
                             java.lang.Exception
merges a template and puts the rendered stream into the 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. * @deprecated Use mergeTemplate( String templateName, String encoding, Context context, Writer writer )

mergeTemplate

public boolean mergeTemplate(java.lang.String templateName,
                             java.lang.String encoding,
                             Context context,
                             java.io.Writer writer)
                      throws ResourceNotFoundException,
                             ParseErrorException,
                             MethodInvocationException,
                             java.lang.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

getTemplate

public Template getTemplate(java.lang.String name)
                     throws ResourceNotFoundException,
                            ParseErrorException,
                            java.lang.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.
java.lang.Exception - if an error occurs in template initialization

getTemplate

public Template getTemplate(java.lang.String name,
                            java.lang.String encoding)
                     throws ResourceNotFoundException,
                            ParseErrorException,
                            java.lang.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.
java.lang.Exception - if an error occurs in template initialization
Since:
Velocity v1.1

templateExists

public boolean templateExists(java.lang.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(java.lang.Object message)
Log a warning message.
Parameters:
Object - message to log

info

public void info(java.lang.Object message)
Log an info message.
Parameters:
Object - message to log

error

public void error(java.lang.Object message)
Log an error message.
Parameters:
Object - message to log

debug

public void debug(java.lang.Object message)
Log a debug message.
Parameters:
Object - message to log

setApplicationAttribute

public 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 stored
value - object to store under this key


Copyright © 2003 Apache Software Foundation. All Rights Reserved.