org.apache.velocity.app

Class Velocity

public class Velocity extends Object implements RuntimeConstants

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

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,v 1.30.4.1 2004/03/03 23:22:53 geirm Exp $

Author: Geir Magnusson Jr. Christoph Reck Jason van Zyl

Method Summary
static voidaddProperty(String key, Object value)
Add a Velocity Runtime property.
static voidclearProperty(String key)
Clear a Velocity Runtime property.
static voiddebug(Object message)
Log a debug message.
static voiderror(Object message)
Log an error message.
static booleanevaluate(Context context, Writer out, String logTag, String instring)
renders the input string using the context into the output writer.
static booleanevaluate(Context context, Writer writer, String logTag, InputStream instream)
Renders the input stream using the context into the output writer.
static booleanevaluate(Context context, Writer writer, String logTag, Reader reader)
Renders the input reader using the context into the output writer.
static ObjectgetProperty(String key)
Get a Velocity Runtime property.
static TemplategetTemplate(String name)
Returns a Template from the Velocity resource management system.
static TemplategetTemplate(String name, String encoding)
Returns a Template from the Velocity resource management system.
static voidinfo(Object message)
Log an info message.
static voidinit()
initialize the Velocity runtime engine, using the default properties of the Velocity distribution
static voidinit(String propsFilename)
initialize the Velocity runtime engine, using default properties plus the properties in the properties file passed in as the arg
static voidinit(Properties p)
initialize the Velocity runtime engine, using default properties plus the properties in the passed in java.util.Properties object
static booleaninvokeVelocimacro(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.
static booleanmergeTemplate(String templateName, Context context, Writer writer)
merges a template and puts the rendered stream into the writer
static booleanmergeTemplate(String templateName, String encoding, Context context, Writer writer)
merges a template and puts the rendered stream into the writer
static booleanresourceExists(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.

static voidsetApplicationAttribute(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.

static voidsetConfiguration(Configuration configuration)
Set an entire configuration at once.
static voidsetExtendedProperties(ExtendedProperties configuration)
Set an entire configuration at once.
static voidsetProperty(String key, Object value)
Set a Velocity Runtime property.
static booleantemplateExists(String resourceName)
static voidwarn(Object message)
Log a warning message.

Method Detail

addProperty

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

Parameters: String key Object value

clearProperty

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

Parameters: key of property to clear

debug

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

Parameters: Object message to log

error

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

Parameters: Object message to log

evaluate

public static boolean evaluate(Context context, Writer out, String logTag, String instring)
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 static boolean evaluate(Context context, Writer writer, String logTag, InputStream instream)

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.

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

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

getTemplate

public static Template getTemplate(String name)
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. Exception if an error occurs in template initialization

getTemplate

public static Template getTemplate(String name, String encoding)
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. Exception if an error occurs in template initialization

Since: Velocity v1.1

info

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

Parameters: Object message to log

init

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

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 Proprties object containing initialization properties

invokeVelocimacro

public static 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. 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 static boolean mergeTemplate(String templateName, Context context, Writer writer)

Deprecated: Use Velocity

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.

mergeTemplate

public static boolean mergeTemplate(String templateName, String encoding, Context context, Writer writer)
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

resourceExists

public static boolean resourceExists(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.

setApplicationAttribute

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

Parameters: Configuration configuration

setExtendedProperties

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

setProperty

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

Parameters: String key Object value

templateExists

public static boolean templateExists(String resourceName)

Deprecated: Use resourceExists(String) instead.

See Also: resourceExists

warn

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

Parameters: Object message to log

Copyright B) 2002 Apache Software Foundation. All Rights Reserved.