com.highqsoft.util

Class PropertyBundle

java.lang.Object

com.highqsoft.util.PropertyBundle

Direct Known Subclasses:

EnhancedPropertyResource

public abstract class PropertyBundle
extends java.lang.Object

Resource bundles contain locale-specific objects. When your program needs a locale-specific resource, a String for example, your program can load it from the resource bundle that is appropriate for the current user's locale. In this way, you can write program code that is largely independent of the user's locale isolating most, if not all, of the locale-specific information in resource bundles.

This allows you to write programs that can:

• be easily localized, or translated, into different languages
• handle multiple locales at once
• be easily modified later to support even more locales

One resource bundle is, conceptually, a set of related classes that inherit from PropertyBundle. Each related subclass of PropertyBundle has the same base name plus an additional component that identifies its locale. For example, suppose your resource bundle is named MyResources. The first class you are likely to write is the default resource bundle which simply has the same name as its family--MyResources. You can also provide as many related locale-specific classes as you need: for example, perhaps you would provide a German one named MyResources_de.

Each related subclass of PropertyBundle contains the same items, but the items have been translated for the locale represented by that PropertyBundle subclass. For example, both MyResources and MyResources_de may have a String that's used on a button for confirming operations. In MyResources the String may contain OK and in MyResources_de it may contain Gut.

If there are different resources for different countries, you can make specializations: for example, MyResources_de_CH is the German language (de) in Switzerland (CH). If you want to only modify some of the resources in the specialization, you can do so.

When your program needs a locale-specific object, it loads the PropertyBundle class using the getBundle method:

 PropertyBundle myResources =
      PropertyBundle.getBundle("MyResources", currentLocale);
 

The first argument specifies the family name of the resource bundle that contains the object in question. The second argument indicates the desired locale. getBundle uses these two arguments to construct the name of the PropertyBundle subclass it should load as follows.

The resource bundle lookup searches for classes with various suffixes on the basis of (1) the desired locale and (2) the default locale (baseclass), in the following order from lower-level (more specific) to parent-level (less specific):

baseclass + "_" + language1 + "_" + country1 + "_" + variant1
baseclass + "_" + language1 + "_" + country1
baseclass + "_" + language1
baseclass
baseclass + "_" + language2 + "_" + country2 + "_" + variant2
baseclass + "_" + language2 + "_" + country2
baseclass + "_" + language2

The result of the lookup is a class, but that class may be backed by a property file on disk. If a lookup fails, getBundle() throws a MissingResourceException.

The baseclass must be fully qualified (for example, myPackage.MyResources, not just MyResources). It must also be accessable by your code; it cannot be a class that is private to the package where PropertyBundle.getBundle is called.

Note: PropertyBundle are used internally in accessing NumberFormats, Collations, and so on. The lookup strategy is the same.

Resource bundles contain key/value pairs. The keys uniquely identify a locale-specific object in the bundle. Here's an example of a ListPropertyBundle that contains two key/value pairs:

 class MyResource extends ListPropertyBundle {
      public Object[][] getContents() {
              return contents;
      }
      static final Object[][] contents = {
      // LOCALIZE THIS
              {"OkKey", "OK"},
              {"CancelKey", "Cancel"},
      // END OF MATERIAL TO LOCALIZE
      };
 }
 

Keys are always Strings. In this example, the keys are OkKey and CancelKey. In the above example, the values are also Strings--OK and Cancel--but they don't have to be. The values can be any type of object.

You retrieve an object from resource bundle using the appropriate getter method. Because OkKey and CancelKey are both strings, you would use getString to retrieve them:

 button1 = new Button(myPropertyBundle.getString("OkKey"));
 button2 = new Button(myPropertyBundle.getString("CancelKey"));
 

The getter methods all require the key as an argument and return the object if found. If the object is not found, the getter method throws a MissingResourceException.

Besides getString; PropertyBundle supports a number of other methods for getting different types of objects such as getStringArray. If you don't have an object that matches one of these methods, you can use getObject and cast the result to the appropriate type. For example:

 int[] myIntegers = (int[]) myResources.getObject("intList");
 

NOTE: You should always supply a baseclass with no suffixes. This will be the class of "last resort", if a locale is requested that does not exist. For example, below we have a class MyResources. It happens to contain US strings, so we don't have to have an explicit MyResource_en or MyResource_en_US.

The JDK provides two subclasses of PropertyBundle, ListPropertyBundle and EnhancedPropertyBundle, that provide a fairly simple way to create resources. (Once serialization is fully integrated, we will provide another way.) As you saw briefly in a prevous example, ListPropertyBundle manages its resource as a List of key/value pairs. EnhancedPropertyBundle uses a properties file to manage its resources.

