org.josef.util

Class CResourceBundle

java.lang.Object

org.josef.util.CResourceBundle

All Implemented Interfaces:

Serializable

@Status(stage=PRODUCTION,
        unitTests=PARTIAL)
 @Review(by="Kees Schotanus",
        at="2009-09-28")
 @ThreadSafety(level=NOT_THREAD_SAFE,
              doc="Since JSP Beans are not thread safe either.")
public final class CResourceBundle
extends Object
implements Serializable

A list of resource bundles that represents itself as a single ResourceBundle.
The resource bundles will be searched from added last, to added first. This allows you to organize your properties files in a hierarchy. Add generic resource bundles first and more specific resource bundles later. Now get the resources you need without actually knowing which resource bundle actually contained the resource.
Note: All getters return an object on which no message attribute substitution has taken place (substitution of text within accolades). To perform this substitution the getMessage(...) method.

Version:

1.1 $Revision: 6488 $

Author:

Kees Schotanus

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
CResourceBundle(Locale locale) Constructs this CResourceBundle with an empty list of resource bundles.
CResourceBundle(Locale locale, String resourceBundleName) Constructs this CResourceBundle from the supplied locale and resourceBundleName.
CResourceBundle(String resourceBundleName) Constructs this CResourceBundle from the supplied resourceBundleName, using the default locale.

Method Summary

Modifier and Type	Method and Description
void	addResourceBundles(ResourceBundle... resourceBundles) Adds resource bundles to the list of resource bundles.
void	addResourceBundles(String... resourceBundleNames) Adds resource bundles by name, to the list of resource bundles.
String	format(String messagePattern, Object... messageArguments) Formats the supplied messagePattern with the optionally supplied messageArguments.
boolean	getBoolean(String key) Gets a boolean resource from the list of resource bundles.
boolean	getBoolean(String key, boolean defaultValue) Gets a boolean resource from the list of resource bundles and when this resource does not exist, use the supplied defaultValue.
Date	getDate(String key) Gets a Date resource from the list of resource bundles.
Date	getDate(String key, Date defaultValue) Gets a Date resource from the list of resource bundles and when this resource does not exist, use the supplied defaultValue.
Double	getDouble(String key) Gets a Double resource from the list of resource bundles.
Double	getDouble(String key, Double defaultValue) Gets a Double resource from the list of resource bundles and when this resource does not exist, use the supplied defaultValue.
Integer	getInteger(String key) Gets an Integer resource from the list of resource bundles.
Integer	getInteger(String key, Integer defaultValue) Gets an Integer resource from the list of resource bundles and when this resource does not exist, use the supplied defaultValue.
Locale	getLocale() Gets the locale used by the list of resource bundles.
static String	getLocalizedMessage(Locale locale, String resourceBundleName, String messageKey, Object... messageArguments) Gets the localized message from the resource bundle with the supplied resourceBundleName, using the supplied messageKey.
static String	getLocalizedMessage(ResourceBundle resourceBundle, String messageKey, Object... messageArguments) Gets the localized message from the supplied resourceBundle, using the supplied messageKey.
Long	getLong(String key) Gets a Long resource from the list of resource bundles.
Long	getLong(String key, Long defaultValue) Gets a Long resource from the list of resource bundles and when this resource does not exist, use the supplied defaultValue.
String	getMessage(String key, Object... arguments) Gets a formatted message from the list of resource bundles.
boolean	getRequiredBoolean(String key) Gets a required boolean resource from the list of resource bundles.
Date	getRequiredDate(String key) Gets a required Date resource from the list of resource bundles.
Double	getRequiredDouble(String key) Gets a required Double resource from the list of resource bundles.
Integer	getRequiredInteger(String key) Gets a required Integer resource from the list of resource bundles.
Long	getRequiredLong(String key) Gets a required Long resource from the list of resource bundles.
String	getRequiredString(String key) Gets a required String resource from the list of resource bundles.
String	getString(String key) Gets a String resource from the list of resource bundles.
String	getString(String key, String defaultValue) Gets a String resource from the list of resource bundles and when this resource does not exist, use the supplied defaultValue.
String	toString() Creates a String representation of this bundle of resource bundles.

Methods inherited from class java.lang.Object

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

Constructor Detail

CResourceBundle

public CResourceBundle(String resourceBundleName)

Constructs this CResourceBundle from the supplied resourceBundleName, using the default locale.
You would normally use this constructor for properties files that contain configuration, independent of a locale.
All subsequent bundles added using addResourceBundles(String...) will use the same locale.

