com.ca.commons.cbutil
Class CBResourceBundle

java.lang.Object
  |
  +--com.ca.commons.cbutil.CBResourceBundle

public class CBResourceBundle

extends java.lang.Object

Java's PropertyResourceBundle class is tragically bad. Why a class intended for i18n use deliberately restricts itself to 8859-1 characters, while using a bizarre unicode escaping format rather than utf8, is beyond me (and certainly beyond any translators I need to send stuff to.)

This class is a reimplementation that automatically selects whether a file is 16bit unicode, utf-8, or local character encoding, and loads it accordingly. Otherwise it is intended to be functionally very similar to PropertiesResourceBundle.

Note that this class does not extend ResourceBundle, as ResourceBundle is difficult to extend - all the functionality is hidden away in private methods. So even though ResourceBundle does some neat things, we won't be doing anything but a bare bones rewrite here. Important: This uses a simplified form of the properties file - keys and phrases are separated by an '=' sign, and while, for backward compatibility, keys can have escaped characters, except for '=', they don't have to. A further restriction is that the '=' sign may not be immediately preceeded by an escaped escape character (i.e. '\\=' is illegal) - the '=' sign must be preceeded by a space character in this case. Any space characters at the start and end of a key/description are trimmed.

e.g. [values in square brackets represent byte values within the file] potato = kartoffel // normal ascii (german) help = [30 d8 30 eb 30d7] // 16 bit unicode (japanese) file = [e6 96 87 e6 a1 a3] // utf-8 (chinese)

Constructor Summary

CBResourceBundle(java.lang.String baseName)
This creates a Resource bundle using only the name of the the resource bundle (e.g.

CBResourceBundle(java.lang.String baseName, java.util.Locale locale)
This creates a Resource bundle the name of the the resource bundle (e.g.

CBResourceBundle(java.lang.String baseName, java.util.Locale locale, java.lang.ClassLoader loader)
This creates a Resource bundle the name of the the resource bundle (e.g.

Method Summary

java.lang.Object	get(java.lang.Object key) Returns the object corresponding to a given key.
protected static java.util.Vector	getBundleNames(java.lang.String baseName, java.util.Locale locale) Calculate the bundles along the search path from the base bundle to the bundle specified by baseName and locale.
java.util.Enumeration	getKeys() returns the translation keys.
java.lang.Object	getObject(java.lang.Object key) Returns the object corresponding to a given key.
java.lang.String	getString(java.lang.String key) Convenience class returning a particular object as a String.
java.util.Enumeration	keys() returns the translation keys.
protected void	loadBundle(java.lang.String baseName, java.util.Locale locale, java.lang.ClassLoader loader) This method searches through all the valid permutations of the base bundle name (modified for locale - e.g.
protected boolean	loadData(java.net.URL url) This loads the data from a translation file, checking on the way what file format it is in.
protected boolean	parseData(java.lang.String text) parses the byte array as per a normal resource file (i.e. looking for key/data pairs seperated by an unescaped '=' sign) after first converting the byte array into a String, using whichever language encoding (unicode16, utf8, locale-specific) seems appropriate.
protected java.lang.String	unescape(java.lang.String escapeMe) Removes all escapes ('\?'

Methods inherited from class java.lang.Object

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

Constructor Detail

CBResourceBundle

public CBResourceBundle(java.lang.String baseName)

This creates a Resource bundle using only the name of the the resource bundle (e.g. "language.JX"). It then uses the default locale and resource loader to track down the appropriate translation file.

Parameters:

baseName - the name of the translation file to look up. this name is extended using the standard locality rules to try to find localised files (e.g. "language.JX" becomes language/JX_fr_CA in french-speaking canada).

CBResourceBundle

public CBResourceBundle(java.lang.String baseName,
                        java.util.Locale locale)

This creates a Resource bundle the name of the the resource bundle (e.g. "language.JX"). It then uses the specified locale to track down the appropriate translation file.

Parameters:

baseName - the name of the translation file to look up. this name is extended using the standard locality rules to try to find localised files (e.g. "language.JX" becomes language/JX_fr_CA in french-speaking canada).

locale - a specific locale to use in place of the default system locale.

CBResourceBundle

public CBResourceBundle(java.lang.String baseName,
                        java.util.Locale locale,
                        java.lang.ClassLoader loader)

This creates a Resource bundle the name of the the resource bundle (e.g. "language.JX"). It then uses the specified locale to track down the appropriate translation file, and teh specified class loader to retrieve the file.

Parameters:

baseName - the name of the translation file to look up. this name is extended using the standard locality rules to try to find localised files (e.g. "language.JX" becomes language/JX_fr_CA in french-speaking canada).

locale - a specific locale to use in place of the default system locale.

loader - a custom class loader (such as CBClassLoader) used to retrieve the translation file.

Method Detail

loadBundle

protected void loadBundle(java.lang.String baseName,
                          java.util.Locale locale,
                          java.lang.ClassLoader loader)

This method searches through all the valid permutations of the base bundle name (modified for locale - e.g. JX_fr_CA.properties, JX_fr.properties, and JX.properties...).

If successful, it loads the data (the translation strings) into a local data store (Hashtable).

Parameters:

baseName - the name of the translation file to look up. this name is extended using the standard locality rules to try to find localised files (e.g. "language.JX" becomes language/JX_fr_CA in french-speaking canada).

locale - a specific locale to use in place of the default system locale.

loader - a custom class loader (such as CBClassLoader) used to retrieve the translation file.

getBundleNames

protected static java.util.Vector getBundleNames(java.lang.String baseName,
                                                 java.util.Locale locale)

Calculate the bundles along the search path from the base bundle to the bundle specified by baseName and locale.

Parameters:

baseName - the base bundle name

locale - the locale

loadData

protected boolean loadData(java.net.URL url)

This loads the data from a translation file, checking on the way what file format it is in. (UTF-8, 16bit unicode, or local encoding).

Parameters:

url - the URL to read the data InputStream from.

Returns:

whether the load data operation was successfull, or whether it was interupted (for whatever reason; no file, error reading file, bad encoding, yadda yadda yadda).

parseData

protected boolean parseData(java.lang.String text)

parses the byte array as per a normal resource file (i.e. looking for key/data pairs seperated by an unescaped '=' sign) after first converting the byte array into a String, using whichever language encoding (unicode16, utf8, locale-specific) seems appropriate.

unescape

protected java.lang.String unescape(java.lang.String escapeMe)

Removes all escapes ('\?' -> '?') from a string. -> Not particularly efficient, but o.k. for short strings.

keys

public java.util.Enumeration keys()

returns the translation keys.

Returns:

an Enumeration of all the known keys (usually translatable strings).

getKeys

public java.util.Enumeration getKeys()

returns the translation keys. Synonym for 'keys()', kept for compatibility with ResourceBundle.

Returns:

an Enumeration of all the known keys (usually translatable strings).

get

public java.lang.Object get(java.lang.Object key)

Returns the object corresponding to a given key.

Parameters:

key - the original text to translate/look up

Returns:

the corresponding translation/object

getObject

public java.lang.Object getObject(java.lang.Object key)

Returns the object corresponding to a given key. kept for compatibility with ResourceBundle.

Parameters:

key - the original text to translate/look up

Returns:

the corresponding translation/object

getString

public java.lang.String getString(java.lang.String key)

Convenience class returning a particular object as a String. If the object was a String already it is passed back unchanged, otherwise 'toString()' is called on the object before returning. This class never throws a ClassCastException.

Parameters:

key - the original text to translate/look up

Returns:

the corresponding translation/object as a String