Package org.apache.velocity.tools.view

Class VelocityView

  • public class VelocityView
extends ViewToolManager

    The class provides the following features:

    • renders Velocity templates
    • provides support for an auto-loaded, configurable toolbox
    • provides transparent access to the servlet request attributes, servlet session attributes and servlet context attributes by auto-searching them
    • logs to the logging facility of the servlet API

    VelocityView supports the following configuration parameters in web.xml:

    org.apache.velocity.tools
    Path and name of the toolbox configuration file. The path must be relative to the web application root directory. If this parameter is not found, the servlet will check for a toolbox file at '/WEB-INF/tools.xml'.
    org.apache.velocity.properties
    Path and name of the Velocity configuration file. The path must be relative to the web application root directory. If this parameter is not present, Velocity will check for a properties file at '/WEB-INF/velocity.properties'. If no file is found there, then Velocity is initialized with the settings in the classpath at 'org.apache.velocity.tools.view.velocity.properties'.
    Version:
    $Id: VelocityView.java 511959 2007-02-26 19:24:39Z nbubna $
    Author:
    Dave Bryson, Jon S. Stevens, Gabe Sidler, Geir Magnusson Jr., Kent Johnson, Daniel Rall, Nathan Bubna

    • Field Detail

      • SERVLET_CONTEXT_KEY

        public static final String SERVLET_CONTEXT_KEY
        Key used to access the ServletContext in the Velocity application attributes.

      • DEFAULT_CONTENT_TYPE

        public static final String DEFAULT_CONTENT_TYPE
        The default content type for the response
        See Also:
        Constant Field Values

      • DEFAULT_OUTPUT_ENCODING

        public static final String DEFAULT_OUTPUT_ENCODING
        Default encoding for the output stream
        See Also:
        Constant Field Values

      • TOOLS_KEY

        public static final String TOOLS_KEY
        Key used to access the toolbox configuration file path from the Servlet or webapp init parameters ("org.apache.velocity.tools") or to access a live FactoryConfiguration previously placed in the ServletContext attributes.
        See Also:
        Constant Field Values

      • USER_TOOLS_PATH

        public static final String USER_TOOLS_PATH
        Default toolbox configuration file path. If no alternate value for this is specified, the servlet will look here.
        See Also:
        Constant Field Values

      • DEFAULT_PROPERTIES_PATH

        public static final String DEFAULT_PROPERTIES_PATH
        Default Runtime properties.
        See Also:
        Constant Field Values

      • PROPERTIES_KEY

        public static final String PROPERTIES_KEY
        This is the string that is looked for when getInitParameter is called ("org.apache.velocity.properties").
        See Also:
        Constant Field Values

      • USER_PROPERTIES_PATH

        public static final String USER_PROPERTIES_PATH
        Default velocity properties file path. If no alternate value for this is specified, the servlet will look here.
        See Also:
        Constant Field Values

      • LOAD_DEFAULTS_KEY

        public static final String LOAD_DEFAULTS_KEY
        Controls loading of available default tool configurations provided by VelocityTools. The default behavior is conditional; if DEPRECATION_SUPPORT_MODE_KEY has not been set to false and there is an old toolbox.xml configuration present, then the defaults will not be loaded unless you explicitly set this property to true in your init params. If there is no toolbox.xml and/or the deprecation support is turned off, then the default tools will be loaded automatically unless you explicitly set this property to false in your init params.
        See Also:
        Constant Field Values

      • CLEAN_CONFIGURATION_KEY

        public static final String CLEAN_CONFIGURATION_KEY
        Controls removal of tools or data with invalid configurations before initialization is finished. The default is false; set to true to turn this feature on.
        See Also:
        Constant Field Values

      • USER_OVERWRITE_KEY

        public static final String USER_OVERWRITE_KEY
        Controls whether or not templates can overwrite tool and servlet API variables in the local context. The default is true; set to false to prevent overwriting of any tool variables.
        See Also:
        Constant Field Values

      • DEPRECATION_SUPPORT_MODE_KEY

        public static final String DEPRECATION_SUPPORT_MODE_KEY
        Controls support for deprecated tools and configuration. The default is true; set to false to turn off support for deprecated tools and configuration.
        See Also:
        Constant Field Values

    • Constructor Detail

      • VelocityView

        public VelocityView​(javax.servlet.ServletConfig config)

      • VelocityView

        public VelocityView​(javax.servlet.FilterConfig config)

      • VelocityView

        public VelocityView​(javax.servlet.ServletContext context)

      • VelocityView

        public VelocityView​(JeeConfig config)

    • Method Detail

      • setDeprecationSupportMode

        @Deprecated