Parameters:

resourceBundleName - Name of the resource bundle file.
Supplying "org.josef.util.UtilMessages" would use the file org/josef/util/UtilMessages.properties.

Throws:

IllegalArgumentException - When the supplied resourceBundleName is empty.

MissingResourceException - When the resource bundle could not be located.

NullPointerException - When the supplied resourceBundleName is null.

CResourceBundle

public CResourceBundle(Locale locale)

Constructs this CResourceBundle with an empty list of resource bundles.

Parameters:

locale - The locale to localize the resources or null to use the default locale.

CResourceBundle

public CResourceBundle(Locale locale,
                       String resourceBundleName)

Constructs this CResourceBundle from the supplied locale and resourceBundleName.
All subsequent bundles added using addResourceBundles(String...) will use the same locale.

Parameters:

locale - The locale to localize the resources or null to use the default locale.

resourceBundleName - Name of the resource bundle file.
Supplying "org.josef.util.UtilMessages" would use the file org/josef/util/UtilMessages.properties.

Throws:

IllegalArgumentException - When the supplied resourceBundleName is empty.

MissingResourceException - When the resource bundle could not be located.

NullPointerException - When the supplied resourceBundleName is null.

Method Detail

addResourceBundles

public void addResourceBundles(String... resourceBundleNames)

Adds resource bundles by name, to the list of resource bundles.
Normally we can't access resource bundle names when loaded by another class loader but we try to get the class that called CResourceBundle's method and use the class loader of the calling class to circumvent this problem.

Parameters:

resourceBundleNames - The names of the resource bundles to add.
All added bundles probably should have the same locale as supplied at construction time but this is not checked.

Throws:

IllegalArgumentException - When the supplied resourceBundleNames is empty.

NullPointerException - When the supplied resourceBundleNames is null.

addResourceBundles

public void addResourceBundles(ResourceBundle... resourceBundles)

Adds resource bundles to the list of resource bundles.

Parameters:

resourceBundles - The resource bundles to add.
All added bundles probably should have the same locale as supplied at construction time but this is not checked.

Throws:

IllegalArgumentException - When the supplied resourceBundles is empty.

NullPointerException - When the supplied resourceBundles is null.

getLocale

public Locale getLocale()

Gets the locale used by the list of resource bundles.

Returns:

The locale used by the list of resource bundles.

getBoolean

public boolean getBoolean(String key)

Gets a boolean resource from the list of resource bundles.

Parameters:

key - Key to the boolean resource.

Returns:

Boolean resource or false when the key could not be located or when the key could be located but the resource is not a boolean.
In the latter case a warning will be logged.

Throws:

IllegalArgumentException - When the supplied key is empty.

NullPointerException - When the supplied key is null.

See Also:

Boolean.parseBoolean(String)

getBoolean

public boolean getBoolean(String key,
                          boolean defaultValue)

Gets a boolean resource from the list of resource bundles and when this resource does not exist, use the supplied defaultValue.

Parameters:

key - Key to the boolean resource.

defaultValue - Default value in case the key is missing or when the located resource is not a boolean.

Returns:

Boolean resource or the supplied default value when the supplied key does not exist or when the key does exist but the resource is not a boolean.
In the latter case a warning will be logged.

Throws:

IllegalArgumentException - When the supplied key is empty.

NullPointerException - When the supplied key is null.

See Also:

Boolean.parseBoolean(String)

getRequiredBoolean

public boolean getRequiredBoolean(String key)

Gets a required boolean resource from the list of resource bundles.

Parameters:

key - Key to the boolean resource.

Returns:

Boolean resource.

Throws:

IllegalArgumentException - When the supplied key is empty or when the retrieved resource could not be converted to a boolean value.

MissingResourceException - When the key does not exist.

NullPointerException - When the supplied key is null.

See Also:

Boolean.parseBoolean(String)

getDate

public Date getDate(String key)

Gets a Date resource from the list of resource bundles.

Parameters:

key - Key to the Date resource.

Returns:

Date resource or null when the key could not be located or when the key could be located but the resource is not a Date.
In the latter case a warning will be logged.

Throws:

IllegalArgumentException - When the supplied key is empty.

NullPointerException - When the supplied key is null.

See Also:

Date.valueOf(String)

getDate

public Date getDate(String key,
                    Date defaultValue)

Gets a Date resource from the list of resource bundles and when this resource does not exist, use the supplied defaultValue.

Parameters:

key - Key to the Date resource.

