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:
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.Constructor and Description |
---|
StandardMessageResolver() |
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.
|
getName, getOrder, setName, setOrder
public final Properties getDefaultMessages()
Returns the default messages. These messages will be used if no other messages can be found.
public final void setDefaultMessages(Properties defaultMessages)
Sets the default messages. These messages will be used if no other messages can be found.
defaultMessages
- the new default messagespublic final void addDefaultMessage(String key, String value)
Adds a new message to the set of default messages.
key
- the message keyvalue
- the message value (text)public final void clearDefaultMessages()
Clears the set of default messages.
public final String resolveMessage(ITemplateContext context, Class<?> origin, String key, Object[] messageParameters)
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).
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.public final String resolveMessage(ITemplateContext context, Class<?> origin, String key, Object[] messageParameters, boolean performTemplateBasedResolution, boolean performOriginBasedResolution, boolean performDefaultBasedResolution)
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.
template
- the templatetemplateResource
- the template resourcelocale
- the localeprotected 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.
origin
- the originlocale
- the localeprotected 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.
locale
- the localemessage
- the resolved messagemessageParameters
- the message parameters (might be null)public String createAbsentMessageRepresentation(ITemplateContext context, Class<?> origin, String key, Object[] messageParameters)
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.
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.Copyright © 2016 The THYMELEAF team. All rights reserved.