protected final void setDeprecationSupportMode​(boolean support)
        Deprecated.

      • setVelocityEngine

        public void setVelocityEngine​(org.apache.velocity.app.VelocityEngine engine)
        Overrides super class to ensure engine is not set to null.
        Overrides:
        setVelocityEngine in class ToolManager

      • getDefaultContentType

        public String getDefaultContentType()
        Returns the configured default Content-Type.

      • setDefaultContentType

        public void setDefaultContentType​(String type)
        Sets the configured default Content-Type.

      • getProperty

        protected String getProperty​(String key,
                             String alternate)
        Simplifies process of getting a property from VelocityEngine, because the VelocityEngine interface sucks compared to the singleton's. Use of this method assumes that init(JeeConfig,VelocityEngine) has already been called.

      • init

        protected void init​(JeeConfig config)

        Initializes ToolboxFactory, VelocityEngine, and sets default encoding for processing requests.

        NOTE: If no charset is specified in the default.contentType property (in your velocity.properties) and you have specified an output.encoding property, then that will be used as the charset for the default content-type of pages served by this servlet.

        Parameters:
        config - servlet configuation

      • init

        protected void init​(JeeConfig config,
                    org.apache.velocity.app.VelocityEngine velocity)
        Initializes the Velocity runtime, first calling loadConfiguration(JeeConfig) to get a org.apache.commons.collections.ExtendedProperties of configuration information and then calling velocityEngine.init(). Override this to do anything to the environment before the initialization of the singleton takes place, or to initialize the singleton in other ways.
        Parameters:
        config - servlet configuration parameters

      • configure

        protected void configure​(JeeConfig config,
                         org.apache.velocity.app.VelocityEngine velocity)

      • configure

        protected void configure​(JeeConfig config,
                         ToolboxFactory factory)
        Here's the configuration lookup/loading order:
        1. If deprecationSupportMode is true:
          1. Config file optionally specified by org.apache.velocity.toolbox init-param (servlet or servletContext)
          2. If none, config file optionally at /WEB-INF/toolbox.xml (deprecated conventional location)
        2. If no old toolbox or loadDefaults is true, ConfigurationUtils.getDefaultTools()
        3. ConfigurationUtils.getAutoLoaded()(false)
        4. Config file optionally specified by servletContext org.apache.velocity.tools init-param
        5. Config file optionally at /WEB-INF/tools.xml (new conventional location)
        6. Config file optionally specified by servlet org.apache.velocity.tools init-param
        Remember that as these configurations are added on top of each other, the newer values will always override the older ones. Also, once they are all loaded, this method can "clean" your configuration of all invalid tool, toolbox or data configurations if you set the org.apache.velocity.tools.cleanConfiguration init-param to true in either your servlet or servletContext init-params.

      • getDeprecatedConfig

        @Deprecated
protected FactoryConfiguration getDeprecatedConfig​(JeeConfig config)
        Deprecated.
        First tries to find a path to a toolbox under the deprecated org.apache.velocity.toolbox key. If found, it tries to load the configuration there and will blow up if there is no config file there. If not found, it looks for a config file at /WEB-INF/toolbox.xml (the deprecated default location) and tries to load it if found.

      • getInputStream

        protected InputStream getInputStream​(String path,
                                     boolean required)

      • getProperties

        protected org.apache.commons.collections.ExtendedProperties getProperties​(String path)

      • getProperties

        protected org.apache.commons.collections.ExtendedProperties getProperties​(String path,
                                                                          boolean required)

      • setEncoding

        protected void setEncoding​(JeeConfig config)

      • render

        public org.apache.velocity.context.Context render​(javax.servlet.http.HttpServletRequest request,
                                                  javax.servlet.http.HttpServletResponse response)
                                           throws IOException
        Parameters:
        request - HttpServletRequest object containing client request
        response - HttpServletResponse object for the response
        Returns:
        the Context prepared and used to perform the rendering to allow proper cleanup afterward
        Throws:
        IOException

      • render

        public org.apache.velocity.context.Context render​(javax.servlet.http.HttpServletRequest request,
                                                  Writer out)
                                           throws IOException
        Throws:
        IOException

      • createContext

        public ViewToolContext createContext​(javax.servlet.http.HttpServletRequest request,
                                     javax.servlet.http.HttpServletResponse response)

        Creates and returns an initialized Velocity context.

        A new context of class ViewToolContext is created and initialized.
        Overrides:
        createContext in class ViewToolManager
        Parameters:
        request - servlet request from client
        response - servlet reponse to client

      • getTemplate

        public org.apache.velocity.Template getTemplate​(javax.servlet.http.HttpServletRequest request)

        Gets the requested template.

        Parameters:
        request - client request
        Returns:
        Velocity Template object or null

      • getTemplate

        public org.apache.velocity.Template getTemplate​(javax.servlet.http.HttpServletRequest request,
                                                javax.servlet.http.HttpServletResponse response)

      • getTemplate

        public org.apache.velocity.Template getTemplate​(String name)
        Retrieves the requested template.
        Parameters:
        name - The file name of the template to retrieve relative to the template root.
        Returns:
        The requested template.
        Throws:
        org.apache.velocity.exception.ResourceNotFoundException - if template not found from any available source.
        ParseErrorException - if template cannot be parsed due to syntax (or other) error.

      • getTemplate

        public org.apache.velocity.Template getTemplate​(String name,
                                                String encoding)
        Retrieves the requested template with the specified character encoding.
        Parameters:
        name - The file name of the template to retrieve relative to the template root.
        encoding - the character encoding of the template
        Returns:
        The requested template.
        Throws:
        org.apache.velocity.exception.ResourceNotFoundException - if template not found from any available source.
        ParseErrorException - if template cannot be parsed due to syntax (or other) error.