org.springframework.web.servlet.view.freemarker
Class FreeMarkerView

java.lang.Object
  extended by org.springframework.context.support.ApplicationObjectSupport
      extended by org.springframework.web.context.support.WebApplicationObjectSupport
          extended by org.springframework.web.servlet.view.AbstractView
              extended by org.springframework.web.servlet.view.AbstractUrlBasedView
                  extended by org.springframework.web.servlet.view.AbstractTemplateView
                      extended by org.springframework.web.servlet.view.freemarker.FreeMarkerView
All Implemented Interfaces:
Aware, BeanNameAware, InitializingBean, ApplicationContextAware, ServletContextAware, View

public class FreeMarkerView
extends AbstractTemplateView

View using the FreeMarker template engine.

Exposes the following JavaBean properties:

Depends on a single FreeMarkerConfig object such as FreeMarkerConfigurer being accessible in the current web application context, with any bean name. Alternatively, you can set the FreeMarker Configuration object as bean property. See setConfiguration(freemarker.template.Configuration) for more details on the impacts of this approach.

Note: Spring's FreeMarker support requires FreeMarker 2.3 or higher.

Since:
03.03.2004
Author:
Darren Davison, Juergen Hoeller
See Also:
AbstractUrlBasedView.setUrl(java.lang.String), AbstractTemplateView.setExposeSpringMacroHelpers(boolean), setEncoding(java.lang.String), setConfiguration(freemarker.template.Configuration), FreeMarkerConfig, FreeMarkerConfigurer

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
 
Constructor Summary
FreeMarkerView()
           
 
Method Summary
protected  FreeMarkerConfig autodetectConfiguration()
          Autodetect a FreeMarkerConfig object via the ApplicationContext.
protected  SimpleHash buildTemplateModel(Map<String,Object> model, HttpServletRequest request, HttpServletResponse response)
          Build a FreeMarker template model for the given model Map.
 boolean checkResource(Locale locale)
          Check that the FreeMarker template used for this view exists and is valid.
protected  void doRender(Map<String,Object> model, HttpServletRequest request, HttpServletResponse response)
          Render the FreeMarker view to the given response, using the given model map which contains the complete template model to use.
protected  void exposeHelpers(Map<String,Object> model, HttpServletRequest request)
          Expose helpers unique to each rendering operation.
protected  Configuration getConfiguration()
          Return the FreeMarker configuration used by this view.
protected  String getEncoding()
          Return the encoding for the FreeMarker template.
protected  ObjectWrapper getObjectWrapper()
          Return the configured FreeMarker ObjectWrapper, or the default wrapper if none specified.
protected  Template getTemplate(Locale locale)
          Retrieve the FreeMarker template for the given locale, to be rendering by this view.
protected  Template getTemplate(String name, Locale locale)
          Retrieve the FreeMarker template specified by the given name, using the encoding specified by the "encoding" bean property.
protected  void initServletContext(ServletContext servletContext)
          Invoked on startup.
protected  void processTemplate(Template template, SimpleHash model, HttpServletResponse response)
          Process the FreeMarker template to the servlet response.
protected  void renderMergedTemplateModel(Map<String,Object> model, HttpServletRequest request, HttpServletResponse response)
          Process the model map by merging it with the FreeMarker template.
 void setConfiguration(Configuration configuration)
          Set the FreeMarker Configuration to be used by this view.
 void setEncoding(String encoding)
          Set the encoding of the FreeMarker template file.
 
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, generatesDownloadContent, getAttributesMap, getBeanName, getContentType, getRequestContextAttribute, getStaticAttributes, isExposePathVariables, prepareResponse, render, setAttributes, setAttributesCSV, setAttributesMap, setBeanName, setContentType, setExposePathVariables, setRequestContextAttribute, writeToResponse
 
Methods inherited from class org.springframework.web.context.support.WebApplicationObjectSupport
getServletContext, getTempDir, getWebApplicationContext, initApplicationContext, isContextRequired, setServletContext
 
Methods inherited from class org.springframework.context.support.ApplicationObjectSupport
getApplicationContext, getMessageSourceAccessor, initApplicationContext, requiredContextClass, setApplicationContext
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

FreeMarkerView

public FreeMarkerView()
Method Detail

setEncoding

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

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


getEncoding

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


setConfiguration

public void setConfiguration(Configuration configuration)
Set the FreeMarker Configuration to be used by this view.

If this is not set, the default lookup will occur: a single FreeMarkerConfig is expected in the current web application context, with any bean name. Note: using this method will cause a new instance of TaglibFactory to created for every single FreeMarkerView instance. This can be quite expensive in terms of memory and initial CPU usage. In production it is recommended that you use a FreeMarkerConfig which exposes a single shared TaglibFactory.


getConfiguration