defaultValue - Default value in case the key is missing or when the located resource is not a Date.

Returns:

Date resource or the supplied default value when the supplied key does not exist or when the key does exist but the resource is not a Date.
In the latter case a warning will be logged.

Throws:

IllegalArgumentException - When the supplied key is empty.

NullPointerException - When the supplied key is null.

See Also:

Date.valueOf(String)

getRequiredDate

public Date getRequiredDate(String key)

Gets a required Date resource from the list of resource bundles.

Parameters:

key - Key to the Date resource.

Returns:

Date resource.

Throws:

IllegalArgumentException - When the supplied key is empty or when the retrieved resource could not be converted to a Date value.

MissingResourceException - When the key does not exist.

NullPointerException - When the supplied key is null.

See Also:

Date.valueOf(String)

getInteger

public Integer getInteger(String key)

Gets an Integer resource from the list of resource bundles.

Parameters:

key - Key to the Integer resource.

Returns:

Integer resource or null when the key could not be located or when the key could be located but the resource is not an Integer.
In the latter case a warning will be logged.

Throws:

IllegalArgumentException - When the supplied key is empty.

NullPointerException - When the supplied key is null.

See Also:

Integer.valueOf(String)

getInteger

public Integer getInteger(String key,
                          Integer defaultValue)

Gets an Integer resource from the list of resource bundles and when this resource does not exist, use the supplied defaultValue.

Parameters:

key - Key to the Integer resource.

defaultValue - Default value in case the key is missing or when the located resource is not an Integer.

Returns:

Integer resource or the supplied default value when the supplied key does not exist or when the key does exist but the resource is not an Integer.
In the latter case a warning will be logged.

Throws:

IllegalArgumentException - When the supplied key is empty.

NullPointerException - When the supplied key is null.

See Also:

Integer.valueOf(String)

getRequiredInteger

public Integer getRequiredInteger(String key)

Gets a required Integer resource from the list of resource bundles.

Parameters:

key - Key to the Integer resource.

Returns:

Integer resource.

Throws:

IllegalArgumentException - When the supplied key is empty or when the retrieved resource could not be converted to an Integer value.

MissingResourceException - When the key does not exist.

NullPointerException - When the supplied key is null.

See Also:

Integer.valueOf(String)

getLong

public Long getLong(String key)

Gets a Long resource from the list of resource bundles.

Parameters:

key - Key to the Long resource.

Returns:

Long resource or null when the key could not be located or when the key could be located but the resource is not a Long.
In the latter case a warning will be logged.

Throws:

IllegalArgumentException - When the supplied key is empty.

NullPointerException - When the supplied key is null.

See Also:

Long.valueOf(String)

getLong

public Long getLong(String key,
                    Long defaultValue)

Gets a Long resource from the list of resource bundles and when this resource does not exist, use the supplied defaultValue.

Parameters:

key - Key to the Long resource.

defaultValue - Default value in case the key is missing or when the located resource is not a Long.

Returns:

Long resource or the supplied default value when the supplied key does not exist or when the key does exist but the resource is not a Long.
In the latter case a warning will be logged.

Throws:

IllegalArgumentException - When the supplied key is empty.

NullPointerException - When the supplied key is null.

See Also:

Long.valueOf(String)

getRequiredLong

public Long getRequiredLong(String key)

Gets a required Long resource from the list of resource bundles.

Parameters:

key - Key to the Long resource.

Returns:

Long resource.

Throws:

IllegalArgumentException - When the supplied key is empty or when the retrieved resource could not be converted to a Long value.

MissingResourceException - When the key does not exist.

NullPointerException - When the supplied key is null.

See Also:

Long.valueOf(String)

getDouble

public Double getDouble(String key)

Gets a Double resource from the list of resource bundles.

Parameters:

key - Key to the Double resource.

Returns:

Double resource or null when the key could not be located or when the key could be located but the resource is not a Double.
In the latter case a warning will be logged.

Throws:

IllegalArgumentException - When the supplied key is empty.

NullPointerException - When the supplied key is null.

See Also:

Double.valueOf(String)

getDouble

public Double getDouble(String key,
                        Double defaultValue)

Gets a Double resource from the list of resource bundles and when this resource does not exist, use the supplied defaultValue.
The resource must have an English locale.

Parameters:

key - Key to the Double resource.

defaultValue - Default value in case the key is missing or when the located resource is not a Double.

Returns:

Double resource or the supplied default value when the supplied key does not exist or when the key does exist but the resource is not a Double.
In the latter case a warning will be logged.

