Retrieving Messages from Message Files

A message file can contain any number of locales for a named message, and as a result a mechanism needs to be in place to return the correctly localized message for a running instance of Cúram. Messages are retrieved from a message file based on the locale property which includes a language and, optionally, a country. The message file look up returns a matching localized message for a named message identifier. For example, if the runtime locale is set to en_US where "en" is the language and "US" is the country, a message look up for the message named A_MESSAGE with the example below will return the text "The message". If however the runtime locale was set to "fr" the text "Le message" would be returned.

Figure 1. Message File Search

<messages package="curam.message">
<message name="A MESSAGE">
  <locale country="US" language="en">The message</locale>
  <locale language="fr">Le message</locale>
  <locale language="en">The en message</locale>
</message></messages>

Since message files are not guaranteed to contain an entry for each message that matches the runtime locale, a fall back mechanism is in place to guarantee that if possible a localized message is returned when a look up is performed. Once a message of a given name has been found, and there is no direct match with the specified locale, the rules for fall back are as follows:

If the runtime locale is set to include a language and country, the country is removed and the search looks for a matching language only. Looking up the message named A_MESSAGE in the example above with runtime locale en_US will return the message text "The message".

If nothing is found for the runtime locale, then a lookup will be performed using the fall back locale of en. Looking up the message named A_MESSAGE in the example above with runtime locale es will return the message text "The en message", i.e. the lookup will revert to the fall back locale of en as nothing can be found for es.

If nothing can be found for either the runtime locale or the fall back locale, then the search will be determined based on the underlying message lookup mechanism provided by the JDK class java.util.ResourceBundle. Please refer to the relevant JDK JavaDoc for details of this classes functionality and further details of the fall back mechanism provided.

If the runtime locale does not find a match in the message file and no match can be found using the fall back locale of en, and no match can be found after applying the fall back rules described by java.util.ResourceBundle, a MissingResourceException is returned and server logs are updated if appropriate.