Package org.springframework.web.servlet.view.velocity

Class VelocityView

java.lang.Object
org.springframework.context.support.ApplicationObjectSupport
org.springframework.web.context.support.WebApplicationObjectSupport
org.springframework.web.servlet.view.AbstractView
org.springframework.web.servlet.view.AbstractUrlBasedView
org.springframework.web.servlet.view.AbstractTemplateView
org.springframework.web.servlet.view.velocity.VelocityView
All Implemented Interfaces:
org.springframework.beans.factory.Aware, org.springframework.beans.factory.BeanNameAware, org.springframework.beans.factory.InitializingBean, org.springframework.context.ApplicationContextAware, org.springframework.web.context.ServletContextAware, org.springframework.web.servlet.View
public class VelocityView extends org.springframework.web.servlet.view.AbstractTemplateView
View using the Velocity template engine.

Exposes the following JavaBean properties:

  • url: the location of the Velocity template to be wrapped, relative to the Velocity resource loader path (see VelocityConfigurer).
  • encoding (optional, default is determined by Velocity configuration): the encoding of the Velocity template file
  • velocityFormatterAttribute (optional, default=null): the name of the VelocityFormatter helper object to expose in the Velocity context of this view, or null if not needed. VelocityFormatter is part of standard Velocity.
  • dateToolAttribute (optional, default=null): the name of the DateTool helper object to expose in the Velocity context of this view, or null if not needed. DateTool is part of Velocity Tools.
  • numberToolAttribute (optional, default=null): the name of the NumberTool helper object to expose in the Velocity context of this view, or null if not needed. NumberTool is part of Velocity Tools.
  • cacheTemplate (optional, default=false): whether or not the Velocity template should be cached. It should normally be true in production, but setting this to false enables us to modify Velocity templates without restarting the application (similar to JSPs). Note that this is a minor optimization only, as Velocity itself caches templates in a modification-aware fashion.

Depends on a VelocityConfig object such as VelocityConfigurer being accessible in the current web application context, with any bean name. Alternatively, you can set the VelocityEngine object as bean property.

Note: Spring 3.0's VelocityView requires Velocity 1.4 or higher, and optionally Velocity Tools 1.1 or higher (depending on the use of DateTool and/or NumberTool).

