org.grinvin.util

Class InternationalizedProperties


public class InternationalizedProperties
extends java.lang.Object

Internationalized version of the standard Java java.util.Properties class. Bundles a set of properties with internationalized values. A property can be retrieved for a given key and locale. When no locale is explicitly indicated, a default locale is used. This default corresponds to the default locale of the application, but this may be changed by means of the method setDefaultLocale(Locale).

Properties are stored in a hierarchy based on locale. When searching for a property a list of subsequently less specific locales is used until a match is found or no match exists. For example, when the current locale is nl_be_UNIX properties are looked for in locales nl_be_UNIX, nl_be, nl and finally the default 'empty' locale.

This class has an interface similar to that of the standard class java.util.Properties but does not extend it. Files saved by the one class cannot be loaded by the other.

The methods load(InputStream) and save(OutputStream) load and save internationalized properties in a simple XML-format that conforms to the following DTD.

    <!ELEMENT resources ( properties, node* ) >

    <!ELEMENT node ( properties, node* ) >
    <!ATTLIST node name CDATA #REQUIRED >

    <!ELEMENT properties ( entry* ) >
    <!ELEMENT entry (#PCDATA) >
    <!ATTLIST entry key CDATA #REQUIRED >
 
Each node corresponds to a locale with a given name. A child node corresponds to a locale that is more specific than that of its parent. The properties element has the same structure as the one used in the standard Java java.util.Properties class.

Methods toElement and fromElement(Element) provide conversion to and from JDOM elements, using a similar format, except that instead of resources a different top level element can be used.

Constructor Summary

InternationalizedProperties()
Default constructor.

Method Summary

void
fromElement(Element element)
Load properties from the given JDOM-element and adds them to the list.
String
getProperty(String key)
Searches for a property with the specified key.
String
getProperty(String key, Locale locale)
Searches for the property with the specified key in this property list, starting with the given locale.
String
getProperty(String key, Locale locale, String defaultValue)
Searches for the property with the specified key in this property list, starting with the given locale.
String
getProperty(String key, String defaultValue)
Searches for a property with the specified key.
void
load(InputStream input)
Loads the properties from the given input stream and adds them to this list.
void
registerLocale(Locale locale)
Registers a locale with this property list.
void
save(OutputStream out)
Writes this property list to the given output stream.
void
setDefaultLocale(Locale locale)
Set the default locale to be used for this list.
void
setProperty(String key, String value)
Adds a given property/value pair for the default locale.
void
setProperty(String key, String value, Locale locale)
Adds a given property/value pair for the given locale.
Element
toElement()
Convert the current list of properties to a JDOM-element with the default name resources.
Element
toElement(String name)
Convert the current list of properties to a JDOM-element of the given name.

Constructor Details

InternationalizedProperties

public InternationalizedProperties()
Default constructor. Creates an empty property list.

Method Details

fromElement

public void fromElement(Element element)
Load properties from the given JDOM-element and adds them to the list.

getProperty

public String getProperty(String key)
Searches for a property with the specified key. Starts the search with the default locale. Returns null when the property is not found.
Parameters:
key - the property key.

getProperty

public String getProperty(String key,
                          Locale locale)
Searches for the property with the specified key in this property list, starting with the given locale. The method returns null if the property is not found.
Parameters:
key - the property key.
locale - the locale to be searched

getProperty

public String getProperty(String key,
                          Locale locale,
                          String defaultValue)
Searches for the property with the specified key in this property list, starting with the given locale. The method returns the given default value if the property is not found.
Parameters:
key - the property key.
locale - the locale to be searched
defaultValue - a default value to be returned when the property is not found

getProperty

public String getProperty(String key,
                          String defaultValue)
Searches for a property with the specified key. Starts the search with the default locale. Returns the goven default value when the property is not found.
Parameters:
key - the property key.
defaultValue - a default value to be returned when the property is not found

load

public void load(InputStream input)
            throws IOException

registerLocale

public void registerLocale(Locale locale)
Registers a locale with this property list. Properties can only be stored with locales that have been registered. If an ancestor of this locale was not yet registered, it is registerd automatically.

save

public void save(OutputStream out)
            throws IOException
Writes this property list to the given output stream. Uses the same data format as save(OutputStream). Note that the generated data will contain information on all locales.

setDefaultLocale

public void setDefaultLocale(Locale locale)
Set the default locale to be used for this list.

setProperty

public void setProperty(String key,
                        String value)
Adds a given property/value pair for the default locale. If the default locale is not registered with this list, then the property is stored with a less specific locale.

setProperty

public void setProperty(String key,
                        String value,
                        Locale locale)
Adds a given property/value pair for the given locale. The property is only stored with the locale if that locale was previously registered with the list, otherwise a less specific locale is used.

toElement

public Element toElement()
Convert the current list of properties to a JDOM-element with the default name resources.

toElement

public Element toElement(String name)
Convert the current list of properties to a JDOM-element of the given name.