Class FreemarkerServlet
- java.lang.Object
-
- javax.servlet.GenericServlet
-
- javax.servlet.http.HttpServlet
-
- freemarker.ext.servlet.FreemarkerServlet
-
- All Implemented Interfaces:
Serializable
,javax.servlet.Servlet
,javax.servlet.ServletConfig
public class FreemarkerServlet extends javax.servlet.http.HttpServlet
FreeMarker MVC View servlet that can be used similarly to JSP views. That is, you put the variables to expose into HTTP servlet request attributes, then forward to an FTL file (instead of to a JSP file) that's mapped to this servet (usually via the<url-pattern>*.ftl<url-pattern>
). See web.xml example (and more) in the FreeMarker Manual!Main features
- It makes all request, request parameters, session, and servlet context attributes available to templates through
Request
,RequestParameters
,Session
, andApplication
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 writeattrName
, and if no such variable was created in the template, it will search the variable inRequest
, and then inSession
, and finally inApplication
. - It creates a variable with name
JspTaglibs
that can be used to load JSP taglibs. For example:
<#assign dt=JspTaglibs["http://displaytag.sf.net"]>
or<#assign tiles=JspTaglibs["/WEB-INF/struts-tiles.tld"]>
. - A custom directive named
include_page
allows you to include the output of another servlet resource from your servlet container, just as if you usedServletRequest.getRequestDispatcher(path).include()
:<@include_page path="/myWebapp/somePage.jsp"/>
. You can also pass parameters to the newly included page by passing a hash namedparams
:<@include_page path="/myWebapp/somePage.jsp" params= lang: "en", q="5"}/>
. By default, the request parameters of the original request (the one being processed by FreemarkerServlet) are also inherited by the include. You can explicitly control this inheritance using theinherit_params
parameter:<@include_page path="/myWebapp/somePage.jsp" params={lang: "en", q="5"} inherit_params=false/>
.
Supported
init-param
-s- "TemplatePath": Specifies the location of the templates. By default, this is
interpreted as a
ServletContext
reasource path, which practically means a web application directory relative path, or aWEB-INF/lib/*.jar/META-INF/resources
-relative path (note that this last didn't work properly before FreeMarker 2.3.23).
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 withclasspath:
, like in classpath:com/example/templates, to indicate that you want to load templates from the specified package accessible through the Thread Context Class Loader of the thread that initializes this servlet.
Ifincompatible_improvements
is set to 2.3.22 (or higher), you can specify multiple comma separated locations inside square brackets, like:[ WEB-INF/templates, classpath:com/example/myapp/templates ]
. This internally creates aMultiTemplateLoader
. Note again that ifincompatible_improvements
isn't set to at least 2.3.22, the initial[
has no special meaning, and so this feature is unavailable.
Any of the above can have a?setting(name=value, ...)
postfix to set the JavaBeans properties of theTemplateLoader
created. For example,/templates?settings(attemptFileAccess=false, URLConnectionUsesCaches=true)
callsWebappTemplateLoader.setAttemptFileAccess(boolean)
andWebappTemplateLoader.setURLConnectionUsesCaches(Boolean)
to tune theWebappTemplateLoader
. For backward compatibility (not recommended!), you can use theclass://
prefix, like in class://com/example/templates format, which is similar toclasspath:
, except that it uses the defining class loader of this servlet's class. This can cause template not found errors, if that class (infreemarer.jar
usually) is not local to the web application, while the templates are.
The default value is class:// (that is, the root of the class hierarchy), which is not recommended anymore, and should be overwritten with the init-param. - "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.
- "BufferSize": Sets the size of the output buffer in bytes, or if "KB" or
"MB" is written after the number (like
<param-value>256 KB</param-value>
) then in kilobytes or megabytes. This corresponds toServletResponse.setBufferSize(int)
. If theHttpServletResponse
state doesn't allow changing the buffer size, it will silently do nothing. If this init param isn't specified, then the buffer size is not set byFreemarkerServlet
in the HTTP response, which usually means that the default buffer size of the servlet container will be used. - "ExceptionOnMissingTemplate" (since 2.3.22): If
false
(default, but not recommended), if a template is requested that's missing, this servlet responses with a HTTP 404 "Not found" error, and only logs the problem with debug level. Iftrue
(recommended), the servlet will log the issue with error level, then throws an exception that bubbles up to the servlet container, which usually then creates a HTTP 500 "Internal server error" response (and maybe logs the event into the container log). See "Error handling" later for more! - "MetaInfTldSources" (since 2.3.22): Comma separated list of items, each
is either "webInfPerLibJars", or "classpath"
optionally followed by colon and a regular expression, or "clear". For example
<param-value>classpath:.*myoverride.*\.jar$, webInfPerLibJars, classpath:.*taglib.*\.jar$</param-value>
, or<param-value>classpath</param-value>
. (Whitespace around the commas and list items will be ignored.) SeeTaglibFactory.setMetaInfTldSources(List)
for more information. Defaults to a list that contains "webInfPerLibJars" only (can be overridden withcreateDefaultMetaInfTldSources()
). Note that this can be also specified with the "org.freemarker.jsp.metaInfTldSources" system property. If both the init-param and the system property exists, the sources listed in the system property will be added after those specified by the init-param. This is where the special entry, "clear" comes handy, as it will remove all previous list items. (An intended usage of the system property is setting it toclear, classpath
in the Eclipse run configuration if you are running the application without putting the dependency jar-s intoWEB-INF/lib
.) Also, note that furtherclasspath:<pattern>
items are added automatically at the end of this list based on Jetty's"org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern"
servlet context attribute. - "ClasspathTlds" (since 2.3.22): Comma separated list of paths; see
TaglibFactory.setClasspathTlds(List)
. Whitespace around the list items will be ignored. Defaults to no paths (can be overidden withcreateDefaultClassPathTlds()
). Note that this can also be specified with the "org.freemarker.jsp.classpathTlds" system property. If both the init-param and the system property exists, the items listed in system property will be added after those specified by the init-param. - "Debug": Deprecated, has no effect since 2.3.22. (Earlier it has enabled/disabled sending debug-level log messages to the servlet container log, but this servlet doesn't log debug level messages into the servlet container log anymore, only into the FreeMarker log.)
- The following init-params are supported only for backward compatibility, and their usage is discouraged:
TemplateUpdateInterval
,DefaultEncoding
,ObjectWrapper
,TemplateExceptionHandler
. Instead, use init-params with the setting names documented atConfiguration.setSetting(String, String)
, such asobject_wrapper
. - Any other init-params will be interpreted as
Configuration
-level FreeMarker setting. See the possible names and values atConfiguration.setSetting(String, String)
.
Error handling
Notes:
- Logging below, where not said otherwise, always refers to logging with FreeMarker's logging facility (see
Logger
), under the "freemarker.servlet" category. - Throwing a
ServletException
to the servlet container is mentioned at a few places below. That in practice usually means HTTP 500 "Internal server error" response, and maybe a log entry in the servlet container's log.
Errors types:
- If the servlet initialization fails, the servlet won't be started as usual. The cause is usually logged with error level. When it isn't, check the servlet container's log.
- If the requested template doesn't exist, by default the servlet returns a HTTP 404 "Not found" response, and logs
the problem with debug level. Responding with HTTP 404 is how JSP behaves, but it's actually not a
recommended setting anymore. By setting "ExceptionOnMissingTemplate" init-param to
true
(recommended), it will instead log the problem with error level, then the servlet throwsServletException
to the servlet container (with the proper cause exception). After all, if the visited URL had an associated "action" but the template behind it is missing, that's an internal server error, not a wrong URL. -
If the template contains parsing errors, it will log it with error level, then the servlet throws
ServletException
to the servlet container (with the proper cause exception). -
If the template throws exception during its execution, and the value of the
template_exception_handler
init-param isrethrow
(recommended), it will log it with error level and then the servlet throwsServletException
to the servlet container (with the proper cause exception). But beware, the default value of thetemplate_exception_handler
init-param ishtml_debug
, which is for development only! Set it torethrow
for production. Thehtml_debug
(anddebug
) handlers will print error details to the page and then commit the HTTP response with response code 200 "OK", thus, the server wont be able roll back the response and send back an HTTP 500 page. This is so that the template developers will see the error without digging the logs.
- See Also:
- Serialized Form
-
-
Field Summary
Fields Modifier and Type Field Description protected boolean
debug
Deprecated.Not used anymore; to enable/disable debug logging, just set the logging level of the logging library used byLogger
.static String
INIT_PARAM_BUFFER_SIZE
Init-param name - see theFreemarkerServlet
class documentation about the init-params.static String
INIT_PARAM_CLASSPATH_TLDS
Init-param name - see theFreemarkerServlet
class documentation about the init-params.static String
INIT_PARAM_CONTENT_TYPE
Init-param name - see theFreemarkerServlet
class documentation about the init-params.static String
INIT_PARAM_EXCEPTION_ON_MISSING_TEMPLATE
Init-param name - see theFreemarkerServlet
class documentation about the init-params.static String
INIT_PARAM_META_INF_TLD_LOCATIONS
Init-param name - see theFreemarkerServlet
class documentation about the init-params.static String
INIT_PARAM_NO_CACHE
Init-param name - see theFreemarkerServlet
class documentation about the init-params.static String
INIT_PARAM_TEMPLATE_PATH
Init-param name - see theFreemarkerServlet
class documentation about the init-params.static String
KEY_APPLICATION
static String
KEY_APPLICATION_PRIVATE
static String
KEY_INCLUDE
static String
KEY_JSP_TAGLIBS
static String
KEY_REQUEST
static String
KEY_REQUEST_PARAMETERS
static String
KEY_REQUEST_PRIVATE
static String
KEY_SESSION
static String
META_INF_TLD_LOCATION_CLASSPATH
Used as part of the value of the "MetaInfTldSources" init-param.static String
META_INF_TLD_LOCATION_CLEAR
Used as part of the value of the "MetaInfTldSources" init-param.static String
META_INF_TLD_LOCATION_WEB_INF_PER_LIB_JARS
Used as part of the value of the "MetaInfTldSources" init-param.static long
serialVersionUID
static String
SYSTEM_PROPERTY_CLASSPATH_TLDS
When set, the items defined in it will be added after those coming from the "ClasspathTlds" init-param.static String
SYSTEM_PROPERTY_META_INF_TLD_SOURCES
When set, the items defined in it will be added after those coming from the "MetaInfTldSources" init-param.
-
Constructor Summary
Constructors Constructor Description FreemarkerServlet()
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description protected Configuration
createConfiguration()
Creates the FreeMarkerConfiguration
singleton and (when overidden) maybe sets its defaults.protected List
createDefaultClassPathTlds()
Creates the default of the "ClasspathTlds" init-param; if this init-param is specified, it will be appended after the default, not replace it.protected List
createDefaultMetaInfTldSources()
Creates the default of the "MetaInfTldSources" init-param; if this init-param is specified, it will completelly replace the default value.protected ObjectWrapper
createDefaultObjectWrapper()
Override this to specify what the defaultObjectWrapper
will be when theobject_wrapper
Servlet init-param wasn't specified.protected TemplateModel
createModel(ObjectWrapper objectWrapper, javax.servlet.ServletContext servletContext, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
protected ObjectWrapper
createObjectWrapper()
Called frominit()
to create theObjectWrapper
; to customzie this aspect, in most cases you should overridecreateDefaultObjectWrapper()
instead.protected HttpRequestParametersHashModel
createRequestParametersHashModel(javax.servlet.http.HttpServletRequest request)
protected TaglibFactory
createTaglibFactory(ObjectWrapper objectWrapper, javax.servlet.ServletContext servletContext)
Called to create theTaglibFactory
once per servlet context.protected TemplateLoader
createTemplateLoader(String templatePath)
Create the template loader.protected Locale
deduceLocale(String templatePath, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
Returns the locale used for theConfiguration.getTemplate(String, Locale)
call.void
doGet(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
void
doPost(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
protected Configuration
getConfiguration()
Returns theConfiguration
object used by this servlet.protected ObjectWrapper
getObjectWrapper()
Should be final; don't override it.protected String
getTemplatePath()
Deprecated.Not called by FreeMarker code, and there's no point to override this (unless to cause confusion).void
init()
Don't override this method to adjust FreeMarker settings! Override the protected methods for that, such ascreateConfiguration()
,createTemplateLoader(String)
,createDefaultObjectWrapper()
, etc.protected void
initializeServletContext(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
Called when servlet detects in a request processing that application-global (that is, ServletContext-specific) attributes are not yet set.protected void
initializeSession(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
Called when servlet detects in a request processing that session-global (that is, HttpSession-specific) attributes are not yet set.protected void
postTemplateProcess(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, Template template, TemplateModel data)
Called after the execution returns from template.process().protected boolean
preprocessRequest(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
Called as the first step in request processing, before the templating mechanism is put to work.protected boolean
preTemplateProcess(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, Template template, TemplateModel data)
Called before the execution is passed to template.process().protected String
requestUrlToTemplatePath(javax.servlet.http.HttpServletRequest request)
Maps the request URL to a template path (template name) that is passed toConfiguration.getTemplate(String, Locale)
.protected void
setConfigurationDefaults()
Sets the defaults of the configuration that are specific to theFreemarkerServlet
subclass.-
Methods inherited from class javax.servlet.http.HttpServlet
doDelete, doHead, doOptions, doPut, doTrace, getLastModified, service, service
-
-
-
-
Field Detail
-
serialVersionUID
public static final long serialVersionUID
- See Also:
- Constant Field Values
-
INIT_PARAM_TEMPLATE_PATH
public static final String INIT_PARAM_TEMPLATE_PATH
Init-param name - see theFreemarkerServlet
class documentation about the init-params. (This init-param has existed long before 2.3.22, but this constant was only added then.)- Since:
- 2.3.22
- See Also:
- Constant Field Values
-
INIT_PARAM_NO_CACHE
public static final String INIT_PARAM_NO_CACHE
Init-param name - see theFreemarkerServlet
class documentation about the init-params. (This init-param has existed long before 2.3.22, but this constant was only added then.)- Since:
- 2.3.22
- See Also:
- Constant Field Values
-
INIT_PARAM_CONTENT_TYPE
public static final String INIT_PARAM_CONTENT_TYPE
Init-param name - see theFreemarkerServlet
class documentation about the init-params. (This init-param has existed long before 2.3.22, but this constant was only added then.)- Since:
- 2.3.22
- See Also:
- Constant Field Values
-
INIT_PARAM_BUFFER_SIZE
public static final String INIT_PARAM_BUFFER_SIZE
Init-param name - see theFreemarkerServlet
class documentation about the init-params.- Since:
- 2.3.22
- See Also:
- Constant Field Values
-
INIT_PARAM_META_INF_TLD_LOCATIONS
public static final String INIT_PARAM_META_INF_TLD_LOCATIONS
Init-param name - see theFreemarkerServlet
class documentation about the init-params.- Since:
- 2.3.22
- See Also:
- Constant Field Values
-
INIT_PARAM_EXCEPTION_ON_MISSING_TEMPLATE
public static final String INIT_PARAM_EXCEPTION_ON_MISSING_TEMPLATE
Init-param name - see theFreemarkerServlet
class documentation about the init-params.- Since:
- 2.3.22
- See Also:
- Constant Field Values
-
INIT_PARAM_CLASSPATH_TLDS
public static final String INIT_PARAM_CLASSPATH_TLDS
Init-param name - see theFreemarkerServlet
class documentation about the init-params.- Since:
- 2.3.22
- See Also:
- Constant Field Values
-
SYSTEM_PROPERTY_META_INF_TLD_SOURCES
public static final String SYSTEM_PROPERTY_META_INF_TLD_SOURCES
When set, the items defined in it will be added after those coming from the "MetaInfTldSources" init-param. The value syntax is the same as of the init-param. Note that "clear" can be used to re-start the list, rather than continue it.- Since:
- 2.3.22
- See Also:
- Constant Field Values
-
SYSTEM_PROPERTY_CLASSPATH_TLDS
public static final String SYSTEM_PROPERTY_CLASSPATH_TLDS
When set, the items defined in it will be added after those coming from the "ClasspathTlds" init-param. The value syntax is the same as of the init-param.- Since:
- 2.3.22
- See Also:
- Constant Field Values
-
META_INF_TLD_LOCATION_WEB_INF_PER_LIB_JARS
public static final String META_INF_TLD_LOCATION_WEB_INF_PER_LIB_JARS
Used as part of the value of the "MetaInfTldSources" init-param.- Since:
- 2.3.22
- See Also:
- Constant Field Values
-
META_INF_TLD_LOCATION_CLASSPATH
public static final String META_INF_TLD_LOCATION_CLASSPATH
Used as part of the value of the "MetaInfTldSources" init-param.- Since:
- 2.3.22
- See Also:
- Constant Field Values
-
META_INF_TLD_LOCATION_CLEAR
public static final String META_INF_TLD_LOCATION_CLEAR
Used as part of the value of the "MetaInfTldSources" init-param.- Since:
- 2.3.22
- See Also:
- Constant Field Values
-
KEY_REQUEST
public static final String KEY_REQUEST
- See Also:
- Constant Field Values
-
KEY_INCLUDE
public static final String KEY_INCLUDE
- See Also:
- Constant Field Values
-
KEY_REQUEST_PRIVATE
public static final String KEY_REQUEST_PRIVATE
- See Also:
- Constant Field Values
-
KEY_REQUEST_PARAMETERS
public static final String KEY_REQUEST_PARAMETERS
- See Also:
- Constant Field Values
-
KEY_SESSION
public static final String KEY_SESSION
- See Also:
- Constant Field Values
-
KEY_APPLICATION
public static final String KEY_APPLICATION
- See Also:
- Constant Field Values
-
KEY_APPLICATION_PRIVATE
public static final String KEY_APPLICATION_PRIVATE
- See Also:
- Constant Field Values
-
KEY_JSP_TAGLIBS
public static final String KEY_JSP_TAGLIBS
- See Also:
- Constant Field Values
-
debug
protected boolean debug
Deprecated.Not used anymore; to enable/disable debug logging, just set the logging level of the logging library used byLogger
.
-
-
Method Detail
-
init
public void init() throws javax.servlet.ServletException
Don't override this method to adjust FreeMarker settings! Override the protected methods for that, such ascreateConfiguration()
,createTemplateLoader(String)
,createDefaultObjectWrapper()
, etc. Also note that lot of things can be changed with init-params instead of overriding methods, so if you override settings, usually you should only override their defaults.- Overrides:
init
in classjavax.servlet.GenericServlet
- Throws:
javax.servlet.ServletException
-
createTemplateLoader
protected TemplateLoader createTemplateLoader(String templatePath) throws IOException
Create the template loader. The default implementation will create aClassTemplateLoader
if the template path starts with"class://"
, aFileTemplateLoader
if the template path starts with"file://"
, and aWebappTemplateLoader
otherwise. Also, ifincompatible_improvements
is 2.3.22 or higher, it will create aMultiTemplateLoader
if the template path starts with"["
.- Parameters:
templatePath
- the template path to create a loader for- Returns:
- a newly created template loader
- Throws:
IOException
-
doGet
public void doGet(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) throws javax.servlet.ServletException, IOException
- Overrides:
doGet
in classjavax.servlet.http.HttpServlet
- Throws:
javax.servlet.ServletException
IOException
-
doPost
public void doPost(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) throws javax.servlet.ServletException, IOException
- Overrides:
doPost
in classjavax.servlet.http.HttpServlet
- Throws:
javax.servlet.ServletException
IOException
-
deduceLocale
protected Locale deduceLocale(String templatePath, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) throws javax.servlet.ServletException
Returns the locale used for theConfiguration.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.- Parameters:
templatePath
- The template path (templat name) as it will be passed toConfiguration.getTemplate(String)
. (Not to be confused with the servlet init-param of identical name; they aren't related.)- Throws:
javax.servlet.ServletException
- Can be thrown since 2.3.22, if the locale can't be deduced from the URL.
-
createModel
protected TemplateModel createModel(ObjectWrapper objectWrapper, javax.servlet.ServletContext servletContext, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) throws TemplateModelException
- Throws:
TemplateModelException
-
createTaglibFactory
protected TaglibFactory createTaglibFactory(ObjectWrapper objectWrapper, javax.servlet.ServletContext servletContext) throws TemplateModelException
Called to create theTaglibFactory
once per servlet context. The default implementation configures it based on the servlet-init parameters and various other environmental settings, so if you override this method, you should call super, then adjust the result.- Throws:
TemplateModelException
- Since:
- 2.3.22
-
createDefaultClassPathTlds
protected List createDefaultClassPathTlds()
Creates the default of the "ClasspathTlds" init-param; if this init-param is specified, it will be appended after the default, not replace it.The implementation in
FreemarkerServlet
returnsTaglibFactory.DEFAULT_CLASSPATH_TLDS
.
-
createDefaultMetaInfTldSources
protected List createDefaultMetaInfTldSources()
Creates the default of the "MetaInfTldSources" init-param; if this init-param is specified, it will completelly replace the default value.The implementation in
FreemarkerServlet
returnsTaglibFactory.DEFAULT_META_INF_TLD_SOURCES
.- Returns:
- A
List
ofTaglibFactory.MetaInfTldSource
-s; notnull
. - Since:
- 2.3.22
-
requestUrlToTemplatePath
protected String requestUrlToTemplatePath(javax.servlet.http.HttpServletRequest request) throws javax.servlet.ServletException
Maps the request URL to a template path (template name) that is passed toConfiguration.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.- Parameters:
request
- The currently processed HTTP request- Returns:
- The template path (template name); can't be
null
. This is what's passed toConfiguration.getTemplate(String)
later. (Not to be confused with thetemplatePath
servlet init-param of identical name; that basically specifies the "virtual file system" to which this will be relative to.) - Throws:
javax.servlet.ServletException
- Can be thrown since 2.3.22, if the template path can't be deduced from the URL.
-
preprocessRequest
protected boolean preprocessRequest(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) throws javax.servlet.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.- Parameters:
request
- the HTTP requestresponse
- the HTTP response- Returns:
- true to indicate this method has processed the request entirely, and that the further request processing should not take place.
- Throws:
javax.servlet.ServletException
IOException
-
createConfiguration
protected Configuration createConfiguration()
Creates the FreeMarkerConfiguration
singleton and (when overidden) maybe sets its defaults. Servlet init-params will be applied later, and thus can overwrite the settings specified here.By overriding this method you can set your preferred
Configuration
setting defaults, as only the settings for which an init-param was specified will be overwritten later. (Note thatFreemarkerServlet
also has its own defaults for a few settings, but since 2.3.22, the servlet detects if those settings were already set here and then it won't overwrite them.)The default implementation simply creates a new instance with
Configuration()
and returns it.
-
setConfigurationDefaults
protected void setConfigurationDefaults()
Sets the defaults of the configuration that are specific to theFreemarkerServlet
subclass. This is called after the common (wired in)FreemarkerServlet
setting defaults was set, also the
-
createObjectWrapper
protected ObjectWrapper createObjectWrapper()
Called frominit()
to create theObjectWrapper
; to customzie this aspect, in most cases you should overridecreateDefaultObjectWrapper()
instead. Overriding this method is necessary when you want to customize how theObjectWrapper
is created from the init-param values, or you want to do some post-processing (like checking) on the createdObjectWrapper
. To customize init-param interpretation, callGenericServlet.getInitParameter(String)
withConfigurable.OBJECT_WRAPPER_KEY
as argument, and see if it returns a value that you want to interpret yourself. If wasnull
or you don't want to interpret the value, fall back to the super method.The default implementation interprets the
object_wrapper
servlet init-param with callingConfigurable.setSetting(String, String)
(see valid values there), or if there's no such servlet init-param, then it callscreateDefaultObjectWrapper()
.- Returns:
- The
ObjectWrapper
that will be used for adapting request, session, and servlet context attributes toTemplateModel
-s, and also as the object wrapper setting ofConfiguration
.
-
createDefaultObjectWrapper
protected ObjectWrapper createDefaultObjectWrapper()
Override this to specify what the defaultObjectWrapper
will be when theobject_wrapper
Servlet init-param wasn't specified. Note that this is called bycreateConfiguration()
, and so if that was also overidden but improperly then this method might won't be ever called. Also note that if you set theobject_wrapper
increateConfiguration()
, then this won't be called, since then that has already specified the default.The default implementation calls
Configuration.getDefaultObjectWrapper(freemarker.template.Version)
. You should also pass in the version paramter when creating anObjectWrapper
that supports that. You can get the version by callinggetConfiguration()
and thenConfiguration.getIncompatibleImprovements()
.- Since:
- 2.3.22
-
getObjectWrapper
protected ObjectWrapper getObjectWrapper()
Should be final; don't override it. OverridecreateObjectWrapper()
instead.
-
getTemplatePath
protected final String getTemplatePath()
Deprecated.Not called by FreeMarker code, and there's no point to override this (unless to cause confusion).The value of theTemplatePath
init-param.null
if thetemplate_loader
setting was set in a customcreateConfiguration()
.
-
createRequestParametersHashModel
protected HttpRequestParametersHashModel createRequestParametersHashModel(javax.servlet.http.HttpServletRequest request)
-
initializeServletContext
protected void initializeServletContext(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) throws javax.servlet.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.- Parameters:
request
- the actual HTTP requestresponse
- the actual HTTP response- Throws:
javax.servlet.ServletException
IOException
-
initializeSession
protected void initializeSession(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) throws javax.servlet.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's not invoked when a replicated session is reinstantiated in another servlet container.- Parameters:
request
- the actual HTTP requestresponse
- the actual HTTP response- Throws:
javax.servlet.ServletException
IOException
-
preTemplateProcess
protected boolean preTemplateProcess(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, Template template, TemplateModel data) throws javax.servlet.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 rootExample: Expose the Serlvet context path as "baseDir" for all templates:
((SimpleHash) data).put("baseDir", request.getContextPath() + "/"); return true;
- Parameters:
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 anAllHttpScopesHashModel
(which is aSimpleHash
subclass). Thus, you can add new variables to the data-model with theSimpleHash.put(String, Object)
subclass) method.- Returns:
- true to process the template, false to suppress template processing.
- Throws:
javax.servlet.ServletException
IOException
-
postTemplateProcess
protected void postTemplateProcess(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, Template template, TemplateModel data) throws javax.servlet.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.- Parameters:
request
- the actual HTTP requestresponse
- the actual HTTP responsetemplate
- the template that was executeddata
- the data that was passed to the template- Throws:
javax.servlet.ServletException
IOException
-
getConfiguration
protected Configuration getConfiguration()
Returns theConfiguration
object used by this servlet. Please don't forget thatConfiguration
is not thread-safe when you modify it.
-
-