Velocity (Velocity 1.4 API)
Keywords: org.apache.velocity.app.Velocity class

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.30.4.1 2004/03/03 23:22:53 geirm Exp $
Author:
  Geir Magnusson Jr., Christoph Reck, Jason van Zyl

Field Summary

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, UBERSPECT_CLASSNAME, 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
`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 void` | `debug(java.lang.Object message)` Log a debug message.
`static void` | `error(java.lang.Object message)` Log an error message.
`static 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 )`
`static 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.
`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 Template` | `getTemplate(java.lang.String name, java.lang.String encoding)` Returns a `Template` from the Velocity resource management system.
`static void` | `info(java.lang.Object message)` Log an info message.
`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 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.
`static boolean` | `mergeTemplate(java.lang.String templateName, Context context, java.io.Writer writer)` Deprecated. Use `mergeTemplate( String templateName, String encoding, Context context, Writer writer )`
`static 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
`static boolean` | `resourceExists(java.lang.String resourceName)` Determines whether a resource is accessable via the currently configured resource loaders.
`static 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.
`static void` | `setConfiguration(Configuration configuration)` Deprecated. Use `setExtendedProperties( ExtendedProperties )`
`static void` | `setExtendedProperties(org.apache.commons.collections.ExtendedProperties 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 resourceName)` Deprecated. Use resourceExists(String) instead.
`static void` | `warn(java.lang.Object message)` Log a warning message.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, 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

  Throws:
    `java.lang.Exception`

### 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
  Throws:
    `java.lang.Exception`

### 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
  Throws:
    `java.lang.Exception`

### setProperty

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

  Set a Velocity Runtime property.

### addProperty

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

  Add a Velocity Runtime property.

### 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)

  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.

### setExtendedProperties

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

### 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,
                                   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
  Throws:
    `ParseErrorException`
    `MethodInvocationException`
    `ResourceNotFoundException`
    `java.io.IOException`

### evaluate

    public static 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
    `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
  Throws:
    `ParseErrorException`
    `MethodInvocationException`
    `ResourceNotFoundException`
    `java.io.IOException`

### evaluate

    public static 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
    `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
  Throws:
    `ParseErrorException`
    `MethodInvocationException`
    `ResourceNotFoundException`
    `java.io.IOException`
  Since:
    Velocity v1.1

### invokeVelocimacro

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

  Deprecated. Use `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
    `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.
  Throws:
    `ResourceNotFoundException`
    `ParseErrorException`
    `MethodInvocationException`
    `java.lang.Exception`

### mergeTemplate

    public static 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
  Throws:
    `ResourceNotFoundException`
    `ParseErrorException`
    `MethodInvocationException`
    `java.lang.Exception`
  Since:
    Velocity v1.1

### 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

### getTemplate

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

### resourceExists

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

### warn

    public static void warn(java.lang.Object message)

  Log a warning message.

### info

    public static void info(java.lang.Object message)

  Log an info message.

### error

    public static void error(java.lang.Object message)

  Log an error message.

### debug

    public static void debug(java.lang.Object message)

  Log a debug message.

### setApplicationAttribute

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

### templateExists

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

  Deprecated. Use resourceExists(String) instead.

  See Also:
    `resourceExists(String)`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2002 Apache Software Foundation. All Rights Reserved.