Eclipse
Eclipse
IDEA
IntelliJ
NetBeans
NetBeans
XpoLog
XpoLog
org.apache.velocity.app
Class VelocityEngine
Tab mode
public class VelocityEngine
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().

SinceNot specified.
Version$Id: VelocityEngine.java 471381 2006-11-05 08:56:58Z wglass $
AuthorNot specified.
Wiki javadoc Use textile entry format.
Add your comments here.
Constructor Summary
VelocityEngine()
Init-less CTOR
VelocityEngine( String propsFilename )
CTOR that invokes an init(String), initializing the engine using the properties file specified
VelocityEngine( Properties p )
CTOR that invokes an init(String), initializing the engine using the Properties specified
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 )
No description provided.
void error( Object message )
No description provided.
boolean evaluate( Context context, Writer out, String logTag, String instring )
renders the input string using the context into the output writer.
boolean evaluate( Context context, Writer writer, String logTag, InputStream instream )
Renders the input stream using the context into the output writer.
boolean evaluate( Context context, Writer writer, String logTag, Reader reader )
Renders the input reader using the context into the output writer.
Object getApplicationAttribute( Object key )

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.

Log getLog()
Returns a convenient Log instance that wraps the current LogChute.
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 )
No description provided.
void init()
initialize the Velocity runtime engine, using the default properties of the Velocity distribution
void init( String propsFilename )
initialize the Velocity runtime engine, using default properties plus the properties in the properties file passed in as the arg
void init( Properties p )
initialize the Velocity runtime engine, using default properties plus the properties in the passed in java.util.Properties object
boolean invokeVelocimacro( String vmName, String logTag, String [] 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, Context context, Writer writer )
Merges a template and puts 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 resourceExists( String resourceName )
Determines if a resource is accessable 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 setExtendedProperties( ExtendedProperties configuration )
Set an entire configuration at once.
void setProperty( String key, Object value )
Set a Velocity Runtime property.
boolean templateExists( String resourceName )
No description provided.
void warn( Object message )
No description provided.
Methods inherited from java.langObject
Constructor Detail
VelocityEngine
public VelocityEngine ( )
Init-less CTOR
Wiki javadoc Use textile entry format.
Add your comments here.
VelocityEngine
public VelocityEngine ( String propsFilename )
throws
CTOR that invokes an init(String), initializing the engine using the properties file specified
Parameters
TypeNameDescription
String propsFilename name of properties file to init with
Exceptions
Exception No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
VelocityEngine
public VelocityEngine ( Properties p )
throws
CTOR that invokes an init(String), initializing the engine using the Properties specified
Parameters
TypeNameDescription
Properties p name of properties to init with
Exceptions
Exception No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
Method Detail
addProperty
public void addProperty ( String key, Object value )
Add a Velocity Runtime property.
Parameters
TypeNameDescription
String key No description provided.
Object value No description provided.
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
clearProperty
public void clearProperty ( String key )
Clear a Velocity Runtime property.
Parameters
TypeNameDescription
String key of property to clear
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
debug
public void debug ( Object message )
No description provided.
Deprecated Use getLog() and call warn() on it.
Parameters
TypeNameDescription
Object message No description provided.
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
error
public void error ( Object message )
No description provided.
Deprecated Use getLog() and call warn() on it.
Parameters
TypeNameDescription
Object message No description provided.
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
evaluate
public boolean evaluate ( Context context, Writer out, String logTag, String instring )
throws
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
TypeNameDescription
Context context context to use in rendering input string
Writer out Writer in which to render the output
String logTag string to be used as the template name for log messages in case of error
String instring input string containing the VTL to be rendered
Exceptions
ParseErrorException No description provided.
MethodInvocationException No description provided.
ResourceNotFoundException No description provided.
IOException No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
evaluate
public boolean evaluate ( Context context, Writer writer, String logTag, InputStream instream )
throws
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.
Deprecated Use evaluate(Context, Writer, String, Reader)
Parameters
TypeNameDescription
Context context context to use in rendering input string
Writer writer Writer in which to render the output
String logTag string to be used as the template name for log messages in case of error
InputStream instream input stream containing the VTL to be rendered
Exceptions
ParseErrorException No description provided.
MethodInvocationException No description provided.
ResourceNotFoundException No description provided.
IOException No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
evaluate
public boolean evaluate ( Context context, Writer writer, String logTag, Reader reader )
throws
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.
Since: Velocity v
Parameters
TypeNameDescription
Context context context to use in rendering input string
Writer writer Writer in which to render the output
String logTag string to be used as the template name for log messages in case of error
Reader reader Reader containing the VTL to be rendered
Exceptions
ParseErrorException No description provided.
MethodInvocationException No description provided.
ResourceNotFoundException No description provided.
IOException No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
getApplicationAttribute
public Object getApplicationAttribute ( Object key )

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 LogChutes.

