org.apache.velocity.app
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,v 1.11 2001/03/26 04:18:51 jvanzyl Exp $

Author:

Geir Magnusson Jr., Christoph Reck, Jason van Zyl

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

COUNTER_INITIAL_VALUE, COUNTER_NAME, DEBUG_PREFIX, DEFAULT_RUNTIME_DIRECTIVES, DEFAULT_RUNTIME_PROPERTIES, ERROR_PREFIX, ERRORMSG_END, ERRORMSG_START, FILE_RESOURCE_LOADER_CACHE, FILE_RESOURCE_LOADER_PATH, INFO_PREFIX, 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, PARSE_DIRECTIVE_MAXDEPTH, PARSER_POOL_SIZE, RESOURCE_LOADER, 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, TEMPLATE_ENCODING, UNKNOWN_PREFIX, VM_CONTEXT_LOCALSCOPE, VM_LIBRARY, VM_MESSAGES_ON, VM_PERM_ALLOW_INLINE, VM_PERM_ALLOW_INLINE_REPLACE_GLOBAL, VM_PERM_INLINE_LOCAL, WARN_PREFIX

Constructor Summary

Velocity()

Method Summary

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 boolean	evaluate(Context context, java.io.Writer writer, java.lang.String logTag, java.io.InputStream instream) Renders the input stream 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 java.lang.Object	getProperty(java.lang.String key) Get a Velocity Runtime property.
static Template	getTemplate(java.lang.String name) Returns a Template from the Velocity resource management system.
static void	init() initialize the Velocity runtime engine, using the default properties of the Velocity distribution
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
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
static boolean	invokeVelocimacro(java.lang.String vmName, java.lang.String namespace, 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.
static boolean	mergeTemplate(java.lang.String templateName, Context context, java.io.Writer writer) merges a template and puts the rendered stream into the writer
static void	setConfiguration(Configuration 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 templateName) Determines if a template is accessable via the currently configured resource loaders.

Methods inherited from class java.lang.Object

, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait

Constructor Detail

Velocity

public Velocity()

Method Detail

init

public static void init()
                 throws java.lang.Exception

initialize the Velocity runtime engine, using the default properties of the Velocity distribution

Returns:

true if successful, false otherwise

init

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

Returns:

true if successful, false otherwise. Check runtime log if false

init

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

Returns:

true if successful, false otherwise

setProperty

public static void setProperty(java.lang.String key,
                               java.lang.Object value)

Set a Velocity Runtime property.

Parameters:

String - key

Object - value

addProperty

public static void addProperty(java.lang.String key,
                               java.lang.Object value)

Add a Velocity Runtime property.

Parameters:

String - key

Object - value

clearProperty

public static void clearProperty(java.lang.String key)

Clear a Velocity Runtime property.

Parameters:

key - of property to clear

setConfiguration

public static void setConfiguration(Configuration configuration)

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

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,
                               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 static boolean evaluate(Context context,
                               java.io.Writer writer,
                               java.lang.String logTag,
                               java.io.InputStream instream)
                        throws ParseErrorException,
                               MethodInvocationException,
                               java.io.IOException

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

invokeVelocimacro

public static boolean invokeVelocimacro(java.lang.String vmName,
                                        java.lang.String namespace,
                                        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. Note : currently only accepts args to the VM if they are in the context.

Parameters:

vmName - name of Velocimacro to call

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

getTemplate

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

templateExists

public static boolean templateExists(java.lang.String templateName)

Determines if a template is accessable via the currently configured resource loaders.

The assumption is that the caller will use it at some point so that the current implementation, while displaying lazyness and sloth, isn't entirely unreasonable.

Parameters:

templateName - name of the temlpate to search for

Returns:

true if found, false otherwise