org.thymeleaf
Class TemplateEngine

Object
  org.thymeleaf.TemplateEngine

public class TemplateEngine
extends Object

Main class for the execution of templates.

In order to execute Thymeleaf templates, an instance of this class (or one of its subclasses) must be created.

Creating an instance of TemplateEngine

An instance of this class can be created at any time by calling its constructor:

final TemplateEngine templateEngine = new TemplateEngine();

Creation and configuration of TemplateEngine instances is expensive, so it is recommended to create only one instance of this class (or at least one instance per dialect/configuration) and use it to process multiple templates.

Configuring the TemplateEngine

Once created, an instance of TemplateEngine has to be configured by setting the following required parameters:

• One or more Template Resolvers (instances of ITemplateResolver), in charge of reading or obtaining the templates so that the engine is able to process them. If only one template resolver is set (the most common case), the setTemplateResolver(ITemplateResolver) method can be used for this. If more resolvers are to be set, both the setTemplateResolvers(Set) and addTemplateResolver(ITemplateResolver) methods can be used.

Also, the following parameters can be optionally set:

• One or more Dialects (instances of IDialect), defining the way in which templates will be processed: DOM processors, expression parsers, etc. If no dialect is explicitly set, a unique instance of StandardDialect (the Standard Dialect) will be used.
  • Dialects define a default prefix, which will be used for them if not otherwise specified.
  • When setting/adding dialects, a non-default prefix can be specified for each of them.
  • Several dialects can use the same prefix, effectively acting as an aggregate dialect.
  • All specified dialects will be validated to ensure no conflicts with DOCTYPE translations or resolution entries exist. Dialects defining a DOCTYPE translation or resolution entry equal to another one in a different dialect are not considered to be in conflict.
  • Dialect leniency will be computed per-prefix, so that a prefix will be considered to be lenient if at least one of the dialects configured for it is lenient.
  • Note that defining a non-default prefix for a dialect might affect its validation features if this dialect includes DTD files for such purpose (e.g. the Standard Dialect).
