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: attributes, tags, value and expression processors, 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.
• The size of the template caché, set by means of the setParsedTemplateCacheSize(int) method. This caché will be used to store the parsed DOM trees of templates in order to reduce the amount of input/output operations needed. It uses the LRU (Least Recently Used) algorithm. If not set, this parameter will default to Configuration.DEFAULT_PARSED_TEMPLATE_CACHE_SIZE.

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 will also need an HttpServletRequest object as a constructor argument:

final IContext ctx = new WebContext(request);
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) method will be used:

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

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 char	CHAR_ENTITY_START_SUBSTITUTE Constant containing the char that is used for substituting the & character in entities present in DOM Text nodes.
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	addTemplateResolver(ITemplateResolver templateResolver) Adds a new template resolver to the current set.
void	clearDialects() Removes all the currently configured dialects.
void	clearParsedTemplateCache() Completely clears the Parsed Template Cache.
void	clearParsedTemplateCacheFor(String templateName) Clears the entry in the Parsed Template Cache for the specified template, if it is currently cached.
protected Configuration	getConfiguration() Returns the configuration object.
Set<IDialect>	getDialects() Returns the configured dialects.
Map<String,IDialect>	getDialectsByPrefix() Returns the configured dialects, referenced by their prefixes.
Set<IMessageResolver>	getMessageResolvers() Returns the set of Message Resolvers configured for this Template Engine.
int	getParsedTemplateCacheSize() Returns the size of the LRU caché of parsed templates.
Set<ITemplateResolver>	getTemplateResolvers() Returns the Set of template resolvers currently configured.
protected 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	setDefaultMessageResolvers(Set<? extends IMessageResolver> defaultMessageResolvers) Sets the default message resolvers.
void	setDialect(IDialect dialect) Sets a new unique dialect for this template engine.
void	setDialects(Set<IDialect> dialects) Sets a new set of dialects for this template engine, all of them using their default prefixes.
void	setDialectsByPrefix(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 messae resolver for this template engine.
void	setMessageResolvers(Set<? extends IMessageResolver> messageResolvers) Sets the message resolvers to be used by this template engine.
void	setParsedTemplateCacheSize(int parsedTemplateCacheSize) Sets the new size for the template caché.
void	setTemplateResolver(ITemplateResolver templateResolver) Sets a single template resolver for this template engine.
void	setTemplateResolvers(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 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.

CHAR_ENTITY_START_SUBSTITUTE

public static final char CHAR_ENTITY_START_SUBSTITUTE

Constant containing the char that is used for substituting the & character in entities present in DOM Text nodes. These symbols are substituted so that Thymeleaf can output entities in Text nodes in exactly the way they are written in templates, without resolving or re-escaping them.

Developers should never have the need to use this constant unless they are manually processing Text nodes that might contain ampersand ('&') symbols.

Since:

1.1

See Also:

Constant Field Values

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.

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

getDialectsByPrefix

public final Map<String,IDialect> getDialectsByPrefix()

Returns the configured dialects, referenced by their prefixes.

Returns:

the IDialect instances currently configured.

getDialects

public final 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(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(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 Set<ITemplateResolver> getTemplateResolvers()

Returns the Set of template resolvers currently configured.

Returns:

the template resolvers.

setTemplateResolvers

public void setTemplateResolvers(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.

getMessageResolvers

public final Set<IMessageResolver> getMessageResolvers()

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

Returns:

the set of message resolvers.

setMessageResolvers

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

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

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.

Parameters:

messageResolver - the new message resolver to be added.

setMessageResolver

public void setMessageResolver(IMessageResolver messageResolver)

Sets a single messae resolver for this template engine.

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

Parameters:

messageResolver - the message resolver to be set.

setDefaultMessageResolvers

public void setDefaultMessageResolvers(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.

Parameters:

defaultMessageResolvers - the default message resolvers.

getParsedTemplateCacheSize

public final int getParsedTemplateCacheSize()

Returns the size of the LRU caché of parsed templates.

Returns:

the current size of the caché

setParsedTemplateCacheSize

public void setParsedTemplateCacheSize(int parsedTemplateCacheSize)

Sets the new size for the template caché.

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:

parsedTemplateCacheSize - the new size for the caché

clearParsedTemplateCache

public void clearParsedTemplateCache()

Completely clears the Parsed Template Cache.

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

clearParsedTemplateCacheFor

public void clearParsedTemplateCacheFor(String templateName)

Clears the entry in the Parsed 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

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