org.springframework.context.support
Class AbstractMessageSource

java.lang.Object
  extended by org.springframework.context.support.AbstractMessageSource
All Implemented Interfaces:
HierarchicalMessageSource, MessageSource
Direct Known Subclasses:
ReloadableResourceBundleMessageSource, ResourceBundleMessageSource, StaticMessageSource

public abstract class AbstractMessageSource
extends Object
implements HierarchicalMessageSource

Abstract implementation of the HierarchicalMessageSource interface, implementing common handling of message variants, making it easy to implement a specific strategy for a concrete MessageSource.

Subclasses must implement the abstract resolveCode method. For efficient resolution of messages without arguments, the resolveCodeWithoutArguments method should be overridden as well, resolving messages without a MessageFormat being involved.

Note: By default, message texts are only parsed through MessageFormat if arguments have been passed in for the message. In case of no arguments, message texts will be returned as-is. As a consequence, you should only use MessageFormat escaping for messages with actual arguments, and keep all other messages unescaped. If you prefer to escape all messages, set the "alwaysUseMessageFormat" flag to "true".

Supports not only MessageSourceResolvables as primary messages but also resolution of message arguments that are in turn MessageSourceResolvables themselves.

This class does not implement caching of messages per code, thus subclasses can dynamically change messages over time. Subclasses are encouraged to cache their messages in a modification-aware fashion, allowing for hot deployment of updated messages.

Author:
Juergen Hoeller, Rod Johnson
See Also:
resolveCode(String, java.util.Locale), resolveCodeWithoutArguments(String, java.util.Locale), setAlwaysUseMessageFormat(boolean), MessageFormat

Field Summary
protected  Log logger
          Logger available to subclasses
 
Constructor Summary
AbstractMessageSource()
           
 
Method Summary
protected  MessageFormat createMessageFormat(String msg, Locale locale)
          Create a MessageFormat for the given message and Locale.
protected  String formatMessage(String msg, Object[] args, Locale locale)
          Format the given message String, using cached MessageFormats.
protected  String getDefaultMessage(String code)
          Return a fallback default message for the given code, if any.
 String getMessage(MessageSourceResolvable resolvable, Locale locale)
          Try to resolve the message using all the attributes contained within the MessageSourceResolvable argument that was passed in.
 String getMessage(String code, Object[] args, Locale locale)
          Try to resolve the message.
 String getMessage(String code, Object[] args, String defaultMessage, Locale locale)
          Try to resolve the message.
protected  String getMessageFromParent(String code, Object[] args, Locale locale)
          Try to retrieve the given message from the parent MessageSource, if any.
protected  String getMessageInternal(String code, Object[] args, Locale locale)
          Resolve the given code and arguments as message in the given Locale, returning null if not found.
 MessageSource getParentMessageSource()
          Return the parent of this MessageSource, or null if none.
protected  boolean isAlwaysUseMessageFormat()
          Return whether to always apply the MessageFormat rules, parsing even messages without arguments.
protected  boolean isUseCodeAsDefaultMessage()
          Return whether to use the message code as default message instead of throwing a NoSuchMessageException.
protected  String renderDefaultMessage(String defaultMessage, Object[] args, Locale locale)
          Render the given default message String.
protected  Object[] resolveArguments(Object[] args, Locale locale)
          Search through the given array of objects, find any MessageSourceResolvable objects and resolve them.
protected abstract  MessageFormat resolveCode(String code, Locale locale)
          Subclasses must implement this method to resolve a message.
protected  String resolveCodeWithoutArguments(String code, Locale locale)
          Subclasses can override this method to resolve a message without arguments in an optimized fashion, that is, to resolve a message without involving a MessageFormat.
 void setAlwaysUseMessageFormat(boolean alwaysUseMessageFormat)
          Set whether to always apply the MessageFormat rules, parsing even messages without arguments.
 void setParentMessageSource(MessageSource parent)
          Set the parent that will be used to try to resolve messages that this object can't resolve.
 void setUseCodeAsDefaultMessage(boolean useCodeAsDefaultMessage)
          Set whether to use the message code as default message instead of throwing a NoSuchMessageException.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

logger

protected final Log logger
Logger available to subclasses

Constructor Detail

AbstractMessageSource

public AbstractMessageSource()
Method Detail

setParentMessageSource

public void setParentMessageSource(MessageSource parent)
Description copied from interface: HierarchicalMessageSource
Set the parent that will be used to try to resolve messages that this object can't resolve.

Specified by:
setParentMessageSource in interface HierarchicalMessageSource
Parameters:
parent - the parent MessageSource that will be used to resolve messages that this object can't resolve. May be null, in which case no further resolution is possible.

getParentMessageSource