• One or more Message Resolvers (instances of IMessageResolver), in charge of resolving externalized messages. If no message resolver is explicitly set, the default setting specified by setDefaultMessageResolvers(Set) will be applied (this default setting defaults itself to a single instance of StandardMessageResolver). If only one message resolver is set, the setMessageResolver(IMessageResolver) method can be used for this. If more resolvers are to be set, both the setMessageResolvers(Set) and addMessageResolver(IMessageResolver) methods can be used.
• A set of Template Mode Handlers (instances of ITemplateModeHandler, which will take care of reading/parsing templates and also writing the results of processing them for a specific template mode. The presence of these template mode handlers defines which are the valid values for the templateMode attribute of template resolution results (TemplateResolution.getTemplateMode()). If not explicitly set, template mode handlers will be initialized to StandardTemplateModeHandlers.ALL_TEMPLATE_MODE_HANDLERS.
• A Cache Manager (instance of ICacheManager. The Cache Manager is in charge of providing the cache objects (instances of ICache) to be used for caching (at least) templates, fragments, messages and expressions. By default, a StandardCacheManager instance is used. If a null cache manager is specified by calling setCacheManager(ICacheManager), no caches will be used throughout the system at all.

Template Execution

1. Creating a context

All template executions require a context. A context is an object that implements the IContext interface, and that contains at least the following data:

• The locale to be used for message externalization (internationalization).
• The context variables. A map of variables that will be available for use from expressions in the executed template.

Two IContext implementations are provided out-of-the-box:

• Context, a standard implementation containing only the required data.
• WebContext, a web-specific implementation extending the IWebContext subinterface, offering request, session and servletcontext (application) attributes in special variables inside the context variables map. Using an implementation of IWebContext is required when using Thymeleaf for generating HTML/XHTML interfaces in web applications.

Creating a Context instance is very simple:

final IContext ctx = new Context();
ctx.setVariable("allItems", items);

A WebContext would also need HttpServletRequest and ServletContext objects as constructor arguments:

final IContext ctx = new WebContext(request, servletContext);
ctx.setVariable("allItems", items);

See the documentation for these specific implementations for more details.

2. Template Processing

In order to execute templates, the process(String, IContext) and process(String, IContext, Writer) methods can be used:

Without a writer, the processing result will be returned as a String:

final String result = templateEngine.process("mytemplate", ctx);

By specifying a writer, we can avoid the creation of a String containing the whole processing result by writing this result into the output stream as soon as it is produced from the processed DOM. This is specially useful in web scenarios:

templateEngine.process("mytemplate", ctx, httpServletResponse.getWriter());

The "mytemplate" String argument is the template name, and it will relate to the physical/logical location of the template itself in a way configured at the template resolver/s.

Since:

1.0

Author:

Daniel Fernández

Field Summary

static String

TIMER_LOGGER_NAME Name of the TIMER logger.

Constructor Summary

TemplateEngine()
Constructor for TemplateEngine objects.

Method Summary

void	addDialect(IDialect dialect) Adds a new dialect for this template engine, using the dialect's specified default dialect.
void	addDialect(String prefix, IDialect dialect) Adds a new dialect for this template engine, using the specified prefix.
void	addMessageResolver(IMessageResolver messageResolver) Adds a message resolver to the set of message resolvers to be used by the template engine.
void	addTemplateModeHandler(ITemplateModeHandler templateModeHandler) Adds a Template Mode Handler to the set of Template Mode Handlers to be used by the template engine.
void	addTemplateResolver(ITemplateResolver templateResolver) Adds a new template resolver to the current set.
void	clearDialects() Removes all the currently configured dialects.
void	clearTemplateCache() Completely clears the Template Cache.
void	clearTemplateCacheFor(String templateName) Clears the entry in the Template Cache for the specified template, if it is currently cached.
ICacheManager	getCacheManager() Returns the cache manager in effect.
protected Configuration	getConfiguration() Returns the configuration object.
java.util.Set<IDialect>	getDialects() Returns the configured dialects.
java.util.Map<String,IDialect>	getDialectsByPrefix() Returns the configured dialects, referenced by their prefixes.
java.util.Set<IMessageResolver>	getMessageResolvers() Returns the set of Message Resolvers configured for this Template Engine.
java.util.Set<ITemplateModeHandler>	getTemplateModeHandlers() Returns the set of Template Mode Handlers configured for this Template Engine.
TemplateRepository	getTemplateRepository() Returns the template repository.
java.util.Set<ITemplateResolver>	getTemplateResolvers() Returns the Set of template resolvers currently configured.
void	initialize() Internal method that initializes the Template Engine instance.
protected void	initializeSpecific() This method performs additional initializations required for a TemplateEngine.
protected boolean	isInitialized() Checks whether the TemplateEngine has already been initialized or not.
String	process(String templateName, IContext context) Process a template.
void	process(String templateName, IContext context, java.io.Writer writer) Process a template.
void	setCacheManager(ICacheManager cacheManager) Sets the Cache Manager to be used.
void	setDefaultMessageResolvers(java.util.Set<? extends IMessageResolver> defaultMessageResolvers) Sets the default message resolvers.
void	setDefaultTemplateModeHandlers(java.util.Set<? extends ITemplateModeHandler> defaultTemplateModeHandlers) Sets the default Template Mode Handlers.
void	setDialect(IDialect dialect) Sets a new unique dialect for this template engine.
void	setDialects(java.util.Set<IDialect> dialects) Sets a new set of dialects for this template engine, all of them using their default prefixes.
void	setDialectsByPrefix(java.util.Map<String,IDialect> dialects) Sets a new set of dialects for this template engine, referenced by the prefixes they will be using.
void	setMessageResolver(IMessageResolver messageResolver) Sets a single message resolver for this template engine.
void	setMessageResolvers(java.util.Set<? extends IMessageResolver> messageResolvers) Sets the message resolvers to be used by this template engine.
void	setTemplateModeHandlers(java.util.Set<? extends ITemplateModeHandler> templateModeHandlers) Sets the Template Mode Handlers to be used by this template engine.
void	setTemplateResolver(ITemplateResolver templateResolver) Sets a single template resolver for this template engine.
void	setTemplateResolvers(java.util.Set<? extends ITemplateResolver> templateResolvers) Sets the entire set of template resolvers.
static Long	threadIndex() Internal method that retrieves the thread-local index for the current template execution.
static java.util.Locale	threadLocale() Internal method that retrieves the thread-local locale for the current template execution.
static String	threadTemplateName() Internal method that retrieves the thread-local template name for the current template execution.

Methods inherited from class Object

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

Field Detail

TIMER_LOGGER_NAME

public static final String TIMER_LOGGER_NAME

Name of the TIMER logger. This logger will output the time required for executing each template processing operation.

The value of this constant is org.thymeleaf.TemplateEngine.TIMER. This allows you to set a specific configuration and/or appenders for timing info at your logging system configuration.

Constructor Detail

TemplateEngine

public TemplateEngine()

Constructor for TemplateEngine objects.

This is the only way to create a TemplateEngine instance (which should be configured after creation).

Method Detail

isInitialized

protected final boolean isInitialized()

Checks whether the TemplateEngine has already been initialized or not. A TemplateEngine is initialized when the initialize() method is called the first time a template is processed.

Normally, there is no good reason why users would need to call this method.

Returns:

true if the template engine has already been initialized, false if not.

getConfiguration

protected Configuration getConfiguration()

Returns the configuration object. Meant to be used only by subclasses of TemplateEngine.

Returns:

the current configuration

getTemplateRepository

public TemplateRepository getTemplateRepository()

Returns the template repository. Normally there is no reason why users would want to obtain or use this object directly (and it is not recommended behaviour).

Returns:

the template repository

getDialectsByPrefix

public final java.util.Map<String,IDialect> getDialectsByPrefix()

Returns the configured dialects, referenced by their prefixes.

Returns:

the IDialect instances currently configured.

getDialects

public final java.util.Set<IDialect> getDialects()

Returns the configured dialects.

Returns:

the IDialect instances currently configured.

setDialect

public void setDialect(IDialect dialect)

Sets a new unique dialect for this template engine.

This operation is equivalent to removing all the currently configured dialects and then adding this one.

This operation can only be executed before processing templates for the first time. Once a template is processed, the template engine is considered to be initialized, and from then on any attempt to change its configuration will result in an exception.

Parameters:

dialect - the new unique IDialect to be used.

addDialect

public void addDialect(String prefix,
                       IDialect dialect)

Adds a new dialect for this template engine, using the specified prefix.

This dialect will be added to the set of currently configured ones.

This operation can only be executed before processing templates for the first time. Once a template is processed, the template engine is considered to be initialized, and from then on any attempt to change its configuration will result in an exception.

Parameters:

prefix - the prefix that will be used for this dialect

dialect - the new IDialect to be added to the existing ones.

addDialect

public void addDialect(IDialect dialect)

Adds a new dialect for this template engine, using the dialect's specified default dialect.

This dialect will be added to the set of currently configured ones.

This operation can only be executed before processing templates for the first time. Once a template is processed, the template engine is considered to be initialized, and from then on any attempt to change its configuration will result in an exception.

Parameters:

dialect - the new IDialect to be added to the existing ones.

setDialectsByPrefix

public void setDialectsByPrefix(java.util.Map<String,IDialect> dialects)

Sets a new set of dialects for this template engine, referenced by the prefixes they will be using.

This operation can only be executed before processing templates for the first time. Once a template is processed, the template engine is considered to be initialized, and from then on any attempt to change its configuration will result in an exception.

Parameters:

dialects - the new map of IDialect objects to be used, referenced by their prefixes.

setDialects

public void setDialects(java.util.Set<IDialect> dialects)

Sets a new set of dialects for this template engine, all of them using their default prefixes.

This operation can only be executed before processing templates for the first time. Once a template is processed, the template engine is considered to be initialized, and from then on any attempt to change its configuration will result in an exception.

Parameters:

dialects - the new set of IDialect objects to be used.

clearDialects

public void clearDialects()

Removes all the currently configured dialects.

This operation can only be executed before processing templates for the first time. Once a template is processed, the template engine is considered to be initialized, and from then on any attempt to change its configuration will result in an exception.

getTemplateResolvers

public final java.util.Set<ITemplateResolver> getTemplateResolvers()

Returns the Set of template resolvers currently configured.

Returns:

the template resolvers.

setTemplateResolvers

public void setTemplateResolvers(java.util.Set<? extends ITemplateResolver> templateResolvers)

Sets the entire set of template resolvers.

Parameters:

templateResolvers - the new template resolvers.

addTemplateResolver

public void addTemplateResolver(ITemplateResolver templateResolver)

Adds a new template resolver to the current set.

Parameters:

templateResolver - the new template resolver.

setTemplateResolver

public void setTemplateResolver(ITemplateResolver templateResolver)

Sets a single template resolver for this template engine.

Calling this method is equivalent to calling setTemplateResolvers(Set) passing a Set with only one template resolver.

Parameters:

templateResolver - the template resolver to be set.

getCacheManager

public ICacheManager getCacheManager()

Returns the cache manager in effect. This manager is in charge of providing the various caches needed by the system during its process.

By default, an instance of StandardCacheManager is set.

Returns:

the cache manager

setCacheManager

public void setCacheManager(ICacheManager cacheManager)

Sets the Cache Manager to be used. If set to null, no caches will be used throughout the engine.

By default, an instance of StandardCacheManager is set.

This operation can only be executed before processing templates for the first time. Once a template is processed, the template engine is considered to be initialized, and from then on any attempt to change its configuration will result in an exception.

Parameters:

cacheManager - the cache manager to be set.

getMessageResolvers

public final java.util.Set<IMessageResolver> getMessageResolvers()

Returns the set of Message Resolvers configured for this Template Engine.

Returns:

the set of message resolvers.

setMessageResolvers

public void setMessageResolvers(java.util.Set<? extends IMessageResolver> messageResolvers)

Sets the message resolvers to be used by this template engine.

This operation can only be executed before processing templates for the first time. Once a template is processed, the template engine is considered to be initialized, and from then on any attempt to change its configuration will result in an exception.

Parameters:

messageResolvers - the Set of template resolvers.

addMessageResolver

public void addMessageResolver(IMessageResolver messageResolver)

Adds a message resolver to the set of message resolvers to be used by the template engine.

This operation can only be executed before processing templates for the first time. Once a template is processed, the template engine is considered to be initialized, and from then on any attempt to change its configuration will result in an exception.

Parameters:

messageResolver - the new message resolver to be added.

setMessageResolver

public void setMessageResolver(IMessageResolver messageResolver)

Sets a single message resolver for this template engine.

Calling this method is equivalent to calling setMessageResolvers(Set) passing a Set with only one message resolver.

This operation can only be executed before processing templates for the first time. Once a template is processed, the template engine is considered to be initialized, and from then on any attempt to change its configuration will result in an exception.

Parameters:

messageResolver - the message resolver to be set.

setDefaultMessageResolvers

public void setDefaultMessageResolvers(java.util.Set<? extends IMessageResolver> defaultMessageResolvers)

Sets the default message resolvers. These are used when no message resolvers are set via the setMessageResolver(IMessageResolver), setMessageResolvers(Set) or addMessageResolver(IMessageResolver) methods.

This method is useful for creating subclasses of TemplateEngine that establish default configurations for message resolvers.

This operation can only be executed before processing templates for the first time. Once a template is processed, the template engine is considered to be initialized, and from then on any attempt to change its configuration will result in an exception.

Parameters:

defaultMessageResolvers - the default message resolvers.

getTemplateModeHandlers

public final java.util.Set<ITemplateModeHandler> getTemplateModeHandlers()

Returns the set of Template Mode Handlers configured for this Template Engine.

By default, template mode handlers set are StandardTemplateModeHandlers.ALL_TEMPLATE_MODE_HANDLERS

Returns:

the set of Template Mode Handlers.

setTemplateModeHandlers

public void setTemplateModeHandlers(java.util.Set<? extends ITemplateModeHandler> templateModeHandlers)

Sets the Template Mode Handlers to be used by this template engine. Every available template mode must have its corresponding handler.

By default, template mode handlers set are StandardTemplateModeHandlers.ALL_TEMPLATE_MODE_HANDLERS

This operation can only be executed before processing templates for the first time. Once a template is processed, the template engine is considered to be initialized, and from then on any attempt to change its configuration will result in an exception.

Parameters:

templateModeHandlers - the Set of Template Mode Handlers.

addTemplateModeHandler

public void addTemplateModeHandler(ITemplateModeHandler templateModeHandler)

Adds a Template Mode Handler to the set of Template Mode Handlers to be used by the template engine. Every available template mode must have its corresponding handler.

By default, template mode handlers set are StandardTemplateModeHandlers.ALL_TEMPLATE_MODE_HANDLERS

This operation can only be executed before processing templates for the first time. Once a template is processed, the template engine is considered to be initialized, and from then on any attempt to change its configuration will result in an exception.

Parameters:

templateModeHandler - the new Template Mode Handler to be added.

setDefaultTemplateModeHandlers

public void setDefaultTemplateModeHandlers(java.util.Set<? extends ITemplateModeHandler> defaultTemplateModeHandlers)

Sets the default Template Mode Handlers. These are used when no Template Mode Handlers are set via the setTemplateModeHandlers(Set) or addTemplateModeHandler(ITemplateModeHandler) methods.

This method is useful for creating subclasses of TemplateEngine that establish default configurations for Template Mode Handlers.

By default, template mode handlers set are StandardTemplateModeHandlers.ALL_TEMPLATE_MODE_HANDLERS

This operation can only be executed before processing templates for the first time. Once a template is processed, the template engine is considered to be initialized, and from then on any attempt to change its configuration will result in an exception.

Parameters:

defaultTemplateModeHandlers - the default Template Mode Handlers.

clearTemplateCache

public void clearTemplateCache()

Completely clears the Template Cache.

If this method is called before the TemplateEngine has been initialized, it causes its initialization.

clearTemplateCacheFor

public void clearTemplateCacheFor(String templateName)

Clears the entry in the Template Cache for the specified template, if it is currently cached.

If this method is called before the TemplateEngine has been initialized, it causes its initialization.

Parameters:

templateName - the name of the template to be cleared from cache.

initialize

public final void initialize()

Internal method that initializes the Template Engine instance. This method is called before the first execution of process(String, IContext) in order to create all the structures required for a quick execution of templates.

THIS METHOD IS INTERNAL AND SHOULD NEVER BE CALLED DIRECTLY.

If a subclass of TemplateEngine needs additional steps for initialization, the initializeSpecific() method should be overridden.

initializeSpecific

protected void initializeSpecific()

This method performs additional initializations required for a TemplateEngine. It is called by initialize().

The implementation of this method does nothing, and it is designed for being overridden by subclasses of TemplateEngine.

threadIndex

public static Long threadIndex()

Internal method that retrieves the thread-local index for the current template execution.

THIS METHOD IS INTERNAL AND SHOULD NEVER BE CALLED DIRECTLY.

Returns:

the index of the current execution.

threadLocale

public static java.util.Locale threadLocale()

Internal method that retrieves the thread-local locale for the current template execution.

THIS METHOD IS INTERNAL AND SHOULD NEVER BE CALLED DIRECTLY.

Returns:

the locale of the current template execution.

threadTemplateName

public static String threadTemplateName()

Internal method that retrieves the thread-local template name for the current template execution.

THIS METHOD IS INTERNAL AND SHOULD NEVER BE CALLED DIRECTLY.

Returns:

the template name for the current engine execution.

process

public final String process(String templateName,
                            IContext context)

Process a template. This method receives both a template name and a context.

The template name will be used as input for the template resolvers, queried in chain until one of them resolves the template, which will then be executed.

The context will contain the variables that will be available for the execution of expressions inside the template.

Parameters:

templateName - the name of the template.

context - the context.

Returns:

a String containing the result of evaluating the specified template with the provided context.

process

public final void process(String templateName,
                          IContext context,
                          java.io.Writer writer)

Process a template. This method receives a template name, a context and also a Writer, so that there is no need to create a String object containing the whole processing results because these will be written to the specified writer as soon as they are generated from the processed DOM tree. This is specially useful for web environments (using ServletResponse.getWriter()).

The template name will be used as input for the template resolvers, queried in chain until one of them resolves the template, which will then be executed.

The context will contain the variables that will be available for the execution of expressions inside the template.

Parameters:

templateName - the name of the template.

context - the context.

writer - the writer the results will be output to.

Since:

2.0.0