com.plumtree.openfoundation.internationalization
Class XPResourceManager

java.lang.Object
  com.plumtree.openfoundation.internationalization.XPResourceManager

All Implemented Interfaces:

IXPResourceManager

public class XPResourceManager
extends java.lang.Object
implements IXPResourceManager

XPResourceManager is a singleton class that loads all resouce files in a given resource folder. The resource files are primarily used to store the localized string messages. The GetString method of this class is overloaded to support placeholder substitution. The placeholder can be escaped using '\' character. The escaped placeholder will not be replaced and will appear as it is without the escape character i.e. \''. For e.g., if a string "Hello \{0} {0}" is substituted with "Test", the result is "Hello {0} Test". XPResourceManager uses XPResourceSet to load the resources from resource files.

See Also:

XPResourceSet

Field Summary

static java.lang.String

LOCALES_RESOURCE_FILE MES- The name of the file that holds the localized strings describing languages.

Method Summary

static XPResourceManager	CreateResourceManager(java.lang.String resourceFolder) Single access point to obtain an instance of XPResourceManager.
static java.lang.String	FormatMessage(java.lang.String message, java.lang.Object argValue0) Returns the string with the placeholders {0} replaced with the given argument value.
static java.lang.String	FormatMessage(java.lang.String message, java.lang.Object argValue0, java.lang.Object argValue1) Returns the string with the placeholders {0} and {1} replaced with the given argument values.
static java.lang.String	FormatMessage(java.lang.String message, java.lang.Object argValue0, java.lang.Object argValue1, java.lang.Object argValue2) Returns the string with the placeholders {0}, {1} and {2} replaced with the given argument values.
static java.lang.String	FormatMessage(java.lang.String message, java.lang.Object argValue0, java.lang.Object argValue1, java.lang.Object argValue2, java.lang.Object argValue3) Returns the string with the placeholders {0}, {1}, {2} and {3} replaced with the given argument values.
java.lang.String	GetDisplayLanguageFromLocaleID(java.lang.String sLocale, java.lang.String language) Translates from a locale or language identifier to the human readable string for the language.
java.lang.String	GetDisplayLocaleFromLocaleID(java.lang.String sLocale, java.lang.String language) Translates from a locale or language identifier to the human readable string for that locale or language.
java.lang.String	GetString(int messageID, java.lang.String messageFileName, java.lang.String language) Returns the string corresponding to the given message ID, message file index or name and the language.
java.lang.String	GetString(int messageID, java.lang.String messageFileName, java.lang.String language, java.lang.Object argValue0) Returns the string corresponding to the given message ID, message file index or name and the language.
java.lang.String	GetString(int messageID, java.lang.String messageFileName, java.lang.String language, java.lang.Object argValue0, java.lang.Object argValue1) Returns the string corresponding to the given message ID, message file index or name and the language.
java.lang.String	GetString(int messageID, java.lang.String messageFileName, java.lang.String language, java.lang.Object argValue0, java.lang.Object argValue1, java.lang.Object argValue2) Returns the string corresponding to the given message ID, message file index or name and the language.
java.lang.String	GetString(int messageID, java.lang.String messageFileName, java.lang.String language, java.lang.Object argValue0, java.lang.Object argValue1, java.lang.Object argValue2, java.lang.Object argValue3) Returns the string corresponding to the given message ID, message file index or name and the language.
java.lang.String[]	GetSupportedLanguages() Returns the supported languages that can be used as an argument to GetString(*) methods.
java.lang.String[]	GetSupportedLocales(java.lang.String language) Returns the supported locales that can be used as an argument to GetString(*) methods.
void	LoadResources() Loads the resources in all supported languages into an internal hashtable.
java.lang.String	MapLocaleToSupportedUILangID(java.lang.String sLocaleID) Converts from a locale chosen by the user (e.g.
java.lang.String	MapLocaleToSupportedUILangID(java.lang.String sLocaleID, java.lang.String defaultLangID) Converts from a locale chosen by the user (e.g.
java.lang.String	MapLocaleToUISupportedLocaleID(java.lang.String sLocaleID, java.lang.String defaultLocaleID) Converts from a locale chosen by the user (e.g.
static XPSortedDictionary	NormalizeLocaleList(java.lang.String strAcceptsHeader) This helper method converts an accepts header into an XPSortedDictionary in decreasing order of q value.
static java.lang.String	TruncateLocaleID(java.lang.String sLocaleID) An internal use funcation to truncates a locale ID to a language.

Methods inherited from class java.lang.Object

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

Field Detail

LOCALES_RESOURCE_FILE

public static final java.lang.String LOCALES_RESOURCE_FILE

MES- The name of the file that holds the localized strings describing languages.

See Also:

Constant Field Values

Method Detail

FormatMessage

public static java.lang.String FormatMessage(java.lang.String message,
                                             java.lang.Object argValue0)

Returns the string with the placeholders {0} replaced with the given argument value.

Parameters:

message - String message with the placeholder {0}

argValue0 - value of the placeholder {0}

Returns:

String with the placeholder {0} replaced with the given argument value.

FormatMessage

public static java.lang.String FormatMessage(java.lang.String message,
                                             java.lang.Object argValue0,
                                             java.lang.Object argValue1)

Returns the string with the placeholders {0} and {1} replaced with the given argument values.

Parameters:

message - String message with the placeholders {0} and {1}

argValue0 - value of the placeholder {0}

argValue1 - value of the placeholder {1}

Returns:

String with the placeholder {0} and {1} replaced with the given argument values.

FormatMessage

public static java.lang.String FormatMessage(java.lang.String message,
                                             java.lang.Object argValue0,
                                             java.lang.Object argValue1,
                                             java.lang.Object argValue2)

Returns the string with the placeholders {0}, {1} and {2} replaced with the given argument values.

Parameters:

message - String message with the placeholders {0}, {1} and {2}

argValue0 - value of the placeholder {0}

argValue1 - value of the placeholder {1}

argValue2 - value of the placeholder {2}

Returns:

String with the placeholder {0}, {1} and {2} replaced with the given argument values.

FormatMessage

public static java.lang.String FormatMessage(java.lang.String message,
                                             java.lang.Object argValue0,
                                             java.lang.Object argValue1,
                                             java.lang.Object argValue2,
                                             java.lang.Object argValue3)

Returns the string with the placeholders {0}, {1}, {2} and {3} replaced with the given argument values.

Parameters:

message - String message with the placeholders {0}, {1}, {2} and {3}

argValue0 - value of the placeholder {0}

argValue1 - value of the placeholder {1}

argValue2 - value of the placeholder {2}

argValue3 - value of the placeholder {3}

Returns:

String with the placeholder {0}, {1}, {2} and {3} replaced with the given argument values.

CreateResourceManager

public static XPResourceManager CreateResourceManager(java.lang.String resourceFolder)

Single access point to obtain an instance of XPResourceManager. Only one XPResourceManager instance is created.

Parameters:

resourceFolder - Name of the directory that contains the resource files.

Returns:

the only instance of XPResourceManager

GetSupportedLanguages

public java.lang.String[] GetSupportedLanguages()

Returns the supported languages that can be used as an argument to GetString(*) methods.

Returns:

An array of strings representing the identifiers of the languages

NormalizeLocaleList

public static XPSortedDictionary NormalizeLocaleList(java.lang.String strAcceptsHeader)

This helper method converts an accepts header into an XPSortedDictionary in decreasing order of q value. An example accept-language header could look as follows: From the specification: da, en-gb;q=0.8, en;q=0.7 (this implies da is the best choice, then en-gb, and finally en) IE 6: zh-cn,en-us;q=0.8,ja;q=0.5,es-mx;q=0.3 NS 7.1 ja,en-us;q=0.8,zh;q=0.7,zh-cn;q=0.5,es-mx;q=0.3,en;q=0.2 Both IE and Netscape already sort in practice, but the spec allows it to not be sorted (Safari on the Mac does not sort). The return list will be sorted in reverse order. Therefore, locales with q=1 will be stored with a reverseQ of 0, and q's of .3 will be converted to .7. This means the first locale in the list will be the best choice. For example: "da, en-gb;q=0.8, en;q=0.7" will return as "da,en-gb,en" "zh-cn,en-us;q=0.5,ja;q=0.8,es-mx;q=0.9" will return as "zh-cn,es-mx,ja,en-us" "en-us,ja" will return as "en-us,ja" "en-us,q=0.8,ja;q=0.9" will return as "en-us,ja"

Parameters:

strAcceptsHeader - the accepts header.

Returns:

XPSortedDictionary sorted list of locales.

MapLocaleToUISupportedLocaleID

public java.lang.String MapLocaleToUISupportedLocaleID(java.lang.String sLocaleID,
                                                       java.lang.String defaultLocaleID)

Converts from a locale chosen by the user (e.g. en-us) to a locale ID supported by the UI, or return the supplied locale value if no match is found. This return supported locale ID is in lowercase.

Parameters:

sLocaleID - The ID of the locale to be mapped, or an RFC 2616, HTTP/1.1 string on Accept-Language (eg. ja, en-gb;q=0.8, en;q=0.7)

defaultLocaleID - Default value to be used if the supplied locale does not map to any of the UI supported locales

Returns:

The supported locale ID corresponding to the user's locale; or default locale value if no match is found

Throws:

XPException

MapLocaleToSupportedUILangID

public java.lang.String MapLocaleToSupportedUILangID(java.lang.String sLocaleID,
                                                     java.lang.String defaultLangID)

Converts from a locale chosen by the user (e.g. en-us) to a language ID supported by the UI. or the supplied default language ID if no corresponding language is found. In this context, a valid language ID corresponds to the name of a folder under the "msgs" folder, i.e. to a language to which the UI has been translated. This function will be used by the UI to determine which localization strings to use for a user. For example, a user who has chosen the "fr-ca" locale in the UI (French Canadian) should generally see the UI in French. If the UI is NOT localized into French, she should see it in English. In the unlikely event that the UI is localized into French Canadian, the user should see strings in that language.

Parameters:

sLocaleID - The ID of the locale to be mapped, or an RFC 2616, HTTP/1.1 string on Accept-Language (eg. ja, en-gb;q=0.8, en;q=0.7)

defaultLangID - Default value to be used if the supplied locale does not map to any of the UI supported languages

Returns:

The ID of the supported language corresponding to that locale, or the supplied default language ID if no corresponding language is found

Throws:

XPException

MapLocaleToSupportedUILangID

public java.lang.String MapLocaleToSupportedUILangID(java.lang.String sLocaleID)

Converts from a locale chosen by the user (e.g. en-us) to a language ID supported by the UI. In this context, a valid language ID corresponds to the name of a folder under the "msgs" folder, i.e. to a language to which the UI has been translated. This function will be used by the UI to determine which localization strings to use for a user. For example, a user who has chosen the "fr-ca" locale in the UI (French Canadian) should generally see the UI in French. If the UI is NOT localized into French, she should see it in English. In the unlikely event that the UI is localized into French Canadian, the user should see strings in that language.

Parameters:

sLocaleID - The ID of the locale to be mapped, or an RFC 2616, HTTP/1.1 string on Accept-Language (eg. ja, en-gb;q=0.8, en;q=0.7)

Returns:

The ID of the supported language corresponding to that locale, or the default value ("en") if no matching language is found

Throws:

XPException

TruncateLocaleID

public static java.lang.String TruncateLocaleID(java.lang.String sLocaleID)

An internal use funcation to truncates a locale ID to a language. For example, it will convert "en-us" to "en". If passed a language identifier, it should return the identifier (e.g. "en" will become "en".)

Parameters:

sLocaleID - The ID of the locale to be trucated

Returns:

The ID of the language corresponding to that locale

LoadResources

public void LoadResources()

Loads the resources in all supported languages into an internal hashtable. For every language, there is a thread of execution that handles the loading of resources in that language.

Throws:

XPException

GetString

public java.lang.String GetString(int messageID,
                                  java.lang.String messageFileName,
                                  java.lang.String language)

Returns the string corresponding to the given message ID, message file index or name and the language.

Specified by:

GetString in interface IXPResourceManager

Parameters:

messageID - ID of the message

messageFileName - File Name of the message file that contains the string messages

language - Language of the string messages (e.g. en, fr etc.)

Returns:

String corresponding to the given messsage ID, message file name and the language

Throws:

XPException

GetString

public java.lang.String GetString(int messageID,
                                  java.lang.String messageFileName,
                                  java.lang.String language,
                                  java.lang.Object argValue0)

Returns the string corresponding to the given message ID, message file index or name and the language.

Specified by:

GetString in interface IXPResourceManager

Parameters:

messageID - ID of the message

messageFileName - File Name of the message file that contains the string messages

language - Language of the string messages (e.g. en, fr etc.)

argValue0 - The argument value for the placeholder {0}

Returns:

String corresponding to the given messsage ID, message file index or name, language and the placeholder {0} replaced with the given argument value. value.

Throws:

XPException

GetString

public java.lang.String GetString(int messageID,
                                  java.lang.String messageFileName,
                                  java.lang.String language,
                                  java.lang.Object argValue0,
                                  java.lang.Object argValue1)

Returns the string corresponding to the given message ID, message file index or name and the language.

Specified by:

GetString in interface IXPResourceManager

Parameters:

messageID - ID of the message

messageFileName - File Name of the message file that contains the string messages

language - Language of the string messages (e.g. en, fr etc.)

argValue0 - The argument value for the placeholder {0}

argValue1 - The argument value for the placeholder {1}

Returns:

String corresponding to the given messsage ID, message file index or name, language and the placeholder {0} and {1} replaced with the given argument values.

Throws:

XPException

GetString

public java.lang.String GetString(int messageID,
                                  java.lang.String messageFileName,
                                  java.lang.String language,
                                  java.lang.Object argValue0,
                                  java.lang.Object argValue1,
                                  java.lang.Object argValue2)

Returns the string corresponding to the given message ID, message file index or name and the language.

Specified by:

GetString in interface IXPResourceManager

Parameters:

messageID - ID of the message

messageFileName - File Name of the message file that contains the string messages

language - Language of the string messages (e.g. en, fr etc.)

argValue0 - The argument value for the placeholder {0}

argValue1 - The argument value for the placeholder {1}

argValue2 - The argument value for the placeholder {2}

Returns:

String corresponding to the given messsage ID, message file index or name, language and the placeholder {0}, {1} and {2} replaced with the given argument values.

Throws:

XPException

GetString

public java.lang.String GetString(int messageID,
                                  java.lang.String messageFileName,
                                  java.lang.String language,
                                  java.lang.Object argValue0,
                                  java.lang.Object argValue1,
                                  java.lang.Object argValue2,
                                  java.lang.Object argValue3)

Returns the string corresponding to the given message ID, message file index or name and the language.

Specified by:

GetString in interface IXPResourceManager

Parameters:

messageID - ID of the message

messageFileName - File Name of the message file that contains the string messages

language - Language of the string messages (e.g. en, fr etc.)

argValue0 - The argument value for the placeholder {0}

argValue1 - The argument value for the placeholder {1}

argValue2 - The argument value for the placeholder {2}

argValue3 - The argument value for the placeholder {3}

Returns:

String corresponding to the given messsage ID, message file index or name, language and the placeholder {0}, {1}, {2} and {3} replaced with the given argument values. value.

Throws:

XPException

GetDisplayLanguageFromLocaleID

public java.lang.String GetDisplayLanguageFromLocaleID(java.lang.String sLocale,
                                                       java.lang.String language)

Translates from a locale or language identifier to the human readable string for the language. For instance, it would translate from "en" to "English" for an English speaker, or "en" to "Anglais" for a French speaker. Since it's returning the language name, it would return "English" for "en-us".

Parameters:

sLocale - The locale identifier to be converted to human-readable string

language - Language of the string messages (e.g. en, fr etc.)

Returns:

The human readable string for the language, or the locale identifier if the locale isn't known.

GetDisplayLocaleFromLocaleID

public java.lang.String GetDisplayLocaleFromLocaleID(java.lang.String sLocale,
                                                     java.lang.String language)

Translates from a locale or language identifier to the human readable string for that locale or language. For instance, it would translate from "en" to "English" for an English speaker, or "en" to "Anglais" for a French speaker. Since it's returning the locale name, it would return "U.S. English" for "en-us".

Parameters:

sLocale - The locale identifier to be converted to human-readable

language - Language of the string messages (e.g. en, fr etc.)

Returns:

the human readable string for the locale, or the locale identifier if the locale isn't known.

GetSupportedLocales

public java.lang.String[] GetSupportedLocales(java.lang.String language)

Returns the supported locales that can be used as an argument to GetString(*) methods.

Parameters:

language - supported locale name.

Returns:

An array of strings representing the identifiers of the locales