Package org.apache.velocity.app

Class VelocityEngine

  • All Implemented Interfaces:
    DeprecatedRuntimeConstants, RuntimeConstants
    public class VelocityEngine
extends 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.

    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 probably won't function in the way you intend, so it is strongly recommended that you call an init() method yourself if you use the default constructor.

    Version:
    $Id$

    • Constructor Detail

      • VelocityEngine

        public VelocityEngine()
        Init-less CTOR

      • VelocityEngine

        public VelocityEngine​(String propsFilename)
        Construct a VelocityEngine with the initial properties defined in the file propsFilename
        Parameters:
        propsFilename - properties filename

      • VelocityEngine

        public VelocityEngine​(Properties p)
        Construct a VelocityEngine instance with the specified initial properties.
        Parameters:
        p - properties

    • Method Detail

      • init

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

      • reset

        public void reset()
        Resets the instance, so Velocity can be re-initialized again.
        Since:
        2.0.0

      • init

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

      • setProperty

        public void setProperty​(String key,
                        Object value)
        Set a Velocity Runtime property.
        Parameters:
        key -
        value -

      • addProperty

        public void addProperty​(String key,
                        Object value)
        Add a Velocity Runtime property.
        Parameters:
        key -
        value -

      • clearProperty

        public void clearProperty​(String key)
        Clear a Velocity Runtime property.
        Parameters:
        key - of property to clear

      • setProperties

        public void setProperties​(Properties configuration)
        Set an entire configuration at once from a Properties configuration
        Parameters:
        configuration -
        Since:
        2.0

      • setProperties

        public void setProperties​(String propsFilename)
        Set an entire configuration at once from a named properties file
        Parameters:
        propsFilename - properties filename
        Since:
        2.1

      • getProperty

        public 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

      • evaluate

        public boolean evaluate​(Context context,
                        Writer out,
                        String logTag,
                        String instring)
                 throws ParseErrorException,
                        MethodInvocationException,
                        ResourceNotFoundException
        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 - The template could not be parsed.
        MethodInvocationException - A method on a context object could not be invoked.
        ResourceNotFoundException - A referenced resource could not be loaded.

      • evaluate

        public boolean evaluate​(Context context,
                        Writer writer,
                        String logTag,
                        Reader reader)
                 throws ParseErrorException,
                        MethodInvocationException,
                        ResourceNotFoundException
        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
        writer - 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
        Throws:
        ParseErrorException - The template could not be parsed.
        MethodInvocationException - A method on a context object could not be invoked.
        ResourceNotFoundException - A referenced resource could not be loaded.
        Since:
        Velocity v1.1

      • invokeVelocimacro

        public boolean invokeVelocimacro​(String vmName,
                                 String logTag,
                                 String[] params,
                                 Context context,
                                 Writer writer)
        Invokes a currently registered Velocimacro with the params 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. if null, the vmName will be used
        params - keys for args used to invoke Velocimacro, in java format rather than VTL (eg "foo" or "bar" rather than "$foo" or "$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.

      • resourceExists

        public boolean resourceExists​(String resourceName)
        Determines if a resource is accessible 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 laziness and sloth, and the author has been flogged.
        Parameters:
        resourceName - name of the resource to search for
        Returns:
        true if found, false otherwise
        Since:
        1.5

      • getLog

        public org.slf4j.Logger getLog()
        Returns the current slf4j logger. Its namespace defaults to org.apache.velocity if it hasn't been configured using the property runtime.log.name or the property runtime.log.instance.
        Returns:
        A Logger object.
        Since:
        1.5

      • 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 Loggers.

        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:
        key - object 'name' under which the object is stored
        value - object to store under this key

      • 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 Loggers.

        Parameters:
        key - object 'name' under which the object is stored
        Returns:
        value object to store under this key
        Since:
        1.5

      • removeDirective

        public void removeDirective​(String name)
        Remove a directive.
        Parameters:
        name - name of the directive.

      • loadDirective

        public void loadDirective​(String directiveClass)
        Instantiates and loads the directive with some basic checks.
        Parameters:
        directiveClass - classname of directive to load