public MessageSource getParentMessageSource()
Description copied from interface: HierarchicalMessageSource
Return the parent of this MessageSource, or null if none.

Specified by:
getParentMessageSource in interface HierarchicalMessageSource

setUseCodeAsDefaultMessage

public void setUseCodeAsDefaultMessage(boolean useCodeAsDefaultMessage)
Set whether to use the message code as default message instead of throwing a NoSuchMessageException. Useful for development and debugging. Default is "false".

Note: In case of a MessageSourceResolvable with multiple codes (like a FieldError) and a MessageSource that has a parent MessageSource, do not activate "useCodeAsDefaultMessage" in the parent: Else, you'll get the first code returned as message by the parent, without attempts to check further codes.

To be able to work with "useCodeAsDefaultMessage" turned on in the parent, AbstractMessageSource and AbstractApplicationContext contain special checks to delegate to the internal getMessageInternal method if available. In general, it is recommended to just use "useCodeAsDefaultMessage" during development and not rely on it in production in the first place, though.

See Also:
getMessage(String, Object[], Locale), getMessageInternal(java.lang.String, java.lang.Object[], java.util.Locale), FieldError

isUseCodeAsDefaultMessage

protected boolean isUseCodeAsDefaultMessage()
Return whether to use the message code as default message instead of throwing a NoSuchMessageException. Useful for development and debugging. Default is "false".

Alternatively, consider overriding the getDefaultMessage method to return a custom fallback message for an unresolvable code.

See Also:
getDefaultMessage(String)

setAlwaysUseMessageFormat

public void setAlwaysUseMessageFormat(boolean alwaysUseMessageFormat)
Set whether to always apply the MessageFormat rules, parsing even messages without arguments.

Default is "false": Messages without arguments are by default returned as-is, without parsing them through MessageFormat. Set this to "true" to enforce MessageFormat for all messages, expecting all message texts to be written with MessageFormat escaping.

For example, MessageFormat expects a single quote to be escaped as "''". If your message texts are all written with such escaping, even when not defining argument placeholders, you need to set this flag to "true". Else, only message texts with actual arguments are supposed to be written with MessageFormat escaping.

See Also:
MessageFormat

isAlwaysUseMessageFormat

protected boolean isAlwaysUseMessageFormat()
Return whether to always apply the MessageFormat rules, parsing even messages without arguments.


getMessage

public final String getMessage(String code,
                               Object[] args,
                               String defaultMessage,
                               Locale locale)
Description copied from interface: MessageSource
Try to resolve the message. Return default message if no message was found.

Specified by:
getMessage in interface MessageSource
Parameters:
code - the code to lookup up, such as 'calculator.noRateSet'. Users of this class are encouraged to base message names on the relevant fully qualified class name, thus avoiding conflict and ensuring maximum clarity.
args - array of arguments that will be filled in for params within the message (params look like "{0}", "{1,date}", "{2,time}" within a message), or null if none.
defaultMessage - String to return if the lookup fails
locale - the Locale in which to do the lookup
Returns:
the resolved message if the lookup was successful; otherwise the default message passed as a parameter
See Also:
java.text.MessageFormat

getMessage

public final String getMessage(String code,
                               Object[] args,
                               Locale locale)
                        throws NoSuchMessageException
Description copied from interface: MessageSource
Try to resolve the message. Treat as an error if the message can't be found.

Specified by:
getMessage in interface MessageSource
Parameters:
code - the code to lookup up, such as 'calculator.noRateSet'
args - Array of arguments that will be filled in for params within the message (params look like "{0}", "{1,date}", "{2,time}" within a message), or null if none.
locale - the Locale in which to do the lookup
Returns:
the resolved message
Throws:
NoSuchMessageException - if the message wasn't found
See Also:
java.text.MessageFormat

getMessage

public final String getMessage(MessageSourceResolvable resolvable,
                               Locale locale)
                        throws NoSuchMessageException
Description copied from interface: MessageSource
Try to resolve the message using all the attributes contained within the MessageSourceResolvable argument that was passed in.

NOTE: We must throw a NoSuchMessageException on this method since at the time of calling this method we aren't able to determine if the defaultMessage property of the resolvable is null or not.

Specified by:
getMessage in interface MessageSource
Parameters:
resolvable - value object storing attributes required to properly resolve a message
locale - the Locale in which to do the lookup
Returns:
the resolved message
Throws:
NoSuchMessageException - if the message wasn't found
See Also:
java.text.MessageFormat

getMessageInternal

protected String getMessageInternal(String code,
                                    Object[] args,
                                    Locale locale)
Resolve the given code and arguments as message in the given Locale, returning null if not found. Does not fall back to the code as default message. Invoked by getMessage methods.

