VelocityEngine (Velocity 1.4 API)
Keywords: org.apache.velocity.app.VelocityEngine 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 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.6.4.1 2004/03/03 23:22:53 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, 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
`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, 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

  Throws:
    `java.lang.Exception`

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

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

### setProperty

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

  Set a Velocity Runtime property.

### addProperty

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

  Add a Velocity Runtime property.

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

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

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

### 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
    `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 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 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
    `context` - Context object containing data/objects used for rendering.
    `writer` - Writer for output stream
  Returns:
    true if Velocimacro exists and successfully invoked, false otherwise.
  Throws:
    `java.lang.Exception`

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

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

### info

    public void info(java.lang.Object message)

  Log an info message.

### error

    public void error(java.lang.Object message)

  Log an error message.

### debug

    public void debug(java.lang.Object message)

  Log a debug message.

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

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.