If ListPropertyBundle or EnhancedPropertyBundle do not suit your needs, you can write your own PropertyBundle subclass. Your subclasses must overrde two methods: handleGetObject and getKeys().

The following is a very simple example of a PropertyBundle subclass, MyResources, that manages two resources (for a larger number of resources you would probably use a Hashtable). Notice that if the key is not found, handleGetObject must return null. Notice also that you don't need to supply a value if a "parent-level" PropertyBundle handles the same key with the same value (as in United Kingdom below).

Example:

 // English language, United States
 abstract class MyResources extends PropertyBundle {
     public Object handleGetObject(String key) {
         if (key.equals("okKey")) return "Ok";
         if (key.equals("cancelKey")) return "Cancel";
     return null;
     }
 }

 // German language
 public class MyResources_de extends MyResources {
     public Object handleGetObject(String key) {
         if (key.equals("okKey")) return "Gut";
         if (key.equals("cancelKey")) return "Vernichten";
         return null;
     }
 }

 // English language, United Kingdom (Great Britain)
 public class MyResources_en_GB extends MyResources {
     public Object handleGetObject(String key) {
         // don't need okKey, since parent level handles it.
         if (key.equals("cancelKey")) return "Dispose";
         return null;
     }
 }
 

You do not have to restrict yourself to using a single family of PropertyBundles. For example, you could have a set of bundles for exception messages, ExceptionResources (ExceptionResources_fr, ExceptionResources_de, ...), and one for widgets, WidgetResource (WidgetResources_fr, WidgetResources_de, ...); breaking up the resources however you like.

See Also:

ListPropertyBundle, EnhancedPropertyBundle, MissingResourceException

Field Summary

Fields

Modifier and Type	Field and Description
protected PropertyBundle	parent The parent bundle is consulted by getObject when this bundle does not contain a particular resource.

Constructor Summary

Constructors

Constructor and Description
PropertyBundle()

Method Summary

Methods

Modifier and Type	Method and Description
protected static void	debug(java.lang.String str)
boolean	getBooleanValue(java.lang.String key) Get a boolean value from bundle.
boolean	getBooleanValue(java.lang.String key, boolean theDefault) Get a boolean value from bundle.
static PropertyBundle	getBundle(java.lang.String baseName) Get the appropriate PropertyBundle subclass.
static PropertyBundle	getBundle(java.lang.String baseName, java.util.Locale locale) Get the appropriate PropertyBundle subclass.
static PropertyBundle	getBundle(java.lang.String baseName, ResourceComponentFactoryable obj) Get the appropriate PropertyBundle subclass.
static PropertyBundle	getBundle(java.lang.String baseName, ResourceComponentFactoryable obj, java.util.Locale locale) Get the appropriate PropertyBundle subclass.
byte	getByteValue(java.lang.String key) Get a byte value from bundle.
byte	getByteValue(java.lang.String key, byte theDefault) Get a byte value from bundle.
double	getdoubleValue(java.lang.String key) Get a double value from bundle.
double	getDoubleValue(java.lang.String key, double theDefault) Get a double value from bundle.
float	getFloatValue(java.lang.String key) Get a float value from bundle.
float	getFloatValue(java.lang.String key, float theDefault) Get a float value from bundle.
int	getIntValue(java.lang.String key) Get a int value from bundle.
int	getIntValue(java.lang.String key, int theDefault) Get a int value from bundle.
abstract java.util.Enumeration	getKeys() Return an enumeration of the keys.
java.util.Locale	getLocale() Return the Locale for this PropertyBundle.
long	getLongValue(java.lang.String key) Get a long value from bundle.
long	getLongValue(java.lang.String key, long theDefault) Get a long value from bundle.
java.lang.Object	getObject(java.lang.String key) Get an object from a PropertyBundle.
java.lang.String	getString(java.lang.String key) Get an object from a PropertyBundle.
java.lang.String[]	getStringArray(java.lang.String key) Get an object from a PropertyBundle.
java.lang.String	getStringValue(java.lang.String key) Get a string value from bundle.
java.lang.String	getStringValue(java.lang.String key, java.lang.String theDefault) Get a string value from bundle.
protected abstract java.lang.Object	handleGetObject(java.lang.String key) Get an object from a PropertyBundle.
protected void	setParent(PropertyBundle parent) Set the parent bundle of this bundle.

Methods inherited from class java.lang.Object

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

Field Detail

parent

protected PropertyBundle parent

The parent bundle is consulted by getObject when this bundle does not contain a particular resource.

Constructor Detail

PropertyBundle

public PropertyBundle()

Method Detail

getString

public final java.lang.String getString(java.lang.String key)
                                 throws java.util.MissingResourceException

Get an object from a PropertyBundle.
Convenience method to save casting.

Parameters:

key - see class description.

Throws:

java.util.MissingResourceException

getStringValue

