freemarker.ext.servlet

Class FreemarkerServlet

java.lang.Object

javax.servlet.GenericServlet

javax.servlet.http.HttpServlet

freemarker.ext.servlet.FreemarkerServlet

All Implemented Interfaces:

java.io.Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig

public class FreemarkerServlet
extends javax.servlet.http.HttpServlet

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"]>
• A custom directive named include_page allows you to include the output of another servlet resource from your servlet container, just as if you used ServletRequest.getRequestDispatcher(path).include():
  <@include_page path="/myWebapp/somePage.jsp"/>. You can also pass parameters to the newly included page by passing a hash named 'params': <@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 the 'inherit_params' parameter: <@include_page path="/myWebapp/somePage.jsp" params={lang: "en", q="5"} inherit_params=false/>.

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(java.lang.String, java.lang.String)

Author:

Attila Szegedi

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	debug
static java.lang.String	KEY_APPLICATION
static java.lang.String	KEY_APPLICATION_PRIVATE
static java.lang.String	KEY_INCLUDE
static java.lang.String	KEY_JSP_TAGLIBS
static java.lang.String	KEY_REQUEST
static java.lang.String	KEY_REQUEST_PARAMETERS
static java.lang.String	KEY_REQUEST_PRIVATE
static java.lang.String	KEY_SESSION
static long	serialVersionUID

Constructor Summary

Constructors

Constructor and Description
FreemarkerServlet()

Method Summary

Methods

Modifier and Type	Method and Description
protected Configuration	createConfiguration() This method is called from init() to create the FreeMarker configuration object that this servlet will use for template loading.
protected TemplateModel	createModel(ObjectWrapper wrapper, javax.servlet.ServletContext servletContext, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
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..
protected HttpRequestParametersHashModel	createRequestParametersHashModel(javax.servlet.http.HttpServletRequest request)
protected TemplateLoader	createTemplateLoader(java.lang.String templatePath) Create the template loader.
protected java.util.Locale	deduceLocale(java.lang.String templatePath, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Returns the locale used for the Configuration.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 the Configuration object used by this servlet.
protected ObjectWrapper	getObjectWrapper()
protected java.lang.String	getTemplatePath()
void	init()
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 java.lang.String	requestUrlToTemplatePath(javax.servlet.http.HttpServletRequest request) Maps the request URL to a template path that is passed to Configuration.getTemplate(String, Locale).

Methods inherited from class javax.servlet.http.HttpServlet

doDelete, doHead, doOptions, doPut, doTrace, getLastModified, service, service

Methods inherited from class javax.servlet.GenericServlet

destroy, getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, log, log

Methods inherited from class java.lang.Object

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

Field Detail

serialVersionUID

public static final long serialVersionUID

See Also:

Constant Field Values

KEY_REQUEST

public static final java.lang.String KEY_REQUEST

See Also:

Constant Field Values

KEY_INCLUDE

public static final java.lang.String KEY_INCLUDE

See Also:

Constant Field Values

KEY_REQUEST_PRIVATE

public static final java.lang.String KEY_REQUEST_PRIVATE

See Also:

Constant Field Values

KEY_REQUEST_PARAMETERS

public static final java.lang.String KEY_REQUEST_PARAMETERS

See Also:

Constant Field Values

KEY_SESSION

public static final java.lang.String KEY_SESSION

See Also:

Constant Field Values

KEY_APPLICATION

public static final java.lang.String KEY_APPLICATION

See Also:

Constant Field Values

KEY_APPLICATION_PRIVATE

public static final java.lang.String KEY_APPLICATION_PRIVATE

See Also:

Constant Field Values

KEY_JSP_TAGLIBS

public static final java.lang.String KEY_JSP_TAGLIBS

See Also:

Constant Field Values

debug

protected boolean debug

Constructor Detail

FreemarkerServlet

public FreemarkerServlet()

Method Detail

init

public void init()
          throws javax.servlet.ServletException

Overrides:

init in class javax.servlet.GenericServlet

Throws:

javax.servlet.ServletException

createTemplateLoader

protected TemplateLoader createTemplateLoader(java.lang.String templatePath)
                                       throws java.io.IOException

Create the template loader. The default implementation will create a ClassTemplateLoader if the template path starts with "class://", a FileTemplateLoader if the template path starts with "file://", and a WebappTemplateLoader otherwise.

Parameters:

templatePath - the template path to create a loader for

Returns:

a newly created template loader

Throws:

java.io.IOException

doGet

public void doGet(javax.servlet.http.HttpServletRequest request,
         javax.servlet.http.HttpServletResponse response)
           throws javax.servlet.ServletException,
                  java.io.IOException

Overrides:

doGet in class javax.servlet.http.HttpServlet

Throws:

javax.servlet.ServletException

java.io.IOException

doPost

public void doPost(javax.servlet.http.HttpServletRequest request,
          javax.servlet.http.HttpServletResponse response)
            throws javax.servlet.ServletException,
                   java.io.IOException

Overrides:

doPost in class javax.servlet.http.HttpServlet

Throws:

javax.servlet.ServletException

java.io.IOException

deduceLocale

protected java.util.Locale deduceLocale(java.lang.String templatePath,
                            javax.servlet.http.HttpServletRequest request,
                            javax.servlet.http.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.

createModel

protected TemplateModel createModel(ObjectWrapper wrapper,
                        javax.servlet.ServletContext servletContext,
                        javax.servlet.http.HttpServletRequest request,
                        javax.servlet.http.HttpServletResponse response)
                             throws TemplateModelException

Throws:

TemplateModelException

requestUrlToTemplatePath

protected java.lang.String requestUrlToTemplatePath(javax.servlet.http.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.

Parameters:

request - the currently processed request

Returns:

a String representing the template path

preprocessRequest

protected boolean preprocessRequest(javax.servlet.http.HttpServletRequest request,
                        javax.servlet.http.HttpServletResponse response)
                             throws javax.servlet.ServletException,
                                    java.io.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 request

response - 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

java.io.IOException

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.

getObjectWrapper

protected ObjectWrapper getObjectWrapper()

getTemplatePath

protected final java.lang.String getTemplatePath()

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,
                                        java.io.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 request

response - the actual HTTP response

Throws:

javax.servlet.ServletException

java.io.IOException

initializeSession

protected void initializeSession(javax.servlet.http.HttpServletRequest request,
                     javax.servlet.http.HttpServletResponse response)
                          throws javax.servlet.ServletException,
                                 java.io.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 request

response - the actual HTTP response

Throws:

javax.servlet.ServletException

java.io.IOException

preTemplateProcess

protected boolean preTemplateProcess(javax.servlet.http.HttpServletRequest request,
                         javax.servlet.http.HttpServletResponse response,
                         Template template,
                         TemplateModel data)
                              throws javax.servlet.ServletException,
                                     java.io.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;

Parameters:

request - the actual HTTP request

response - the actual HTTP response

template - the template that will get executed

data - 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.

Returns:

true to process the template, false to suppress template processing.

Throws:

javax.servlet.ServletException

java.io.IOException

postTemplateProcess

protected void postTemplateProcess(javax.servlet.http.HttpServletRequest request,
                       javax.servlet.http.HttpServletResponse response,
                       Template template,
                       TemplateModel data)
                            throws javax.servlet.ServletException,
                                   java.io.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 request

response - the actual HTTP response

template - the template that was executed

data - the data that was passed to the template

Throws:

javax.servlet.ServletException

java.io.IOException

getConfiguration

protected Configuration getConfiguration()

Returns the Configuration object used by this servlet. Please don't forget that Configuration is not thread-safe when you modify it.