Parameters:
code - the code to lookup up, such as 'calculator.noRateSet'
args - array of arguments that will be filled in for params within the message
locale - the Locale in which to do the lookup
Returns:
the resolved message, or null if not found
See Also:
getMessage(String, Object[], String, Locale), getMessage(String, Object[], Locale), getMessage(MessageSourceResolvable, Locale), setUseCodeAsDefaultMessage(boolean)

getMessageFromParent

protected String getMessageFromParent(String code,
                                      Object[] args,
                                      Locale locale)
Try to retrieve the given message from the parent MessageSource, if any.

Parameters:
code - the code to lookup up, such as 'calculator.noRateSet'
args - array of arguments that will be filled in for params within the message
locale - the Locale in which to do the lookup
Returns:
the resolved message, or null if not found
See Also:
getParentMessageSource()

getDefaultMessage

protected String getDefaultMessage(String code)
Return a fallback default message for the given code, if any.

Default is to return the code itself if "useCodeAsDefaultMessage" is activated, or return no fallback else. In case of no fallback, the caller will usually receive a NoSuchMessageException from getMessage.

Parameters:
code - the message code that we couldn't resolve and that we didn't receive an explicit default message for
Returns:
the default message to use, or null if none
See Also:
setUseCodeAsDefaultMessage(boolean)

renderDefaultMessage

protected String renderDefaultMessage(String defaultMessage,
                                      Object[] args,
                                      Locale locale)
Render the given default message String. The default message is passed in as specified by the caller and can be rendered into a fully formatted default message shown to the user.

Default implementation passes the String to formatMessage, resolving any argument placeholders found in them. Subclasses may override this method to plug in custom processing of default messages.

Parameters:
defaultMessage - the passed-in default message String
args - array of arguments that will be filled in for params within the message, or null if none.
locale - the Locale used for formatting
Returns:
the rendered default message (with resolved arguments)
See Also:
formatMessage(String, Object[], java.util.Locale)

formatMessage

protected String formatMessage(String msg,
                               Object[] args,
                               Locale locale)
Format the given message String, using cached MessageFormats. By default invoked for passed-in default messages, to resolve any argument placeholders found in them.

Parameters:
msg - the message to format
args - array of arguments that will be filled in for params within the message, or null if none.
locale - the Locale used for formatting
Returns:
the formatted message (with resolved arguments)

createMessageFormat

protected MessageFormat createMessageFormat(String msg,
                                            Locale locale)
Create a MessageFormat for the given message and Locale.

This implementation creates an empty MessageFormat first, populating it with Locale and pattern afterwards, to stay compatible with J2SE 1.3.

Parameters:
msg - the message to create a MessageFormat for
locale - the Locale to create a MessageFormat for
Returns:
the MessageFormat instance

resolveArguments

protected Object[] resolveArguments(Object[] args,
                                    Locale locale)
Search through the given array of objects, find any MessageSourceResolvable objects and resolve them.

Allows for messages to have MessageSourceResolvables as arguments.

Parameters:
args - array of arguments for a message
locale - the locale to resolve through
Returns:
an array of arguments with any MessageSourceResolvables resolved

resolveCodeWithoutArguments

protected String resolveCodeWithoutArguments(String code,
                                             Locale locale)
Subclasses can override this method to resolve a message without arguments in an optimized fashion, that is, to resolve a message without involving a MessageFormat.

The default implementation does use MessageFormat, through delegating to the resolveCode method. Subclasses are encouraged to replace this with optimized resolution.

Unfortunately, java.text.MessageFormat is not implemented in an efficient fashion. In particular, it does not detect that a message pattern doesn't contain argument placeholders in the first place. Therefore, it's advisable to circumvent MessageFormat completely for messages without arguments.

Parameters:
code - the code of the message to resolve
locale - the Locale to resolve the code for (subclasses are encouraged to support internationalization)
Returns:
the message String, or null if not found
See Also:
resolveCode(java.lang.String, java.util.Locale), MessageFormat

resolveCode

protected abstract MessageFormat resolveCode(String code,
                                             Locale locale)
Subclasses must implement this method to resolve a message.

Returns a MessageFormat instance rather than a message String, to allow for appropriate caching of MessageFormats in subclasses.

Subclasses are encouraged to provide optimized resolution for messages without arguments, not involving MessageFormat. See resolveCodeWithoutArguments javadoc for details.

Parameters:
code - the code of the message to resolve
locale - the Locale to resolve the code for (subclasses are encouraged to support internationalization)
Returns:
the MessageFormat for the message, or null if not found
See Also:
resolveCodeWithoutArguments(String, java.util.Locale)


Copyright (c) 2002-2007 The Spring Framework Project.