org.faktorips.runtime.util

Class MessagesHelper

java.lang.Object

org.faktorips.runtime.util.MessagesHelper

public class MessagesHelper
extends Object

A MessagesHelper is a set of strings available in different locales. A localized string can be looked up by a locale independent key and a locale.

The locale dependent strings have to be stored in property files. They are accessed via Java's ResourceBundle. To access the property files, they all have to be in the same package and must start with the same prefix. Therefore the set's qualified name is the package name, followed by a dot (.), followed by the prefix, e.g. "org.faktorips.internal.messages". For further information see the ResourceBundle documentation.

In order to have a fallback if a message was requested in a not existing locale ResourceBundle provides a strategy to find a message anyway: If the message was not found the fallback strategy will try to find a resource for the system default language. If this also does not succeed a resource bundle without language specification would be taken. This leads to a bad behavior: Imagine you provide English as your default language and hence having your English translation in a property file without locale suffix. Additionally you provide a German translation with suffix _de. Now you start your runtime with system default language German but you try to get a message in English. You would always get the German one because the strategy does not find a resource for _en but finds one for _de (your system default). The file without suffix would never be read. To avoid this problem we recommend to add a language suffix to every resource. Additionally to get a fallback to your default language you have to provide the default language to the MessagesHelper. When calling getMessage(String, Locale)) the we first check for the primary language, second then the ResourceBundle will check for system default language and third we would provide the message in specified default language.

If a localized String contains sections that have to be replaced with replacements before the String is presented to a user, you can use the method with replacement objects as a parameter. The mechanism used here is the one of MessageFormat.

The property file loaded by the ResourceBundle is cached internally by SoftReferences. So you do not have to worry about performance problems instantiation this class multiple times.

Example:

In the message "The sum insured must be at least {0}." the sum insured must be inserted at runtime depending on the chosen product.

Constructor Summary

Constructors

Constructor and Description
MessagesHelper(String qualifiedName, ClassLoader loader, Locale defaultLocale) Creates a new StringsSet with the indicated qualified name.

Method Summary

Methods

Modifier and Type	Method and Description
String	getMessage(String key, Locale locale) Getting the message for the given key in the specified locale.
String	getMessage(String key, Locale locale, Object... replacements) Getting the message for the given key in the specified language.
String	getMessageOr(String key, Locale locale, String fallBack) Getting the message for the given key in the specified language.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MessagesHelper

public MessagesHelper(String qualifiedName,
              ClassLoader loader,
              Locale defaultLocale)

Creates a new StringsSet with the indicated qualified name. The property files are loaded with the indicated classloader.

Parameters:

qualifiedName - The qualified name of your resource without suffix nor extension for ".properties" example org.sample.messages

loader - The ClassLoader to load the ResourceBundle

defaultLocale - If no message was found the system default locale is used as fallback. If there is also no resource bundle in system's default language we try to find a message in defaultLocale

Method Detail

getMessage

public String getMessage(String key,
                Locale locale)

Getting the message for the given key in the specified locale.

Parameters:

key - the key of the message

locale - the locale of the message you want to get

Returns:

the translated message located in the property file

getMessage

public String getMessage(String key,
                Locale locale,
                Object... replacements)

Getting the message for the given key in the specified language. For every replacement parameter there must be a replacement mark (e.g. {0}) in the message. @see MessageFormat.

Parameters:

key - The key of the message

locale - The locale of the message you want to get

replacements - the replacements in the message text

Returns:

the translated message located in the property file with replaced parameters

getMessageOr

public String getMessageOr(String key,
                  Locale locale,
                  String fallBack)

Getting the message for the given key in the specified language. If there is no message in the specified language the message helper searches the key in the default language. If there is not message for the specified key in the requested language nor the default language, this message returns the specified fallback text.

Parameters:

key - The key to identify the message

locale - the locale of the expected message

fallBack - a fall back text if there is no message

Returns:

The message for the specified key