Throws:

IllegalArgumentException - When the supplied key is empty.

NullPointerException - When the supplied key is null.

See Also:

Double.valueOf(String)

getRequiredDouble

public Double getRequiredDouble(String key)

Gets a required Double resource from the list of resource bundles.
The resource must have an English locale.

Parameters:

key - Key to the double resource.

Returns:

Double resource.

Throws:

IllegalArgumentException - When the supplied key is empty or when the retrieved resource could not be converted to a Double value.

MissingResourceException - When the key does not exist.

NullPointerException - When the supplied key is null.

See Also:

Double.valueOf(String)

getString

public String getString(String key)

Gets a String resource from the list of resource bundles.

Parameters:

key - Key to the String resource.

Returns:

String resource or null when the resource could not be located.

Throws:

IllegalArgumentException - When the supplied key is empty.

NullPointerException - When the supplied key is null.

getString

public String getString(String key,
                        String defaultValue)

Gets a String resource from the list of resource bundles and when this resource does not exist, use the supplied defaultValue.

Parameters:

key - Key to the String resource.

defaultValue - Default value in case the key does not exist.

Returns:

String resource or the supplied default value when the supplied key does not exist.

Throws:

IllegalArgumentException - When the supplied key is empty.

NullPointerException - When the supplied key is null.

getRequiredString

public String getRequiredString(String key)

Gets a required String resource from the list of resource bundles.
When the key is missing an error will be logged.

Parameters:

key - Key to the String resource.

Returns:

String resource.

Throws:

IllegalArgumentException - When the supplied key is empty.

MissingResourceException - When the key does not exist.

NullPointerException - When the supplied key is null.

getMessage

public String getMessage(String key,
                         Object... arguments)

Gets a formatted message from the list of resource bundles.

Parameters:

key - Key to the String resource.

arguments - Message arguments that will be substituted in the retrieved string resource.
May be null, in which case no message arguments will be substituted.

Returns:

String resource or the supplied key when the resource could not be located.

Throws:

IllegalArgumentException - When the supplied key is empty.

NullPointerException - When the supplied key is null.

format

public String format(String messagePattern,
                     Object... messageArguments)

Formats the supplied messagePattern with the optionally supplied messageArguments.

Parameters:

messagePattern - The message pattern.
For example: Processing record {0} of {1}.

messageArguments - The arguments that must be inserted into the supplied messagePattern.
Message arguments may contain object of type Localizable that will be localized before being inserted into the supplied messagePattern.

Returns:

The localized message or simply the supplied messagePattern when the supplied messageArguments is empty.

Throws:

NullPointerException - When the supplied messagePattern is null.

getLocalizedMessage

public static String getLocalizedMessage(Locale locale,
                                         String resourceBundleName,
                                         String messageKey,
                                         Object... messageArguments)

Gets the localized message from the resource bundle with the supplied resourceBundleName, using the supplied messageKey.
Post condition: A log message will be written when a message could not be retrieved.

Parameters:

locale - The locale used to translate the message.
When null is supplied, the default locale will be used.

resourceBundleName - The name of the ResourceBundle that contains the message to be localized.

messageKey - Key of the message to find and localize.

messageArguments - The message arguments that will be inserted into the localized message.

Returns:

The localized message for the supplied locale.
When the localized message could not be retrieved from the resource bundle, the message key is returned hence this method never throws a MissingResourceException.

Throws:

IllegalArgumentException - When either the supplied resourceBundleName or messageKey is empty.

NullPointerException - When either the supplied resourceBundleName or messageKey is null.

getLocalizedMessage

public static String getLocalizedMessage(ResourceBundle resourceBundle,
                                         String messageKey,
                                         Object... messageArguments)

Gets the localized message from the supplied resourceBundle, using the supplied messageKey.
Post condition: A log message will be written when a message could not be retrieved.

Parameters:

resourceBundle - The ResourceBundle that contains the message to be localized.

messageKey - Key of the message to find and localize.

messageArguments - The message arguments that will be inserted into the localized message.

Returns:

The localized message for the supplied messageKey.
When the localized message could not be retrieved from the resource bundle a standard message containing the message key is returned hence this method never throws a MissingResourceException.

Throws:

IllegalArgumentException - When the supplied messageKey is empty.

NullPointerException - When either the supplied resourceBundle or messageKey is null.

toString

public String toString()

Creates a String representation of this bundle of resource bundles.

Overrides:

toString in class Object

Returns:

String representation of this bundle of resource bundles.