Package org.thymeleaf.messageresolver

Class 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:

    Since:
    3.0.0
    Author:
    Daniel Fernández

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