Message Resources Semantics

This section will briefly discuss the semantics of MessageResources and PropertyMessageResources classes. Each message resource bundle has a base name, which corresponds to the name of a properties file, as discussed in the section "Internationalized Messaging and Labeling." This base name is identified by the property attribute in the <message-resources> element of the configuration file. The controller creates a MessageResourcesConfig object for every <message-resources> element in the configuration file. The controller then creates a MessageResources object for each MessageResourcesConfig object and saves it in the context using the key supplied for each message resource, or the default key Action.MESSAGES_KEY (a.k.a. Globals.MESSAGES_KEY).

The MessageResources objects are created using a MessageResourcesFactory. A factory class can be specified using the factory attribute in the <message-resources> element. However, for the accessing messages housed in a properties file, a default factory org.apache.struts.util.PropertyMessageResourcesFactory is preconfigured in the MessageResourcesConfig object; the ActionServlet uses this factory object for instantiating the PropertyMessageResources object. The following illustration depicts the static model providing internationalized messaging and labeling facility.

A message from a specific resource bundle is retrieved by the framework by first retrieving the PropertyMessageResources object from the context using the appropriate key and then calling its getMessage(…) method while passing a locale and a message key. PropertyMessageResources.getMessage(…) is used when the retrieved message does not require parametric substitution; otherwise, for parametric substitution the MessageResources.getMessage(…) method is used, which accepts a locale, a message key, and an Object[] as arguments. When an Object[] is specified, the MessageResources.getMessage(…) method retrieves the message format pattern by calling the PropertyMessageResources.getMessage(…) method and uses this format pattern in the MessageFormat.format(…) method to perform parametric substitution of Object[].

A cache of locale (converted to its String value) is maintained in the PropertyMessageResource object to identify if messages for a particular locale have already been loaded in the message cache. If a locale is not found in the locale cache, the entire properties file associated with that locale is loaded into the message cache. Refer to the section "Internationalized Messaging and Labeling" for naming conventions used for the properties files. The message cache is keyed by ‘locale.toString() + "." + key’ and the value is the value in the properties file for the corresponding key. When retrieving messages, it is possible that after loading the properties file for a particular locale, the desired key may not exist. In such situations, an attempt is made to find a key that is less restrictive for the specified locale; this is accomplished by stripping the locale variant from the key, if present, and doing another search with the less restrictive key; if this search is unsuccessful, then the locale's country code is stripped from the key and another search is performed. If the key is found using the less restrictive version of the locale, then the corresponding message is added to the message cache using the complete original key without country code or variant stripping; this increases the number of messages in the cache but provides faster response time for finding messages. If the key is not found even after locale stripping, the default locale is loaded in the message cache, if it already hasn't been loaded, and the key search is performed with the key modified for the default locale; if this search is unsuccessful, the base resource bundle without any locale specification is searched. If the key is found using the default locale or the base bundle, the corresponding message is added to the message cache using the complete original key.