de.aristaflow.adept2.util

Class LocaleTools

java.lang.Object

de.aristaflow.adept2.util.LocaleTools

public final class LocaleTools
extends java.lang.Object

Provides Locale-specific utility methods.

Author:

Patrick Schmidt

Method Summary

Modifier and Type	Method and Description
static java.util.Map<java.util.Locale,java.lang.String>	fillLocalisedMessage(java.util.Map<java.util.Locale,java.lang.String> localisedMessage, java.lang.String msgKey, java.lang.String bundleName, java.util.List<java.util.Locale> locales, java.lang.Class<?> localisingClass, java.lang.Object... args) Loads the designated message key from the designated bundle for the designated locales and stores them in the designated map.
static java.util.Locale	findBestMatch(java.util.Locale targetLocale, java.util.Collection<java.util.Locale> availableLocales) Returns a locale from the given collection of available locales that best matches the given target locale or null if either the target locale is null or no locale matches the target locale.
static java.util.Locale[]	getCommonLocales() Returns a list of commonly useful locales, e.g. to offer a set of default locales in a combo box.
static java.util.List<java.util.Locale>	getFallbackSequence(java.util.List<java.util.Locale> preferredLocales) Gets a sequence of locales in the order they should be used until a localisation for a specific resource could be found for the designated preferred locales.
static java.util.List<java.util.Locale>	getFallbackSequence(java.util.Locale... preferredLocales) Gets a sequence of locales in the order they should be used until a localisation for a specific resource could be found for the designated preferred locales.
static java.lang.String	getLocaleLabel(java.util.Locale locale) Returns a string representation of the locale, which is presentable to the user.
static java.lang.String	getLocalisedMessage(java.lang.String msgKey, java.lang.String bundleName, java.util.Locale locale, java.lang.Class<?> localisingClass, java.lang.Object... args) Gets the localised message for the designated message key from the designated bundle for the designated locale.
static java.lang.String	getLocalisedString(java.util.Collection<java.util.Locale> locs, java.util.Map<java.util.Locale,java.lang.String> localisations) Gets the localised string from the designated map of localisations matching one of the designated locales.
static java.lang.String	getLocalisedString(java.util.Collection<java.util.Locale> locs, java.util.Map<java.util.Locale,java.lang.String> localisations, java.lang.String defString) Gets the localised string from the designated map of localisations matching one of the designated locales.
static java.lang.String	getLocalisedString(java.util.Locale loc, java.util.Map<java.util.Locale,java.lang.String> localisations) Gets the localised string from the designated map of localisations matching the designated locale or one of its fallbacks.
static java.lang.String	getLocalisedString(java.util.Locale loc, java.util.Map<java.util.Locale,java.lang.String> localisations, java.lang.String defString) Gets the localised string from the designated map of localisations matching the designated locale or one of its fallbacks.
static java.util.Locale	parseLocaleString(java.lang.String localeString) Parse a locale from the specified locale string as returned by Locale.toString().

Methods inherited from class java.lang.Object

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

Method Detail

getCommonLocales

public static java.util.Locale[] getCommonLocales()

Returns a list of commonly useful locales, e.g. to offer a set of default locales in a combo box.

Returns:

a list of commonly useful locales

parseLocaleString

public static java.util.Locale parseLocaleString(java.lang.String localeString)

Parse a locale from the specified locale string as returned by Locale.toString().

Parameters:

localeString - the locale string to be parsed

Returns:

The locale, null if the string was null. An empty or blank string will be parsed to Locale.ROOT.

See Also:

Locale.toString()

getFallbackSequence

public static java.util.List<java.util.Locale> getFallbackSequence(java.util.Locale... preferredLocales)

