com.threerings.util
Class MessageBundle

java.lang.Object
  com.threerings.util.MessageBundle

public class MessageBundle
extends Object

A message bundle provides an easy mechanism by which to obtain translated message strings from a resource bundle. It uses the MessageFormat class to substitute arguments into the translation strings. Message bundles would generally be obtained via the MessageManager, but could be constructed individually if so desired.

Constructor Summary

MessageBundle()

Method Summary

static String	compose(String key, Object... args) Composes a message key with an array of arguments.
static String	compose(String key, Object arg) Composes a message key with a single argument.
static String	compose(String key, String... args) Composes a message key with an array of arguments.
boolean	exists(String key) Returns true if we have a translation mapping for the supplied key, false if not.
String	get(String key) Obtains the translation for the specified message key.
String	get(String key, Object... args) Obtains the translation for the specified message key.
String	get(String key, String... args) Obtains the translation for the specified message key.
void	getAll(String prefix, Collection<String> messages, boolean includeParent) Adds all messages whose key starts with the specified prefix to the supplied collection.
void	getAllKeys(String prefix, Collection<String> keys, boolean includeParent) Adds all keys for messages whose key starts with the specified prefix to the supplied collection.
static String	getBundle(String qualifiedKey) Returns the bundle name from a fully qualified message key.
String	getResourceString(String key) Get a String from the resource bundle, or null if there was an error.
String	getResourceString(String key, boolean reportMissing) Get a String from the resource bundle, or null if there was an error.
String	getSuffix(Object[] args) A helper function for get(String,Object[]) that allows us to automatically perform plurality processing if our first argument can be coaxed to an Integer.
static String	getUnqualifiedKey(String qualifiedKey) Returns the unqualified portion of the key from a fully qualified message key.
void	init(MessageManager msgmgr, String path, ResourceBundle bundle, MessageBundle parent) Initializes the message bundle which will obtain localized messages from the supplied resource bundle.
static String	qualify(String bundle, String key) Returns a fully qualified message key which, when translated by some other bundle, will know to resolve and utilize the supplied bundle to translate this particular key.
static String	taint(Object text) Call this to "taint" any string that has been entered by an entity outside the application so that the translation code knows not to attempt to translate this string when doing recursive translations (see xlate(java.lang.String)).
static String	tcompose(String key, Object... args) A convenience method for calling compose(String,Object[]) with an array of arguments that will be automatically tainted (see taint(java.lang.Object)).
static String	tcompose(String key, Object arg) Required for backwards compatibility.
static String	tcompose(String key, Object arg1, Object arg2) Required for backwards compatibility.
static String	tcompose(String key, String... args) A convenience method for calling compose(String,String[]) with an array of arguments that will be automatically tainted (see taint(java.lang.Object)).
String	toString()
String	xlate(String compoundKey) Obtains the translation for the specified compound message key.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MessageBundle

public MessageBundle()

Method Detail

taint

public static String taint(Object text)

Call this to "taint" any string that has been entered by an entity outside the application so that the translation code knows not to attempt to translate this string when doing recursive translations (see xlate(java.lang.String)).

compose

public static String compose(String key,
                             Object arg)

Composes a message key with a single argument. The message can subsequently be translated in a single call using xlate(java.lang.String).

compose

public static String compose(String key,
                             Object... args)

Composes a message key with an array of arguments. The message can subsequently be translated in a single call using xlate(java.lang.String).

compose

public static String compose(String key,
                             String... args)

Composes a message key with an array of arguments. The message can subsequently be translated in a single call using xlate(java.lang.String).

tcompose

public static String tcompose(String key,
                              Object... args)

A convenience method for calling compose(String,Object[]) with an array of arguments that will be automatically tainted (see taint(java.lang.Object)).

tcompose

public static String tcompose(String key,
                              Object arg)

Required for backwards compatibility. Alas.

tcompose

public static String tcompose(String key,
                              Object arg1,
                              Object arg2)

Required for backwards compatibility. Alas.

tcompose

public static String tcompose(String key,
                              String... args)

A convenience method for calling compose(String,String[]) with an array of arguments that will be automatically tainted (see taint(java.lang.Object)).

qualify

public static String qualify(String bundle,
                             String key)

Returns a fully qualified message key which, when translated by some other bundle, will know to resolve and utilize the supplied bundle to translate this particular key.

getBundle

public static String getBundle(String qualifiedKey)

Returns the bundle name from a fully qualified message key.

See Also:

qualify(java.lang.String, java.lang.String)

getUnqualifiedKey

public static String getUnqualifiedKey(String qualifiedKey)

Returns the unqualified portion of the key from a fully qualified message key.

See Also:

qualify(java.lang.String, java.lang.String)

init

public void init(MessageManager msgmgr,
                 String path,
                 ResourceBundle bundle,
                 MessageBundle parent)

Initializes the message bundle which will obtain localized messages from the supplied resource bundle. The path is provided purely for reporting purposes.

get

public String get(String key)

Obtains the translation for the specified message key. No arguments are substituted into the translated string. If a translation message does not exist for the specified key, an error is logged and the key itself is returned so that the caller need not worry about handling a null response.

getAll

public void getAll(String prefix,
                   Collection<String> messages,
                   boolean includeParent)

Adds all messages whose key starts with the specified prefix to the supplied collection.

Parameters:

includeParent - if true, messages from our parent bundle (and its parent bundle, all the way up the chain will be included).

getAllKeys

public void getAllKeys(String prefix,
                       Collection<String> keys,
                       boolean includeParent)

Adds all keys for messages whose key starts with the specified prefix to the supplied collection.

Parameters:

includeParent - if true, messages from our parent bundle (and its parent bundle, all the way up the chain will be included).

exists

public boolean exists(String key)

Returns true if we have a translation mapping for the supplied key, false if not.

getResourceString

public String getResourceString(String key)

Get a String from the resource bundle, or null if there was an error.

getResourceString

public String getResourceString(String key,
                                boolean reportMissing)

Get a String from the resource bundle, or null if there was an error.

Parameters:

key - the resource key.

reportMissing - whether or not the method should log an error if the resource didn't exist.

get

public String get(String key,
                  Object... args)

Obtains the translation for the specified message key. The specified arguments are substituted into the translated string.

If the first argument in the array is an Integer object, a translation will be selected accounting for plurality in the following manner. Assume a message key of m.widgets, the following translations should be defined:

 m.widgets.0 =
 no widgets. m.widgets.1 = {0} widget. m.widgets.n = {0} widgets. 

The specified argument is substituted into the translated string as appropriate. Consider using:

 m.widgets.n = {0,number,integer} widgets. 

to obtain proper insertion of commas and dots as appropriate for the locale.

See MessageFormat for more information on how the substitution is performed. If a translation message does not exist for the specified key, an error is logged and the key itself (plus the arguments) is returned so that the caller need not worry about handling a null response.

get

public String get(String key,
                  String... args)

Obtains the translation for the specified message key. The specified arguments are substituted into the translated string.

getSuffix

public String getSuffix(Object[] args)

A helper function for get(String,Object[]) that allows us to automatically perform plurality processing if our first argument can be coaxed to an Integer.

xlate

public String xlate(String compoundKey)

Obtains the translation for the specified compound message key. A compound key contains the message key followed by a tab separated list of message arguments which will be substituted into the translation string.

See MessageFormat for more information on how the substitution is performed. If a translation message does not exist for the specified key, an error is logged and the key itself (plus the arguments) is returned so that the caller need not worry about handling a null response.

toString

public String toString()

Overrides:

toString in class Object