protected Configuration getConfiguration()
Return the FreeMarker configuration used by this view.


initServletContext

protected void initServletContext(ServletContext servletContext)
                           throws BeansException
Invoked on startup. Looks for a single FreeMarkerConfig bean to find the relevant Configuration for this factory.

Checks that the template for the default Locale can be found: FreeMarker will check non-Locale-specific templates if a locale-specific one is not found.

Overrides:
initServletContext in class WebApplicationObjectSupport
Parameters:
servletContext - the ServletContext that this application object runs in (never null)
Throws:
BeansException
See Also:
TemplateCache.getTemplate(java.lang.String, java.util.Locale, java.lang.String, boolean)

autodetectConfiguration

protected FreeMarkerConfig autodetectConfiguration()
                                            throws BeansException
Autodetect a FreeMarkerConfig object via the ApplicationContext.

Returns:
the Configuration instance to use for FreeMarkerViews
Throws:
BeansException - if no Configuration instance could be found
See Also:
ApplicationObjectSupport.getApplicationContext(), setConfiguration(freemarker.template.Configuration)

getObjectWrapper

protected ObjectWrapper getObjectWrapper()
Return the configured FreeMarker ObjectWrapper, or the default wrapper if none specified.

See Also:
Configurable.getObjectWrapper()

checkResource

public boolean checkResource(Locale locale)
                      throws Exception
Check that the FreeMarker 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
Parameters:
locale - the desired Locale that we're looking for
Returns:
true if the resource exists (or is assumed to exist); false if we know that it does not exist
Throws:
Exception - if the resource exists but is invalid (e.g. could not be parsed)

renderMergedTemplateModel

protected void renderMergedTemplateModel(Map<String,Object> model,
                                         HttpServletRequest request,
                                         HttpServletResponse response)
                                  throws Exception
Process the model map by merging it with the FreeMarker 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 - combined output Map, with request attributes and session attributes merged into it if required
request - current HTTP request
response - current HTTP response
Throws:
Exception - if rendering failed

exposeHelpers

protected void exposeHelpers(Map<String,Object> model,
                             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 at merge time
request - current HTTP request
Throws:
Exception - if there's a fatal error while we're adding information to the context
See Also:
renderMergedTemplateModel(java.util.Map, javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)

doRender

protected void doRender(Map<String,Object> model,
                        HttpServletRequest request,
                        HttpServletResponse response)
                 throws Exception
Render the FreeMarker view to the given response, using the given model map 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 processTemplate method to merge the template instance with the given template model.

Adds the standard Freemarker hash models to the model: request parameters, request, session and application (ServletContext), as well as the JSP tag library hash model.

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

Parameters:
model - the model to use for rendering
request - current HTTP request
response - current servlet response
Throws:
IOException - if the template file could not be retrieved
Exception - if rendering failed
See Also:
AbstractUrlBasedView.setUrl(java.lang.String), RequestContextUtils.getLocale(javax.servlet.http.HttpServletRequest), getTemplate(java.util.Locale), processTemplate(freemarker.template.Template, freemarker.template.SimpleHash, javax.servlet.http.HttpServletResponse), FreemarkerServlet

buildTemplateModel

protected SimpleHash buildTemplateModel(Map<String,Object> model,
                                        HttpServletRequest request,
                                        HttpServletResponse response)
Build a FreeMarker template model for the given model Map.

The default implementation builds a AllHttpScopesHashModel.

Parameters:
model - the model to use for rendering
request - current HTTP request
response - current servlet response
Returns:
the FreeMarker template model, as a SimpleHash or subclass thereof

getTemplate

protected Template getTemplate(Locale locale)
                        throws IOException
Retrieve the FreeMarker template for the given locale, to be rendering by this view.

By default, the template specified by the "url" bean property will be retrieved.

Parameters:
locale - the current locale
Returns:
the FreeMarker template to render
Throws:
IOException - if the template file could not be retrieved
See Also:
AbstractUrlBasedView.setUrl(java.lang.String), getTemplate(String, java.util.Locale)

getTemplate

protected Template getTemplate(String name,
                               Locale locale)
                        throws IOException
Retrieve the FreeMarker 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
locale - the current locale
Returns:
the FreeMarker template
Throws:
IOException - if the template file could not be retrieved

processTemplate

protected void processTemplate(Template template,
                               SimpleHash model,
                               HttpServletResponse response)
                        throws IOException,
                               TemplateException
Process the FreeMarker template to the servlet response.

Can be overridden to customize the behavior.

Parameters:
template - the template to process
model - the model for the template
response - servlet response (use this to get the OutputStream or Writer)
Throws:
IOException - if the template file could not be retrieved
TemplateException - if thrown by FreeMarker
See Also:
Template.process(Object, java.io.Writer)