org.pf.settings
Interface ReadOnlySettings

All Known Subinterfaces:

MultiValueSettings, Settings

All Known Implementing Classes:

GenericSettingsImpl, MultiValueSettingsImpl, ReloadableSettings, SettingsImpl

public interface ReadOnlySettings

This interface provides read/only access to settings. The structure is, that there is a category with any number of key/value pairs inside. A key is unique in one category but may occur several times in different categories.
If a category of null is passed to any method, the default category will be taken instead. Apart from the interface each implementing class must provide a public default constructor so that instance creation with newInstance() is possible !

Additionaly the settings object can be named to distinguish between several settings objects. The name also might be used to keep the source (e.g. file name or URL) of the settings.
Each settings object can have another settings objects with default settings. Whenever a setting can't be found in the main settings, it will be looked up in the default settings. Of course this can be cascaded unlimited.

Version:

1.1

Author:

Manfred Duchrow

Method Summary

java.lang.String[]	getCategoryNames() Returns an array of all currently known categories.
ReadOnlySettings	getDefaults() Gets the defaults that are looked up, if a setting can't be found in the main settings object.
java.lang.String[]	getKeyNamesOf(java.lang.String categoryName) Returns all currently known key names in the category with the specified name.
java.lang.String[]	getKeyNamesOfDefaultCategory() Returns all currently known key names in the default category.
java.lang.String	getName() Returns the name of the settings object as a whole.
java.lang.String	getSettingsNameOf(java.lang.String keyName) Returns the name of the name of the settings where the specified key is found in the default category.
java.lang.String	getSettingsNameOf(java.lang.String categoryName, java.lang.String keyName) Returns the name of the name of the settings where the specified category and key are found.
java.lang.String	getValueOf(java.lang.String keyName) Returns the value of keyName in the default category.
java.lang.String	getValueOf(java.lang.String categoryName, java.lang.String keyName) Returns the value of keyName in the specified category.
void	setDefaults(ReadOnlySettings defaults) Sets defaults that must be looked up, if a setting can't be found in the main settings object.
void	setName(java.lang.String aName) Sets the name of the settings object as a whole.

Method Detail

getName

java.lang.String getName()

Returns the name of the settings object as a whole. This might be a simple name or a resource locator or a filename. However, naming a setting is optional and therefore this method can also return null.

setName

void setName(java.lang.String aName)

Sets the name of the settings object as a whole. This might be a simple name or a resource locator or a filename.

getValueOf

java.lang.String getValueOf(java.lang.String categoryName,
                            java.lang.String keyName)

Returns the value of keyName in the specified category.

Parameters:

categoryName - The name of the category (null means the default category)

keyName - The name of a key inside the category

Returns:

The associated value or null if either the category or the key could not be found

getValueOf

java.lang.String getValueOf(java.lang.String keyName)

Returns the value of keyName in the default category.

Parameters:

keyName - The name of a key inside the default category

Returns:

The associated value or null if the key could not be found

getCategoryNames

java.lang.String[] getCategoryNames()

Returns an array of all currently known categories. An empty string is the name for the default category!

getKeyNamesOf

java.lang.String[] getKeyNamesOf(java.lang.String categoryName)

Returns all currently known key names in the category with the specified name. If the category name is null or an empty string, the default category's keys will be returned.

Parameters:

categoryName - The name of the category the keys are wanted from

getKeyNamesOfDefaultCategory

java.lang.String[] getKeyNamesOfDefaultCategory()

Returns all currently known key names in the default category.

getDefaults

ReadOnlySettings getDefaults()

Gets the defaults that are looked up, if a setting can't be found in the main settings object.

Returns:

A settings object with default values or null

setDefaults

void setDefaults(ReadOnlySettings defaults)

Sets defaults that must be looked up, if a setting can't be found in the main settings object.

Parameters:

defaults - A settings object with default values or null

getSettingsNameOf

java.lang.String getSettingsNameOf(java.lang.String categoryName,
                                   java.lang.String keyName)

Returns the name of the name of the settings where the specified category and key are found. That is a lookup in this settings object and then, if not found, in its defaults and so on.

Parameters:

categoryName - The name of the category (null means the default category)

keyName - The name of a key inside the category

Returns:

The name of the settings object or null

getSettingsNameOf

java.lang.String getSettingsNameOf(java.lang.String keyName)

Returns the name of the name of the settings where the specified key is found in the default category. That is a lookup in this settings object and then, if not found, in its defaults and so on.

Parameters:

keyName - The name of a key inside the default category

Returns:

The name of the settings object or null