This is a general-purpose FreeMarker view servlet.
The main features are:
- It makes all request, request parameters, session, and servlet
context attributes available to templates through
Request
,
RequestParameters
, Session
, and Application
variables.
- The scope variables are also available via automatic scope discovery. That is,
writing
Application.attrName
, Session.attrName
,
Request.attrName
is not mandatory; it's enough to write attrName
,
and if no such variable was created in the template, it will search the
variable in Request
, and then in Session
,
and finally in Application
.
- It creates a variable with name
JspTaglibs
, that can be used
to load JSP taglibs. For example:
<#assign tiles=JspTaglibs["/WEB-INF/struts-tiles.tld"]>
The servlet will rethrow the errors occurring during template processing,
wrapped into
ServletException
, except if the class name of the
class set by the
template_exception_handler
contains the
substring
"Debug"
. If it contains
"Debug"
, then it
is assumed that the template exception handler prints the error message to the
page, thus
FreemarkerServlet
will suppress the exception, and
logs the problem with the servlet logger
(
javax.servlet.GenericServlet.log(...)
).
Supported init-params are:
- TemplatePath specifies the location of the templates.
By default, this is interpreted as web application directory relative URI.
Alternatively, you can prepend it with file:// to indicate a literal
path in the file system (i.e. file:///var/www/project/templates/).
Note that three slashes were used to specify an absolute path.
Also, you can prepend it with class://path/to/template/package to
indicate that you want to load templates from the specified package
accessible through the classloader of the servlet.
Default value is class:// (that is, the root of the class hierarchy).
Note that this default is different than the default in FreeMarker 1.x, when
it defaulted /, that is to loading from the webapp root directory. - NoCache if set to true, generates headers in the response
that advise the HTTP client not to cache the returned page.
The default is false.
- ContentType if specified, response uses the specified
Content-type HTTP header. The value may include the charset (e.g.
"text/html; charset=ISO-8859-1"). If not specified, "text/html"
is used. If the charset is not specified in this init-param, then the charset
(encoding) of the actual template file will be used (in the response HTTP header
and for encoding the output stream). Note that this setting can be overridden
on a per-template basis by specifying a custom attribute named
content_type in the attributes parameter of the
<#ftl> directive.
- The following init-params are supported only for backward compatibility, and
their usage is discouraged: TemplateUpdateInterval, DefaultEncoding,
ObjectWrapper, TemplateExceptionHandler. Use setting init-params such as
object_wrapper instead.
- Any other init-param will be interpreted as
Configuration
level setting. See Configuration.setSetting(String,String)
KEY_APPLICATION
public static final String KEY_APPLICATION
KEY_APPLICATION_PRIVATE
public static final String KEY_APPLICATION_PRIVATE
KEY_JSP_TAGLIBS
public static final String KEY_JSP_TAGLIBS
KEY_REQUEST
public static final String KEY_REQUEST
KEY_REQUEST_PARAMETERS
public static final String KEY_REQUEST_PARAMETERS
KEY_REQUEST_PRIVATE
public static final String KEY_REQUEST_PRIVATE
KEY_SESSION
public static final String KEY_SESSION
debug
protected boolean debug
serialVersionUID
public static final long serialVersionUID
createConfiguration
protected Configuration createConfiguration()
This method is called from
init()
to create the
FreeMarker configuration object that this servlet will use
for template loading. This is a hook that allows you
to custom-configure the configuration object in a subclass.
The default implementation returns a new
Configuration
instance.
createObjectWrapper
protected ObjectWrapper createObjectWrapper()
This method is called from
init()
to create the
FreeMarker object wrapper object that this servlet will use
for adapting request, session, and servlet context attributes into
template models.. This is a hook that allows you
to custom-configure the wrapper object in a subclass.
The default implementation returns a wrapper that depends on the value
of
ObjectWrapper
init parameter. If
simple
is
specified,
ObjectWrapper.SIMPLE_WRAPPER
is used; if
jython
is specified,
JythonWrapper
is used. In
every other case
ObjectWrapper.DEFAULT_WRAPPER
is used.
createTemplateLoader
protected TemplateLoader createTemplateLoader(String templatePath)
throws IOException
templatePath
- the template path to create a loader for
- a newly created template loader
deduceLocale
protected Locale deduceLocale(String templatePath,
HttpServletRequest request,
HttpServletResponse response)
Returns the locale used for the
Configuration.getTemplate(String,Locale)
call.
The base implementation simply returns the locale setting of the
configuration. Override this method to provide different behaviour, i.e.
to use the locale indicated in the request.
doGet
public void doGet(HttpServletRequest request,
HttpServletResponse response)
throws ServletException,
IOException
doPost
public void doPost(HttpServletRequest request,
HttpServletResponse response)
throws ServletException,
IOException
getTemplatePath
protected final String getTemplatePath()
init
public void init()
throws ServletException
initializeServletContext
protected void initializeServletContext(HttpServletRequest request,
HttpServletResponse response)
throws ServletException,
IOException
Called when servlet detects in a request processing that
application-global (that is, ServletContext-specific) attributes are not yet
set.
This is a generic hook you might use in subclasses to perform a specific
action on first request in the context. By default it does nothing.
request
- the actual HTTP requestresponse
- the actual HTTP response
initializeSession
protected void initializeSession(HttpServletRequest request,
HttpServletResponse response)
throws ServletException,
IOException
Called when servlet detects in a request processing that session-global
(that is, HttpSession-specific) attributes are not yet set.
This is a generic hook you might use in subclasses to perform a specific
action on first request in the session. By default it does nothing. It
is only invoked on newly created sessions; it is not invoked when a
replicated session is reinstantiated in another servlet container.
request
- the actual HTTP requestresponse
- the actual HTTP response
postTemplateProcess
protected void postTemplateProcess(HttpServletRequest request,
HttpServletResponse response,
Template template,
TemplateModel data)
throws ServletException,
IOException
Called after the execution returns from template.process().
This is a generic hook you might use in subclasses to perform a specific
action after the template is processed. It will be invoked even if the
template processing throws an exception. By default does nothing.
request
- the actual HTTP requestresponse
- the actual HTTP responsetemplate
- the template that was executeddata
- the data that was passed to the template
preTemplateProcess
protected boolean preTemplateProcess(HttpServletRequest request,
HttpServletResponse response,
Template template,
TemplateModel data)
throws ServletException,
IOException
Called before the execution is passed to template.process().
This is a generic hook you might use in subclasses to perform a specific
action before the template is processed. By default does nothing.
A typical action to perform here is to inject application-specific
objects into the model root
Example: Expose the Serlvet context path as "baseDir" for all templates:
((SimpleHash) data).put("baseDir", request.getContextPath() + "/");
return true;
request
- the actual HTTP requestresponse
- the actual HTTP responsetemplate
- the template that will get executeddata
- the data that will be passed to the template. By default this will be
an AllHttpScopesHashModel
(which is a SimpleHash
subclass).
Thus, you can add new variables to the data-model with the
SimpleHash.put(String,Object)
subclass) method.
- true to process the template, false to suppress template processing.
preprocessRequest
protected boolean preprocessRequest(HttpServletRequest request,
HttpServletResponse response)
throws ServletException,
IOException
Called as the first step in request processing, before the templating mechanism
is put to work. By default does nothing and returns false. This method is
typically overridden to manage serving of non-template resources (i.e. images)
that reside in the template directory.
request
- the HTTP requestresponse
- the HTTP response
- true to indicate this method has processed the request entirely,
and that the further request processing should not take place.
requestUrlToTemplatePath
protected String requestUrlToTemplatePath(HttpServletRequest request)
Maps the request URL to a template path that is passed to
Configuration.getTemplate(String,Locale)
. You can override it
(i.e. to provide advanced rewriting capabilities), but you are strongly
encouraged to call the overridden method first, then only modify its
return value.
request
- the currently processed request
- a String representing the template path