Package net.shibboleth.shared.spring.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
net.shibboleth.shared.spring.velocity.VelocityView

All Implemented Interfaces:
  `Aware`, `BeanNameAware`, `InitializingBean`, `ApplicationContextAware`, `ServletContextAware`, `View`

public class VelocityView extends 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.
- 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.

Note: Spring 3.0's VelocityView requires Velocity 1.4 or higher.

Since:
  6.0.0

## Field Summary

Fields
Modifier and Type
Field
Description
`private boolean`
`cacheTemplate`
Caching flag.
`private String`
`encoding`
Template encoding.
`private org.apache.velocity.Template`
`template`
The template.
`private org.apache.velocity.app.VelocityEngine`
`velocityEngine`
Velocity engine.

### 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, HttpServletRequest request, 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, HttpServletResponse response)`
Render the Velocity view to the given response, using the given Velocity context which contains the complete template model to use.
`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 t, org.apache.velocity.context.Context context, HttpServletResponse response)`
Merge the template with the context.
`protected void`
`renderMergedTemplateModel(Map<String,Object> model, HttpServletRequest request, HttpServletResponse response)`
Process the model map by merging it with the Velocity template.
`void`
`setCacheTemplate(boolean flag)`
Set whether the Velocity template should be cached (default is "false").
`void`
`setEncoding(String enc)`
Set the encoding of the Velocity template file.
`void`
`setVelocityEngine(org.apache.velocity.app.VelocityEngine engine)`
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`

## Field Details

### encoding

@Nullable private String encoding
Template encoding.

### cacheTemplate

private boolean cacheTemplate
Caching flag.

### velocityEngine

@Nullable private org.apache.velocity.app.VelocityEngine velocityEngine
Velocity engine.

### template

@Nullable private org.apache.velocity.Template template
The template.

## Constructor Details

### VelocityView

public VelocityView()

## Method Details

### setEncoding

public void setEncoding(@Nullable String enc)
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.

Parameters:
  `enc` - encoding

### getEncoding

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

Returns:
  encoding

### setCacheTemplate

public void setCacheTemplate(boolean flag)
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.

Parameters:
  `flag` - flag to set

### isCacheTemplate

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

Returns:
  whether template should be cached

### setVelocityEngine

public void setVelocityEngine(@Nullable org.apache.velocity.app.VelocityEngine engine)
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.

Parameters:
  `engine` - velocity engine

### getVelocityEngine

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

Returns:
  engine

### initApplicationContext

protected void initApplicationContext() throws BeansException
Invoked on startup. Looks for a single `VelocityConfig` bean to find the relevant VelocityEngine for this factory.

Overrides:
  `initApplicationContext` in class `ApplicationObjectSupport`
Throws:
  `BeansException`

### autodetectVelocityEngine

@Nonnull protected org.apache.velocity.app.VelocityEngine autodetectVelocityEngine() throws BeansException
Autodetect a VelocityEngine via the ApplicationContext.

Called if no explicit VelocityEngine has been specified.

Returns:
  the VelocityEngine to use
Throws:
  `BeansException` - if no VelocityEngine could be found

### checkResource

public boolean checkResource(@Nullable 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 `AbstractUrlBasedView`
Throws:
  `Exception`

### renderMergedTemplateModel

protected void renderMergedTemplateModel(@Nonnull @NullableElements Map<String,Object> model, @Nonnull HttpServletRequest request, @Nonnull 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 `AbstractTemplateView`
Parameters:
  `model` - the model Map, containing the model attributes to be exposed to the view
  `request` - current HTTP request
  `response` - current HTTP response
Throws:
  `Exception` - if there's a fatal error while rendering the model

### createVelocityContext

@Nonnull protected org.apache.velocity.context.Context createVelocityContext(@Nullable @NullableElements Map<String,Object> model, @Nonnull HttpServletRequest request, @Nonnull 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.

Parameters:
  `model` - the model Map, containing the model attributes to be exposed to the view
  `request` - current HTTP request
  `response` - current HTTP response
Returns:
  the Velocity Context
Throws:
  `Exception` - if there's a fatal error while creating the context

### createVelocityContext

@Nonnull protected org.apache.velocity.context.Context createVelocityContext(@Nullable @NullableElements 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

### doRender

protected void doRender(@Nonnull org.apache.velocity.context.Context context, @Nonnull 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

### getTemplate

@Nonnull 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

### getTemplate

@Nonnull 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

### mergeTemplate

protected void mergeTemplate(@Nonnull org.apache.velocity.Template t, @Nonnull org.apache.velocity.context.Context context, @Nonnull HttpServletResponse response) throws Exception
Merge the template with the context.

Parameters:
  `t` - 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