org.thymeleaf.messageresolver

Class StandardMessageResolver

Object

org.thymeleaf.messageresolver.AbstractMessageResolver

org.thymeleaf.messageresolver.StandardMessageResolver

All Implemented Interfaces:

IMessageResolver

public class StandardMessageResolver
extends AbstractMessageResolver

Standard implementation of IMessageResolver.

This class will first try to perform message resolution based on the template context, then on the origin, and finally on the specified default messages (if any).

Step 1: Template-based message resolution

For template-based resolution, not only the template being executed will be examined, but also templates corresponding to fragments being inserted, so that if template A inserts a fragment from B, and that fragment from B inserts a fragment from C, the requested message will be searched in this order: A, B, C.

Note the order specified above allows container templates to override default message values specified at children (inserted fragment) templates.

For each of these templates, several .properties files will be examined. For example, a message in template /WEB-INF/templates/home.html for locale gl_ES-gheada ("gl" = language, "ES" = country, "gheada" = variant) would be looked for in .properties files in the following sequence:

• /WEB-INF/templates/home_gl_ES-gheada.properties
• /WEB-INF/templates/home_gl_ES.properties
• /WEB-INF/templates/home_gl.properties
• /WEB-INF/templates/home.properties

Note the resolution mechanism used for accessing these template-based .properties files will be the same used for resolving the templates themselves. So for templates resolved from the ServletContext its messages files will be searched at the ServletContext, for templates resolved from URL the corresponding derived URLs will be called, etc.

Step 2: Origin-based message resolution

If no suitable message value is found during template-based resolution, origin-based resolution is performed. This allows the resolution of messages from .properties files living in the classpath (and only in the classpath) in files corresponding with the names of the classes being used as origin.

For example, a processor my.company.processor.SomeDataProcessor using its own class as origin will be able to resolve messages from a my/company/processor/SomeDataProcessor_gl_ES.properties file in the classpath.

Also, if a message is not found there, resolution will be tried for each of the superclasses this my.company.processor.SomeDataProcessor class extends, until a suitable message is found, or no more superclasses (except java.lang.Object exist).

Step 3: Defaults-based message resolution

If both template-based and origin-based message resolution fail, resolution will be tried using the default messages specified via this class's setDefaultMessages(Properties) or addDefaultMessage(String, String) methods.

Defaults-based message resolution is not locale-dependent.

Absent message specification

Message resolution will return null if no message is found, in which case callers will have the possibility to choose between asking the resolver to create an absent message representation or not. This is precisely what the useAbsentMessageRepresentation flag does in ITemplateContext.getMessage(Class, String, Object[], boolean).

An absent message representation looks like ??mymessage_gl_ES?? and is useful to quickly determine when a message is lacking from the application's configuration. Note #{...} message expressions will always ask for an absent message representation, whereas methods in the #messages expression object will do it depending on the specific method being called.

Message caching

This implementation will cache template-based messages for those templates that are resolved (by their corresponding ITemplateResolver) as cacheable. Non-cacheable templates will not have their messages cached.

Origin-based messages will be always cached.

Extensibility

This implementation is designed for allowing the following extension points:

• resolveMessagesForTemplate(String, ITemplateResource, Locale): the mechanism for resolving the messages for a specific uncached template. Might be called several times, one per nested template.
• resolveMessagesForOrigin(Class, Locale): the mechanism for resolving the messages for a specific unchecked origin class. Might be called several times, one per class/superclass.
• formatMessage(Locale, String, Object[]): the way resolved messages are actually formated along with their parameters (by default a MessageFormat is used).
• createAbsentMessageRepresentation(ITemplateContext, Class, String, Object[]): the mechanism for creating absent message representations, which can be customized if needed.

Since:

3.0.0

Author:

Daniel Fernández

Constructor Summary

Constructors

Constructor and Description
StandardMessageResolver()

Method Summary

Modifier and Type	Method and Description
void	addDefaultMessage(String key, String value) Adds a new message to the set of default messages.
void	clearDefaultMessages() Clears the set of default messages.
String	createAbsentMessageRepresentation(ITemplateContext context, Class<?> origin, String key, Object[] messageParameters) Create a suitable representation of an absent message (a message that could not be resolved).
protected String	formatMessage(Locale locale, String message, Object[] messageParameters) Format a message, merging it with its parameters, before returning.
Properties	getDefaultMessages() Returns the default messages.
String	resolveMessage(ITemplateContext context, Class<?> origin, String key, Object[] messageParameters) Resolve the message, returning the requested message (or null if not found).
String	resolveMessage(ITemplateContext context, Class<?> origin, String key, Object[] messageParameters, boolean performTemplateBasedResolution, boolean performOriginBasedResolution, boolean performDefaultBasedResolution)
protected Map<String,String>	resolveMessagesForOrigin(Class<?> origin, Locale locale) Resolve messages for a specific origin and locale.
protected Map<String,String>	resolveMessagesForTemplate(String template, ITemplateResource templateResource, Locale locale) Resolve messages for a specific template and locale.
void	setDefaultMessages(Properties defaultMessages) Sets the default messages.

