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 Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String CLEAN_CONFIGURATION_KEY
      Controls removal of tools or data with invalid configurations before initialization is finished.
      static java.lang.String CONTENT_TYPE_KEY
      The HTTP content type context key.
      static java.lang.String DEFAULT_CONTENT_TYPE
      The default content type for the response
      static java.lang.String DEFAULT_OUTPUT_ENCODING
      Default encoding for the output stream
      static java.lang.String DEFAULT_PROPERTIES_PATH
      Default Runtime properties.
      static java.lang.String LOAD_DEFAULTS_KEY
      Controls loading of available default tool configurations provided by VelocityTools.
      static java.lang.String OUTPUT_ENCODING_KEY
      The HTTP output encoding.
      static java.lang.String PROPERTIES_KEY
      This is the string that is looked for when getInitParameter is called ("org.apache.velocity.properties").
      static java.lang.String SERVLET_CONTEXT_KEY
      Key used to access the ServletContext in the Velocity application attributes.
      static java.lang.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.
      static java.lang.String USER_OVERWRITE_KEY
      Controls whether or not templates can overwrite tool and servlet API variables in the local context.
      static java.lang.String USER_PROPERTIES_PATH
      Default velocity properties file path.
      static java.lang.String USER_TOOLS_PATH
      Default toolbox configuration file path.

      • Fields inherited from class org.apache.velocity.tools.ToolManager

        factory, log, velocity

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void configure​(JeeConfig config, org.apache.velocity.app.VelocityEngine velocity)  
      protected void configure​(JeeConfig config, org.apache.velocity.tools.ToolboxFactory factory)
      Here's the configuration lookup/loading order: If loadDefaults is true, ConfigurationUtils.getDefaultTools() Config file optionally specified by servletContext org.apache.velocity.tools init-param Config file optionally at /WEB-INF/tools.xml (conventional location) 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.
      ViewToolContext createContext​(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
      Creates and returns an initialized Velocity context.
      protected org.apache.velocity.tools.config.FactoryConfiguration getConfiguration​(java.lang.String path)  
      protected org.apache.velocity.tools.config.FactoryConfiguration getConfiguration​(java.lang.String path, boolean required)  
      java.lang.String getDefaultContentType()  
      protected org.apache.velocity.tools.config.FactoryConfiguration getDefaultToolsConfiguration()  
      protected java.io.InputStream getInputStream​(java.lang.String path, boolean required)  
      protected java.util.Properties getProperties​(java.lang.String path)  
      protected java.util.Properties getProperties​(java.lang.String path, boolean required)  
      protected java.lang.String getProperty​(java.lang.String key, java.lang.String alternate)
      Simplifies process of getting a property from VelocityEngine, because the VelocityEngine interface sucks compared to the singleton's.
      org.apache.velocity.Template getTemplate​(java.lang.String name)
      Retrieves the requested template.
      org.apache.velocity.Template getTemplate​(java.lang.String name, java.lang.String encoding)
      Retrieves the requested template with the specified character encoding.
      org.apache.velocity.Template getTemplate​(javax.servlet.http.HttpServletRequest request)
      Gets the requested template.
      protected void init​(JeeConfig config)
      Initializes ToolboxFactory, VelocityEngine, and sets default encoding for processing requests.
      protected void init​(JeeConfig config, org.apache.velocity.app.VelocityEngine velocity)
      Initializes the Velocity runtime, first calling loadConfiguration(JeeConfig) to get a java.util.Properties of configuration information and then calling velocityEngine.init().
      void merge​(org.apache.velocity.Template template, org.apache.velocity.context.Context context, java.io.Writer writer)
      Merges the template with the context.
      protected void performMerge​(org.apache.velocity.Template template, org.apache.velocity.context.Context context, java.io.Writer writer)
      This is here so developers may override it and gain access to the Writer which the template will be merged into.
      org.apache.velocity.context.Context render​(javax.servlet.http.HttpServletRequest request, java.io.Writer out)  
      org.apache.velocity.context.Context render​(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)  
      void setDefaultContentType​(java.lang.String type)
      Sets the configured default Content-Type.
      protected void setEncoding​(JeeConfig config)  
      void setVelocityEngine​(org.apache.velocity.app.VelocityEngine engine)
      Overrides super class to ensure engine is not set to null.

      • Methods inherited from class org.apache.velocity.tools.ToolManager

        configure, createContext, createToolbox, getApplicationToolbox, getLog, getRequestToolbox, getToolboxFactory, getUserCanOverwriteTools, getVelocityEngine, hasApplicationTools, hasRequestTools, hasTools, initLog, prepareContext, setToolboxFactory, setUserCanOverwriteTools

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • CONTENT_TYPE_KEY

        public static final java.lang.String CONTENT_TYPE_KEY
        The HTTP content type context key.
        See Also:
        Constant Field Values

      • OUTPUT_ENCODING_KEY

        public static final java.lang.String OUTPUT_ENCODING_KEY
        The HTTP output encoding.
        See Also:
        Constant Field Values

      • SERVLET_CONTEXT_KEY

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

      • DEFAULT_CONTENT_TYPE

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

      • DEFAULT_OUTPUT_ENCODING

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

      • TOOLS_KEY

        public static final java.lang.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 java.lang.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 java.lang.String DEFAULT_PROPERTIES_PATH
        Default Runtime properties.
        See Also:
        Constant Field Values

      • PROPERTIES_KEY

        public static final java.lang.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 java.lang.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 java.lang.String LOAD_DEFAULTS_KEY
        Controls loading of available default tool configurations provided by VelocityTools. The default is false.
        See Also:
        Constant Field Values

      • CLEAN_CONFIGURATION_KEY

        public static final java.lang.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 java.lang.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

    • 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

      • 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 org.apache.velocity.tools.ToolManager

      • getDefaultContentType

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

      • setDefaultContentType

        public void setDefaultContentType​(java.lang.String type)
        Sets the configured default Content-Type.
        Parameters:
        type - default content type

      • getProperty

        protected java.lang.String getProperty​(java.lang.String key,
                                       java.lang.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.
        Parameters:
        key - property key
        alternate - default value
        Returns:
        property value

      • 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 java.util.Properties 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
        velocity - VelocityEngine instance

      • configure

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

      • configure

        protected void configure​(JeeConfig config,
                         org.apache.velocity.tools.ToolboxFactory factory)
        Here's the configuration lookup/loading order:
        1. If loadDefaults is true, ConfigurationUtils.getDefaultTools()
        2. Config file optionally specified by servletContext org.apache.velocity.tools init-param
        3. Config file optionally at /WEB-INF/tools.xml (conventional location)
        4. 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.
        Parameters:
        config - configuration values container
        factory - toolbox factory instance

      • getDefaultToolsConfiguration

        protected org.apache.velocity.tools.config.FactoryConfiguration getDefaultToolsConfiguration()

      • getInputStream

        protected java.io.InputStream getInputStream​(java.lang.String path,
                                             boolean required)

      • getProperties

        protected java.util.Properties getProperties​(java.lang.String path)

      • getProperties

        protected java.util.Properties getProperties​(java.lang.String path,
                                             boolean required)

      • getConfiguration

        protected org.apache.velocity.tools.config.FactoryConfiguration getConfiguration​(java.lang.String path)

      • getConfiguration

        protected org.apache.velocity.tools.config.FactoryConfiguration getConfiguration​(java.lang.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 java.io.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:
        java.io.IOException - if thrown by underling code

      • render

        public org.apache.velocity.context.Context render​(javax.servlet.http.HttpServletRequest request,
                                                  java.io.Writer out)
                                           throws java.io.IOException
        Throws:
        java.io.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
        Returns:
        newly created context

      • 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​(java.lang.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.
        org.apache.velocity.exception.ParseErrorException - if template cannot be parsed due to syntax (or other) error.

      • getTemplate

        public org.apache.velocity.Template getTemplate​(java.lang.String name,
                                                java.lang.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.
        org.apache.velocity.exception.ParseErrorException - if template cannot be parsed due to syntax (or other) error.

      • merge

        public void merge​(org.apache.velocity.Template template,
                  org.apache.velocity.context.Context context,
                  java.io.Writer writer)
           throws java.io.IOException
        Merges the template with the context. Only override this if you really, really really need to. (And don't call us with questions if it breaks :)
        Parameters:
        template - template being rendered
        context - Context created by the createContext(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)
        writer - into which the content is rendered
        Throws:
        java.io.IOException - if thrown by underling code

      • performMerge

        protected void performMerge​(org.apache.velocity.Template template,
                            org.apache.velocity.context.Context context,
                            java.io.Writer writer)
                     throws java.io.IOException
        This is here so developers may override it and gain access to the Writer which the template will be merged into. See VELTOOLS-7 for discussion of this.
        Parameters:
        template - template object returned by the handleRequest() method
        context - Context created by the createContext(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)
        writer - a VelocityWriter that the template is merged into
        Throws:
        java.io.IOException - if thrown by underling code