org.javarosa.core.services.locale

Class Localizer

java.lang.Object

org.javarosa.core.services.locale.Localizer

All Implemented Interfaces:

Externalizable

public class Localizer
extends Object
implements Externalizable

The Localizer object maintains mappings for locale ID's and Object ID's to the String values associated with them in different locales.

Author:

Drew Roos/Clayton Sims

Constructor Summary

Constructors

Constructor and Description
Localizer() Default constructor.
Localizer(boolean fallbackDefaultLocale, boolean fallbackDefaultForm) Full constructor.

Method Summary

Modifier and Type	Method and Description
boolean	addAvailableLocale(String locale) Create a new locale (with no mappings).
static String	clearArguments(String text)
boolean	destroyLocale(String locale) Undefine a locale and remove all its data.
boolean	equals(Object o)
static List<String>	getArgs(String text)
String[]	getAvailableLocales() Get a list of defined locales.
String	getDefaultLocale() Get the default locale.
boolean	getFallbackForm() Get default form fallback mode
boolean	getFallbackLocale() Get default locale fallback mode
String	getLocale() Get the current locale.
OrderedMap<String,String>	getLocaleData(String locale) Get the set of mappings for a locale.
OrderedMap<String,String>	getLocaleMap(String locale) Get the mappings for a locale, but throw an exception if locale is not defined.
String	getLocalizedText(String textID) Retrieve localized text for a text handle in the current locale.
String	getNextLocale() Return the next locale in order, for cycling through locales.
String	getRawText(String locale, String textID) Get text for locale and exact text ID only, not using any fallbacks.
String	getText(String textID) Retrieve the localized text for a text handle in the current locale.
String	getText(String textID, HashMap<String,String> args) Retrieve the localized text for a text handle in the current locale.
String	getText(String textID, String locale) Retrieve the localized text for a text handle in the given locale.
String	getText(String textID, String[] args) Retrieve the localized text for a text handle in the current locale.
boolean	hasLocale(String locale) Get whether a locale is defined.
boolean	hasMapping(String locale, String textID) Determine whether a locale has a mapping for a given text handle.
static String	processArguments(String text, HashMap<String,String> args)
static String	processArguments(String text, String[] args)
static String	processArguments(String text, String[] args, int currentArg)
void	readExternal(DataInputStream dis, PrototypeFactory pf) Reads the object from a stream.
void	registerLocaleResource(String locale, LocaleDataSource resource) Registers a resource file as a source of locale data for the specified locale.
void	registerLocalizable(Localizable l) Register a Localizable to receive updates when the locale is changed.
void	setDefaultLocale(String defaultLocale) Set the default locale.
void	setLocale(String currentLocale) Set the current locale.
void	setToDefault() Set the current locale to the default locale.
void	unregisterAll() Unregister all ILocalizables.
void	unregisterLocalizable(Localizable l) Unregister an Localizable from receiving locale change updates.
void	writeExternal(DataOutputStream dos) Writes the object to a stream.

Methods inherited from class java.lang.Object

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

Constructor Detail

Localizer

public Localizer()

Default constructor. Disables all fallback modes.

Localizer

public Localizer(boolean fallbackDefaultLocale,
                 boolean fallbackDefaultForm)

Full constructor.

Parameters:

fallbackDefaultLocale - If true, search the default locale when no translation for a particular text handle is found in the current locale.

fallbackDefaultForm - If true, search the default text form when no translation is available for the specified text form ('long', 'short', etc.). Note: form is specified by appending ';[form]' onto the text ID.

Method Detail

equals

public boolean equals(Object o)

Overrides:

equals in class Object

getFallbackLocale

public boolean getFallbackLocale()

Get default locale fallback mode

Returns:

default locale fallback mode

getFallbackForm

public boolean getFallbackForm()

Get default form fallback mode

Returns:

default form fallback mode

addAvailableLocale

public boolean addAvailableLocale(String locale)

Create a new locale (with no mappings). Do nothing if the locale is already defined.

Parameters:

locale - Locale to add. Must not be null.

Returns:

True if the locale was not already defined.

Throws:

NullPointerException - if locale is null

getAvailableLocales

public String[] getAvailableLocales()

Get a list of defined locales.

Returns:

Array of defined locales, in order they were created.

hasLocale

public boolean hasLocale(String locale)

Get whether a locale is defined. The locale need not have any mappings.

Parameters:

locale - Locale

Returns:

Whether the locale is defined. False if null

getNextLocale

public String getNextLocale()

Return the next locale in order, for cycling through locales.

Returns:

Next locale following the current locale (if the current locale is the last, cycle back to the beginning). If the current locale is not set, return the default locale. If the default locale is not set, return null.

getLocale

public String getLocale()

Get the current locale.

Returns:

Current locale.

setLocale

public void setLocale(String currentLocale)

Set the current locale. The locale must be defined. Will notify all registered ILocalizables of the change in locale.

Parameters:

currentLocale - Locale. Must be defined and not null.

Throws:

UnregisteredLocaleException - If locale is null or not defined.

getDefaultLocale

public String getDefaultLocale()

Get the default locale.

Returns:

Default locale.

setDefaultLocale

public void setDefaultLocale(String defaultLocale)

Set the default locale. The locale must be defined.

Parameters:

defaultLocale - Default locale. Must be defined. May be null, in which case there will be no default locale.

Throws:

UnregisteredLocaleException - If locale is not defined.

setToDefault

public void setToDefault()

Set the current locale to the default locale. The default locale must be set.

Throws:

IllegalStateException - If default locale is not set.

registerLocaleResource

public void registerLocaleResource(String locale,
                                   LocaleDataSource resource)

Registers a resource file as a source of locale data for the specified locale.

Parameters:

locale - The locale of the definitions provided.