Methods inherited from class org.thymeleaf.messageresolver.AbstractMessageResolver

getName, getOrder, setName, setOrder

Methods inherited from class Object

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

Constructor Detail

StandardMessageResolver

public StandardMessageResolver()

Method Detail

getDefaultMessages

public final Properties getDefaultMessages()

Returns the default messages. These messages will be used if no other messages can be found.

Returns:

the default messages

setDefaultMessages

public final void setDefaultMessages(Properties defaultMessages)

Sets the default messages. These messages will be used if no other messages can be found.

Parameters:

defaultMessages - the new default messages

addDefaultMessage

public final void addDefaultMessage(String key,
                                    String value)

Adds a new message to the set of default messages.

Parameters:

key - the message key

value - the message value (text)

clearDefaultMessages

public final void clearDefaultMessages()

Clears the set of default messages.

resolveMessage

public final String resolveMessage(ITemplateContext context,
                                   Class<?> origin,
                                   String key,
                                   Object[] messageParameters)

Description copied from interface: IMessageResolver

Resolve the message, returning the requested message (or null if not found).

Message resolvers should perform resolution of the key + messageParameters pair based on the context and origin specified. The context will provide information about the template and the (optional) origin about the point in template execution from which the message is being requested (usually an IProcessor or the MessageExpression class).

Parameters:

context - the ITemplateContext object being used for template processing. Can be null.

origin - the origin of the message request, usually a processor or expression class. Can be null.

key - the message key.

messageParameters - the (optional) message parameters.

Returns:

the resolved message, or null if the message could not be resolved.

resolveMessage

public final String resolveMessage(ITemplateContext context,
                                   Class<?> origin,
                                   String key,
                                   Object[] messageParameters,
                                   boolean performTemplateBasedResolution,
                                   boolean performOriginBasedResolution,
                                   boolean performDefaultBasedResolution)

resolveMessagesForTemplate

protected Map<String,String> resolveMessagesForTemplate(String template,
                                                        ITemplateResource templateResource,
                                                        Locale locale)

Resolve messages for a specific template and locale.

This is meant to be overridden by subclasses if necessary, so that the way in which messages are obtained for a specific template can be modified without changing the rest of the message resolution mechanisms.

The standard mechanism will look for .properties files at the same location as the template (using the same resource resolution mechanism), and with the same name base.

Parameters:

template - the template

templateResource - the template resource

locale - the locale

Returns:

a Map containing all the possible messages for the specified template and locale. Can return null.

resolveMessagesForOrigin

protected Map<String,String> resolveMessagesForOrigin(Class<?> origin,
                                                      Locale locale)

Resolve messages for a specific origin and locale.

This is meant to be overridden by subclasses if necessary, so that the way in which messages are obtained for a specific origin can be modified without changing the rest of the message resolution mechanisms.

The standard mechanism will look for files in the classpath (only classpath), at the same package and with the same name as the origin class, with .properties extension.

Parameters:

origin - the origin

locale - the locale

Returns:

a Map containing all the possible messages for the specified origin and locale. Can return null.

formatMessage

protected String formatMessage(Locale locale,
                               String message,
                               Object[] messageParameters)

Format a message, merging it with its parameters, before returning.

This is meant to be overridden by subclasses if necessary. The default mechanism will simply use a standard MessageFormat instance.

Parameters:

locale - the locale

message - the resolved message

messageParameters - the message parameters (might be null)

Returns:

the formatted message

createAbsentMessageRepresentation

public String createAbsentMessageRepresentation(ITemplateContext context,
                                                Class<?> origin,
                                                String key,
                                                Object[] messageParameters)

Description copied from interface: IMessageResolver

Create a suitable representation of an absent message (a message that could not be resolved).

Once the entire chain of configured IMessageResolver objects is asked for a specific message and all of them return null, the engine will call this method on the first resolver in the chain. If the first resolver returns null as a representation, the following resolver will be called, and so on until a resolver returns a non-null result. The empty String will be used if all resolvers return null.

Parameters:

context - the ITemplateContext object being used for template processing. Can be null.

origin - the origin of the message request, usually a processor or expression class. Can be null.

key - the message key.

messageParameters - the (optional) message parameters.

Returns:

the absent message representation, of null if the resolver cannot create such representation.