Parameters
TypeNameDescription
Object key object 'name' under which the object is stored
Wiki javadoc Use textile entry format.
Add your comments here.
getLog
public Log getLog ( )
Returns a convenient Log instance that wraps the current LogChute. Use this to log error messages. It has the usual methods you'd expect.
Wiki javadoc Use textile entry format.
Add your comments here.
getProperty
public Object getProperty ( String key )
Get a Velocity Runtime property.
Parameters
TypeNameDescription
String key property to retrieve
Wiki javadoc Use textile entry format.
Add your comments here.
getTemplate
public Template getTemplate ( String name )
throws
Returns a Template from the Velocity resource management system.
Parameters
TypeNameDescription
String name The file name of the desired template.
Exceptions
ResourceNotFoundException if template not found from any available source.
ParseErrorException if template cannot be parsed due to syntax (or other) error.
Exception if an error occurs in template initialization
Wiki javadoc Use textile entry format.
Add your comments here.
getTemplate
public Template getTemplate ( String name, String encoding )
throws
Returns a Template from the Velocity resource management system.
Since: Velocity v
Parameters
TypeNameDescription
String name The file name of the desired template.
String encoding The character encoding to use for the template.
Exceptions
ResourceNotFoundException if template not found from any available source.
ParseErrorException if template cannot be parsed due to syntax (or other) error.
Exception if an error occurs in template initialization
Wiki javadoc Use textile entry format.
Add your comments here.
info
public void info ( Object message )
No description provided.
Deprecated Use getLog() and call warn() on it.
Parameters
TypeNameDescription
Object message No description provided.
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
init
public void init ( )
throws
initialize the Velocity runtime engine, using the default properties of the Velocity distribution
Returns void No description provided.
Exceptions
Exception No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
init
public void init ( String propsFilename )
throws
initialize the Velocity runtime engine, using default properties plus the properties in the properties file passed in as the arg
Parameters
TypeNameDescription
String propsFilename file containing properties to use to initialize the Velocity runtime
Returns void No description provided.
Exceptions
Exception No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
init
public void init ( Properties p )
throws
initialize the Velocity runtime engine, using default properties plus the properties in the passed in java.util.Properties object
Parameters
TypeNameDescription
Properties p Proprties object containing initialization properties
Returns void No description provided.
Exceptions
Exception No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
invokeVelocimacro
public boolean invokeVelocimacro ( String vmName, String logTag, String [] params, Context context, Writer writer )
throws
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
TypeNameDescription
String vmName name of Velocimacro to call
String logTag string to be used for template name in case of error
String [] params args used to invoke Velocimacro. In context key format : eg "foo","bar" (rather than "$foo","$bar")
Context context Context object containing data/objects used for rendering.
Writer writer Writer for output stream
Exceptions
Exception No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
mergeTemplate
public boolean mergeTemplate ( String templateName, Context context, Writer writer )
throws
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
TypeNameDescription
String templateName name of template to be used in merge
Context context filled context to be used in merge
Writer writer writer to write template into
Exceptions
ResourceNotFoundException No description provided.
ParseErrorException No description provided.
MethodInvocationException No description provided.
Exception * @deprecated Use mergeTemplate(String, String, Context, Writer)
Wiki javadoc Use textile entry format.
Add your comments here.
mergeTemplate
public boolean mergeTemplate ( String templateName, String encoding, Context context, Writer writer )
throws
merges a template and puts the rendered stream into the writer
Since: Velocity v
Parameters
TypeNameDescription
String templateName name of template to be used in merge
String encoding encoding used in template
Context context filled context to be used in merge
Writer writer writer to write template into
Exceptions
ResourceNotFoundException No description provided.
ParseErrorException No description provided.
MethodInvocationException No description provided.
Exception No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
resourceExists
public boolean resourceExists ( String resourceName )
Determines if a resource 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
TypeNameDescription
String resourceName name of the resource to search for
Wiki javadoc Use textile entry format.
Add your comments here.
setApplicationAttribute
public 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. This allows communication between the application environment and custom pluggable components of the Velocity engine, such as ResourceLoaders and LogChutes.

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
TypeNameDescription
Object key object 'name' under which the object is stored
Object value object to store under this key
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
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
TypeNameDescription
ExtendedProperties configuration No description provided.
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
setProperty
public void setProperty ( String key, Object value )
Set a Velocity Runtime property.
Parameters
TypeNameDescription
String key No description provided.
Object value No description provided.
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
templateExists
public boolean templateExists ( String resourceName )
No description provided.
Deprecated Use resourceExists(String) instead.
Parameters
TypeNameDescription
String resourceName No description provided.
See also
Wiki javadoc Use textile entry format.
Add your comments here.
warn
public void warn ( Object message )
No description provided.
Deprecated Use getLog() and call warn() on it.
Parameters
TypeNameDescription
Object message No description provided.
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.