Author:
Rod Johnson, Juergen Hoeller, Dave Syer
See Also:

  • Field Summary

    Fields inherited from class org.springframework.web.servlet.view.AbstractTemplateView

    SPRING_MACRO_REQUEST_CONTEXT_ATTRIBUTE

    Fields inherited from class org.springframework.web.servlet.view.AbstractView

    DEFAULT_CONTENT_TYPE

    Fields inherited from class org.springframework.context.support.ApplicationObjectSupport

    logger

    Fields inherited from interface org.springframework.web.servlet.View

    PATH_VARIABLES, RESPONSE_STATUS_ATTRIBUTE, SELECTED_CONTENT_TYPE

  • Constructor Summary

    Constructors
    Constructor
    Description
    VelocityView()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    protected org.apache.velocity.app.VelocityEngine
    autodetectVelocityEngine()
    Autodetect a VelocityEngine via the ApplicationContext.
    boolean
    checkResource(Locale locale)
    Check that the Velocity template used for this view exists and is valid.
    protected org.apache.velocity.context.Context
    createVelocityContext(Map<String,Object> model)
    Create a Velocity Context instance for the given model, to be passed to the template for merging.
    protected org.apache.velocity.context.Context
    createVelocityContext(Map<String,Object> model, jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response)
    Create a Velocity Context instance for the given model, to be passed to the template for merging.
    protected void
    doRender(org.apache.velocity.context.Context context, jakarta.servlet.http.HttpServletResponse response)
    Render the Velocity view to the given response, using the given Velocity context which contains the complete template model to use.
    protected void
    exposeHelpers(Map<String,Object> model, jakarta.servlet.http.HttpServletRequest request)
    Expose helpers unique to each rendering operation.
    protected void
    exposeHelpers(org.apache.velocity.context.Context velocityContext, jakarta.servlet.http.HttpServletRequest request)
    Expose helpers unique to each rendering operation.
    protected void
    exposeHelpers(org.apache.velocity.context.Context velocityContext, jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response)
    Expose helpers unique to each rendering operation.
    protected String
    getEncoding()
    Return the encoding for the Velocity template.
    protected org.apache.velocity.Template
    getTemplate()
    Retrieve the Velocity template to be rendered by this view.
    protected org.apache.velocity.Template
    getTemplate(String name)
    Retrieve the Velocity template specified by the given name, using the encoding specified by the "encoding" bean property.
    protected org.apache.velocity.app.VelocityEngine
    getVelocityEngine()
    Return the VelocityEngine used by this view.
    protected void
    initApplicationContext()
    Invoked on startup.
    protected boolean
    isCacheTemplate()
    Return whether the Velocity template should be cached.
    protected void
    mergeTemplate(org.apache.velocity.Template template, org.apache.velocity.context.Context context, jakarta.servlet.http.HttpServletResponse response)
    Merge the template with the context.
    protected void
    renderMergedTemplateModel(Map<String,Object> model, jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response)
    Process the model map by merging it with the Velocity template.
    void
    setCacheTemplate(boolean cacheTemplate)
    Set whether the Velocity template should be cached.
    void
    setEncoding(String encoding)
    Set the encoding of the Velocity template file.
    void
    setVelocityEngine(org.apache.velocity.app.VelocityEngine velocityEngine)
    Set the VelocityEngine to be used by this view.

    Methods inherited from class org.springframework.web.servlet.view.AbstractTemplateView

    applyContentType, renderMergedOutputModel, setAllowRequestOverride, setAllowSessionOverride, setExposeRequestAttributes, setExposeSessionAttributes, setExposeSpringMacroHelpers

    Methods inherited from class org.springframework.web.servlet.view.AbstractUrlBasedView

    afterPropertiesSet, getUrl, isUrlRequired, setUrl, toString

    Methods inherited from class org.springframework.web.servlet.view.AbstractView

    addStaticAttribute, createMergedOutputModel, createRequestContext, createTemporaryOutputStream, exposeModelAsRequestAttributes, formatViewName, generatesDownloadContent, getAttributesMap, getBeanName, getContentType, getRequestContextAttribute, getRequestToExpose, getStaticAttributes, isExposePathVariables, prepareResponse, render, setAttributes, setAttributesCSV, setAttributesMap, setBeanName, setContentType, setExposeContextBeansAsAttributes, setExposedContextBeanNames, setExposePathVariables, setRequestContextAttribute, setResponseContentType, writeToResponse

    Methods inherited from class org.springframework.web.context.support.WebApplicationObjectSupport

    getServletContext, getTempDir, getWebApplicationContext, initApplicationContext, initServletContext, isContextRequired, setServletContext

    Methods inherited from class org.springframework.context.support.ApplicationObjectSupport

    getApplicationContext, getMessageSourceAccessor, obtainApplicationContext, requiredContextClass, setApplicationContext

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • VelocityView

      public VelocityView()

  • Method Details

    • setEncoding

      public void setEncoding(String encoding)
      Set the encoding of the Velocity template file. Default is determined by the VelocityEngine: "ISO-8859-1" if not specified otherwise.

      Specify the encoding in the VelocityEngine rather than per template if all your templates share a common encoding.

    • getEncoding

      protected String getEncoding()
      Return the encoding for the Velocity template.

    • setCacheTemplate

      public void setCacheTemplate(boolean cacheTemplate)
      Set whether the Velocity template should be cached. Default is "false". It should normally be true in production, but setting this to false enables us to modify Velocity templates without restarting the application (similar to JSPs).

      Note that this is a minor optimization only, as Velocity itself caches templates in a modification-aware fashion.

    • isCacheTemplate

      protected boolean isCacheTemplate()
      Return whether the Velocity template should be cached.

    • setVelocityEngine

      public void setVelocityEngine(org.apache.velocity.app.VelocityEngine velocityEngine)
      Set the VelocityEngine to be used by this view.

      If this is not set, the default lookup will occur: A single VelocityConfig is expected in the current web application context, with any bean name.

      See Also:

    • getVelocityEngine

      protected org.apache.velocity.app.VelocityEngine getVelocityEngine()
      Return the VelocityEngine used by this view.

    • initApplicationContext

      protected void initApplicationContext() throws org.springframework.beans.BeansException
      Invoked on startup. Looks for a single VelocityConfig bean to find the relevant VelocityEngine for this factory.
      Overrides:
      initApplicationContext in class org.springframework.context.support.ApplicationObjectSupport
      Throws:
      org.springframework.beans.BeansException

    • autodetectVelocityEngine

      protected org.apache.velocity.app.VelocityEngine autodetectVelocityEngine() throws org.springframework.beans.BeansException
      Autodetect a VelocityEngine via the ApplicationContext. Called if no explicit VelocityEngine has been specified.
      Returns:
      the VelocityEngine to use for VelocityViews
      Throws:
      org.springframework.beans.BeansException - if no VelocityEngine could be found
      See Also:

    • checkResource

      public boolean checkResource(Locale locale) throws Exception
      Check that the Velocity template used for this view exists and is valid.

      Can be overridden to customize the behavior, for example in case of multiple templates to be rendered into a single view.

      Overrides:
      checkResource in class org.springframework.web.servlet.view.AbstractUrlBasedView
      Throws:
      Exception

    • renderMergedTemplateModel

      protected void renderMergedTemplateModel(Map<String,Object> model, jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response) throws Exception
      Process the model map by merging it with the Velocity template. Output is directed to the servlet response.

      This method can be overridden if custom behavior is needed.

      Specified by:
      renderMergedTemplateModel in class org.springframework.web.servlet.view.AbstractTemplateView
      Throws:
      Exception

    • exposeHelpers

      protected void exposeHelpers(Map<String,Object> model, jakarta.servlet.http.HttpServletRequest request) throws Exception
      Expose helpers unique to each rendering operation. This is necessary so that different rendering operations can't overwrite each other's formats etc.

      Called by renderMergedTemplateModel. The default implementation is empty. This method can be overridden to add custom helpers to the model.

      Parameters:
      model - the model that will be passed to the template for merging
      request - current HTTP request
      Throws:
      Exception - if there's a fatal error while we're adding model attributes
      See Also:

    • createVelocityContext

      protected org.apache.velocity.context.Context createVelocityContext(Map<String,Object> model, jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response) throws Exception
      Create a Velocity Context instance for the given model, to be passed to the template for merging.

      The default implementation delegates to createVelocityContext(Map). Can be overridden for a special context class, for example ChainedContext which is part of the view package of Velocity Tools. ChainedContext is needed for initialization of ViewTool instances.

      Throws:
      Exception

    • createVelocityContext

      protected org.apache.velocity.context.Context createVelocityContext(Map<String,Object> model) throws Exception
      Create a Velocity Context instance for the given model, to be passed to the template for merging.

      Default implementation creates an instance of Velocity's VelocityContext implementation class.

      Parameters:
      model - the model Map, containing the model attributes to be exposed to the view
      Returns:
      the Velocity Context
      Throws:
      Exception - if there's a fatal error while creating the context
      See Also:
      • VelocityContext

    • exposeHelpers

      protected void exposeHelpers(org.apache.velocity.context.Context velocityContext, jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response) throws Exception
      Expose helpers unique to each rendering operation. This is necessary so that different rendering operations can't overwrite each other's formats etc.

      Called by renderMergedTemplateModel. Default implementation delegates to exposeHelpers(velocityContext, request). This method can be overridden to add special tools to the context, needing the servlet response to initialize (see Velocity Tools, for example LinkTool and ViewTool/ChainedContext).

      Parameters:
      velocityContext - Velocity context that will be passed to the template
      request - current HTTP request
      response - current HTTP response
      Throws:
      Exception - if there's a fatal error while we're adding model attributes
      See Also:

    • exposeHelpers

      protected void exposeHelpers(org.apache.velocity.context.Context velocityContext, jakarta.servlet.http.HttpServletRequest request) throws Exception
      Expose helpers unique to each rendering operation. This is necessary so that different rendering operations can't overwrite each other's formats etc.

      Default implementation is empty. This method can be overridden to add custom helpers to the Velocity context.

      Parameters:
      velocityContext - Velocity context that will be passed to the template
      request - current HTTP request
      Throws:
      Exception - if there's a fatal error while we're adding model attributes
      See Also:

    • doRender

      protected void doRender(org.apache.velocity.context.Context context, jakarta.servlet.http.HttpServletResponse response) throws Exception
      Render the Velocity view to the given response, using the given Velocity context which contains the complete template model to use.

      The default implementation renders the template specified by the "url" bean property, retrieved via getTemplate. It delegates to the mergeTemplate method to merge the template instance with the given Velocity context.

      Can be overridden to customize the behavior, for example to render multiple templates into a single view.

      Parameters:
      context - the Velocity context to use for rendering
      response - servlet response (use this to get the OutputStream or Writer)
      Throws:
      Exception - if thrown by Velocity
      See Also:

    • getTemplate

      protected org.apache.velocity.Template getTemplate() throws Exception
      Retrieve the Velocity template to be rendered by this view.

      By default, the template specified by the "url" bean property will be retrieved: either returning a cached template instance or loading a fresh instance (according to the "cacheTemplate" bean property)

      Returns:
      the Velocity template to render
      Throws:
      Exception - if thrown by Velocity
      See Also:

    • getTemplate

      protected org.apache.velocity.Template getTemplate(String name) throws Exception
      Retrieve the Velocity template specified by the given name, using the encoding specified by the "encoding" bean property.

      Can be called by subclasses to retrieve a specific template, for example to render multiple templates into a single view.

      Parameters:
      name - the file name of the desired template
      Returns:
      the Velocity template
      Throws:
      Exception - if thrown by Velocity
      See Also:
      • VelocityEngine.getTemplate(java.lang.String)

    • mergeTemplate

      protected void mergeTemplate(org.apache.velocity.Template template, org.apache.velocity.context.Context context, jakarta.servlet.http.HttpServletResponse response) throws Exception
      Merge the template with the context. Can be overridden to customize the behavior.
      Parameters:
      template - the template to merge
      context - the Velocity context to use for rendering
      response - servlet response (use this to get the OutputStream or Writer)
      Throws:
      Exception - if thrown by Velocity
      See Also:
      • Template.merge(org.apache.velocity.context.Context, java.io.Writer)