Gets a sequence of locales in the order they should be used until a localisation for a specific resource could be found for the designated preferred locales. The first of these locales should be the most preferred and the last typically being a default locale. The result will not contain duplicates, that is, a more generic locale will not be in the list again. For instance, [en_US, en_GB] will lead to [en_US, en, "quot;, en_GB].

Parameters:

preferredLocales - The desired locales in order of their preference. If this is null or an empty array or an array containing only one null element, an empty list will be returned. This must not contain several null elements.

Returns:

A sequence of locale fallbacks starting from and including the designated locale. The last locale will be Locale.ROOT. This will be the empty list if the designated locales are null or an empty array.

getFallbackSequence

public static java.util.List<java.util.Locale> getFallbackSequence(java.util.List<java.util.Locale> preferredLocales)

Gets a sequence of locales in the order they should be used until a localisation for a specific resource could be found for the designated preferred locales. The first of these locales should be the most preferred and the last typically being a default locale. The result will not contain duplicates, that is, a more generic locale will not be in the list again. For instance, [en_US, en_GB] will lead to [en_US, en, "", en_GB].

Parameters:

preferredLocales - The desired locales in order of their preference. If this is null, an empty list will be returned. This must not contain null elements.

Returns:

A sequence of locale fallbacks starting from and including the designated locale. The last locale will be Locale.ROOT. This will be the empty list if the designated locales are null or the empty list.

getLocalisedString

public static java.lang.String getLocalisedString(java.util.Locale loc,
                                                  java.util.Map<java.util.Locale,java.lang.String> localisations)

Gets the localised string from the designated map of localisations matching the designated locale or one of its fallbacks. The map should contain the root locale.

Parameters:

loc - The locale to retrieve the string for, also a fallback locale may be used.

localisations - A map containing localised strings for various locales. This map should contain the root locale.

Returns:

A localised string from the designated map corresponding to the designated locale or null if there is no appropriate localisation in the map.

getLocalisedString

public static java.lang.String getLocalisedString(java.util.Collection<java.util.Locale> locs,
                                                  java.util.Map<java.util.Locale,java.lang.String> localisations)

Gets the localised string from the designated map of localisations matching one of the designated locales. The map should contain the root locale.

Parameters:

locs - The locales to retrieve the string for, a preceding locale has preference over the following locales. This may be null.

localisations - A map containing localised strings for various locales. This map should contain the root locale.

Returns:

A localised string from the designated map corresponding to the designated locale or null if there is no appropriate localisation in the map.

getLocalisedString

public static java.lang.String getLocalisedString(java.util.Locale loc,
                                                  java.util.Map<java.util.Locale,java.lang.String> localisations,
                                                  java.lang.String defString)

Gets the localised string from the designated map of localisations matching the designated locale or one of its fallbacks. If there is no appropriate localisation in the map, the default string will be used.

Parameters:

loc - The locale to retrieve the string for, also a fallback locale may be used.

localisations - A map containing localised strings for various locales. This may be null.

defString - The default string to be used if no appropriate localisation is found.

Returns:

A localised string from the designated map corresponding to the designated locale or the designated default string if there is no appropriate localisation in the map.

getLocalisedString

public static java.lang.String getLocalisedString(java.util.Collection<java.util.Locale> locs,
                                                  java.util.Map<java.util.Locale,java.lang.String> localisations,
                                                  java.lang.String defString)

Gets the localised string from the designated map of localisations matching one of the designated locales. If there is no appropriate localisation in the map, the default string will be used.

Parameters:

locs - The locales to retrieve the string for, a preceding locale has preference over the following locales. This may be null.

localisations - A map containing localised strings for various locales. This may be null.

defString - The default string to be used if no appropriate localisation is found.

Returns:

A localised string from the designated map corresponding to the designated locale or the designated default string if there is no appropriate localisation in the map.

getLocalisedMessage

public static java.lang.String getLocalisedMessage(java.lang.String msgKey,
                                                   java.lang.String bundleName,
                                                   java.util.Locale locale,
                                                   java.lang.Class<?> localisingClass,
                                                   java.lang.Object... args)

Gets the localised message for the designated message key from the designated bundle for the designated locale. That is, a resource bundle with the designated name is loaded with the designated classloader for the designated locales. The localisation for the designated message key is then returned. This may be a fallback locale for the requested locale.

Parameters:

msgKey - The message key with which to retrieve the localisation from the resource bundle.

bundleName - The name of the resource bundle.

locale - The locale for which to retrieve the localisation for the designated message key.

localisingClass - The class that is performing the localisation. This is used for loading the resource bundle.

args - Optional arguments passed to the corresponding localised message using String.format(Locale, String, Object...).

Returns:

The requested localised message.

fillLocalisedMessage

public static java.util.Map<java.util.Locale,java.lang.String> fillLocalisedMessage(java.util.Map<java.util.Locale,java.lang.String> localisedMessage,
                                                                                    java.lang.String msgKey,
                                                                                    java.lang.String bundleName,
                                                                                    java.util.List<java.util.Locale> locales,
                                                                                    java.lang.Class<?> localisingClass,
                                                                                    java.lang.Object... args)

Loads the designated message key from the designated bundle for the designated locales and stores them in the designated map. That is, a resource bundle with the designated name is loaded with the designated classloader for each of the designated locales. The localisation for the designated message key is then stored in the designated map using the locale of the resource bundle. This locale may be a fallback for the requested locale. The root locale will always be included.

Parameters:

localisedMessage - The map to store the localised message with the locale of the corresponding resource bundle as key. If this is null a new map will be created and returned.

msgKey - The message key with which to retrieve the localisation from the resource bundles.

bundleName - The name of the resource bundle.

locales - The locales for which to retrieve localisations for the designated message key.

localisingClass - The class that is performing the localisation. This is used for loading the resource bundle.

args - Optional arguments passed to the corresponding localised message using String.format(Locale, String, Object...).

Returns:

The designated map containing the requested localisations. This is the designated map unless null is provided. If null is provided a new map will be created.

findBestMatch

public static java.util.Locale findBestMatch(java.util.Locale targetLocale,
                                             java.util.Collection<java.util.Locale> availableLocales)

Returns a locale from the given collection of available locales that best matches the given target locale or null if either the target locale is null or no locale matches the target locale. The best locale need not be the right one. That is, if a matching language is found, this locale may be the best, ignoring country and variant.

Parameters:

targetLocale - the desired locale

availableLocales - the available locales

Returns:

The best matching locale or null if not even a language matches.

getLocaleLabel

public static java.lang.String getLocaleLabel(java.util.Locale locale)

Returns a string representation of the locale, which is presentable to the user.

Parameters:

locale - The locale to be transformed to a string.

Returns:

The label string for the given locale.