public final java.lang.String getStringValue(java.lang.String key)

Get a string value from bundle.

Parameters:

key - Keyword value.

getStringValue

public final java.lang.String getStringValue(java.lang.String key,
                              java.lang.String theDefault)

Get a string value from bundle.

Parameters:

key - Keyword value.

default - The default value that is returned if the keyword was not found.

getIntValue

public final int getIntValue(java.lang.String key)

Get a int value from bundle.

Parameters:

key - Keyword value.

getIntValue

public final int getIntValue(java.lang.String key,
              int theDefault)

Get a int value from bundle.

Parameters:

key - Keyword value.

default - The default value that is returned if the keyword was not found.

getLongValue

public final long getLongValue(java.lang.String key)

Get a long value from bundle.

Parameters:

key - Keyword value.

getLongValue

public final long getLongValue(java.lang.String key,
                long theDefault)

Get a long value from bundle.

Parameters:

key - Keyword value.

default - The default value that is returned if the keyword was not found.

getFloatValue

public final float getFloatValue(java.lang.String key)

Get a float value from bundle.

Parameters:

key - Keyword value.

getFloatValue

public final float getFloatValue(java.lang.String key,
                  float theDefault)

Get a float value from bundle.

Parameters:

key - Keyword value.

default - The default value that is returned if the keyword was not found.

getdoubleValue

public final double getdoubleValue(java.lang.String key)

Get a double value from bundle.

Parameters:

key - Keyword value.

getDoubleValue

public final double getDoubleValue(java.lang.String key,
                    double theDefault)

Get a double value from bundle.

Parameters:

key - Keyword value.

default - The default value that is returned if the keyword was not found.

getByteValue

public final byte getByteValue(java.lang.String key)

Get a byte value from bundle.

Parameters:

key - Keyword value.

getByteValue

public final byte getByteValue(java.lang.String key,
                byte theDefault)

Get a byte value from bundle.

Parameters:

key - Keyword value.

default - The default value that is returned if the keyword was not found.

getBooleanValue

public final boolean getBooleanValue(java.lang.String key)

Get a boolean value from bundle.

Parameters:

key - Keyword value.

getBooleanValue

public final boolean getBooleanValue(java.lang.String key,
                      boolean theDefault)

Get a boolean value from bundle.

Parameters:

key - Keyword value.

default - The default value that is returned if the keyword was not found.

getStringArray

public final java.lang.String[] getStringArray(java.lang.String key)
                                        throws java.util.MissingResourceException

Get an object from a PropertyBundle.
Convenience method to save casting.

Parameters:

key - see class description.

Throws:

java.util.MissingResourceException

getObject

public final java.lang.Object getObject(java.lang.String key)
                                 throws java.util.MissingResourceException

Get an object from a PropertyBundle.

Parameters:

key - see class description.

Throws:

java.util.MissingResourceException

getBundle

public static final PropertyBundle getBundle(java.lang.String baseName)
                                      throws java.util.MissingResourceException

Get the appropriate PropertyBundle subclass.

Parameters:

baseName - see class description.

Throws:

java.util.MissingResourceException

getBundle

public static final PropertyBundle getBundle(java.lang.String baseName,
                       ResourceComponentFactoryable obj)
                                      throws java.util.MissingResourceException

Get the appropriate PropertyBundle subclass.

Parameters:

baseName - see class description.

obj - The object that holds this resource.

Throws:

java.util.MissingResourceException

getBundle

public static final PropertyBundle getBundle(java.lang.String baseName,
                       java.util.Locale locale)

Get the appropriate PropertyBundle subclass.

Parameters:

baseName - see class description.

locale - see class description.

getBundle

public static final PropertyBundle getBundle(java.lang.String baseName,
                       ResourceComponentFactoryable obj,
                       java.util.Locale locale)

Get the appropriate PropertyBundle subclass.

Parameters:

baseName - see class description.

obj - The object that holds this resource.

locale - see class description.

getLocale

public java.util.Locale getLocale()

Return the Locale for this PropertyBundle. (This function can be used after a call to getBundle() to determine whether the PropertyBundle returned really corresponds to the requested locale or is a fallback.)

setParent

protected void setParent(PropertyBundle parent)

Set the parent bundle of this bundle. The parent bundle is searched by getObject when this bundle does not contain a particular resource.

Parameters:

parent - this bundle's parent bundle.

handleGetObject

protected abstract java.lang.Object handleGetObject(java.lang.String key)
                                             throws java.util.MissingResourceException

Get an object from a PropertyBundle. NOTE: Subclasses must override.

Parameters:

key - see class description.

Throws:

java.util.MissingResourceException

getKeys

public abstract java.util.Enumeration getKeys()

Return an enumeration of the keys. NOTE: Subclasses must override.

debug

protected static void debug(java.lang.String str)