resource - A LocaleDataSource containing string data for the locale provided

Throws:

NullPointerException - if resource or locale are null

getLocaleData

public OrderedMap<String,String> getLocaleData(String locale)

Get the set of mappings for a locale.

Parameters:

locale - Locale

getLocaleMap

public OrderedMap<String,String> getLocaleMap(String locale)

Get the mappings for a locale, but throw an exception if locale is not defined.

Parameters:

locale - Locale

Returns:

Text mappings for locale.

Throws:

UnregisteredLocaleException - If locale is not defined or null.

hasMapping

public boolean hasMapping(String locale,
                          String textID)

Determine whether a locale has a mapping for a given text handle. Only tests the specified locale and form; does not fallback to any default locale or text form.

Parameters:

locale - Locale. Must be defined and not null.

textID - Text handle.

Returns:

True if a mapping exists for the text handle in the given locale.

Throws:

UnregisteredLocaleException - If locale is not defined.

destroyLocale

public boolean destroyLocale(String locale)

Undefine a locale and remove all its data. Cannot be called on the current locale. If called on the default locale, no default locale will be set afterward.

Parameters:

locale - Locale to remove. Must not be null. Need not be defined. Must not be the current locale.

Returns:

Whether the locale existed in the first place.

Throws:

IllegalArgumentException - If locale is the current locale.

NullPointerException - if locale is null

getText

public String getText(String textID)

Retrieve the localized text for a text handle in the current locale. See getText(String, String) for details.

Parameters:

textID - Text handle (text ID appended with optional text form). Must not be null.

Returns:

Localized text. If no text is found after using all fallbacks, return null.

Throws:

UnregisteredLocaleException - If current locale is not set.

NullPointerException - if textID is null

getText

public String getText(String textID,
                      String[] args)

Retrieve the localized text for a text handle in the current locale. See getText(String, String) for details.

Parameters:

textID - Text handle (text ID appended with optional text form). Must not be null.

args - arguments for string variables.

Returns:

Localized text

Throws:

UnregisteredLocaleException - If current locale is not set.

NullPointerException - if textID is null

NoLocalizedTextException - If there is no text for the specified id

getText

public String getText(String textID,
                      HashMap<String,String> args)

Retrieve the localized text for a text handle in the current locale. See getText(String, String) for details.

Parameters:

textID - Text handle (text ID appended with optional text form). Must not be null.

args - arguments for string variables.

Returns:

Localized text

Throws:

UnregisteredLocaleException - If current locale is not set.

NullPointerException - if textID is null

NoLocalizedTextException - If there is no text for the specified id

getLocalizedText

public String getLocalizedText(String textID)

Retrieve localized text for a text handle in the current locale. Like getText(String), however throws exception if no localized text is found.

Parameters:

textID - Text handle (text ID appended with optional text form). Must not be null.

Returns:

Localized text

Throws:

NoLocalizedTextException - If there is no text for the specified id

UnregisteredLocaleException - If current locale is not set

NullPointerException - if textID is null

getText

public String getText(String textID,
                      String locale)

Retrieve the localized text for a text handle in the given locale. If no mapping is found initially, then, depending on enabled fallback modes, other places will be searched until a mapping is found.

The search order is thus: 1) Specified locale, specified text form 2) Specified locale, default text form 3) Default locale, specified text form 4) Default locale, default text form

(1) and (3) are only searched if a text form ('long', 'short', etc.) is specified. If a text form is specified, (2) and (4) are only searched if default-form-fallback mode is enabled. (3) and (4) are only searched if default-locale-fallback mode is enabled. It is not an error in this situation if no default locale is set; (3) and (4) will simply not be searched.

Parameters:

textID - Text handle (text ID appended with optional text form). Must not be null.

locale - Locale. Must be defined and not null.

Returns:

Localized text. If no text is found after using all fallbacks, return null.

Throws:

UnregisteredLocaleException - If the locale is not defined or null.

NullPointerException - if textID is null

getRawText

public String getRawText(String locale,
                         String textID)

Get text for locale and exact text ID only, not using any fallbacks.

NOTE: This call will only return the full compliment of available strings if and only if the requested locale is current. Otherwise it will only retrieve strings declared at runtime.

Parameters:

locale - Locale. Must be defined and not null.

textID - Text handle (text ID appended with optional text form). Must not be null.

Returns:

Localized text. Return null if none found.

Throws:

UnregisteredLocaleException - If the locale is not defined or null.

NullPointerException - if textID is null

registerLocalizable

public void registerLocalizable(Localizable l)

Register a Localizable to receive updates when the locale is changed. If the Localizable is already registered, nothing happens. If a locale is currently set, the new Localizable will receive an immediate 'locale changed' event.

Parameters:

l - Localizable to register.

unregisterLocalizable

public void unregisterLocalizable(Localizable l)

Unregister an Localizable from receiving locale change updates. No effect if the Localizable was never registered in the first place.

Parameters:

l - Localizable to unregister.

unregisterAll

public void unregisterAll()

Unregister all ILocalizables.

getArgs

public static List<String> getArgs(String text)

processArguments

public static String processArguments(String text,
                                      HashMap<String,String> args)

processArguments

public static String processArguments(String text,
                                      String[] args)

processArguments

public static String processArguments(String text,
                                      String[] args,
                                      int currentArg)

clearArguments

public static String clearArguments(String text)

readExternal

public void readExternal(DataInputStream dis,
                         PrototypeFactory pf)
                  throws IOException,
                         DeserializationException

Reads the object from a stream.

Specified by:

readExternal in interface Externalizable

Throws:

IOException

DeserializationException

writeExternal

public void writeExternal(DataOutputStream dos)
                   throws IOException

Writes the object to a stream.

Specified by:

writeExternal in interface Externalizable

Throws:

IOException