net.sf.sfac.setting
Interface Settings

All Known Implementing Classes:

SettingsImpl, SubSettingsProxy

public interface Settings

Interface used to store the settings of an application.
It provides a kind of service able to store some object values and retrieve them using a string key. It also provide PropertyChangeListener support to listen to settings changes (if needed).

This settings store allows to convert the file properties (strings representing file paths) from absolute to relative (and vice-versa). The idea is that the file settings values are always stored relatively to the base path (and always get as absolute). So if you move or copy your application to another directory (and if the base path is correctly updated by the application) every file property will be resolved to the correct location.

Author:

Olivier Berlanger

Method Summary

void	addPropertyChangeListener(String settingKey, PropertyChangeListener listener) Add a PropertyChangeListener for a specific setting.
boolean	containsProperty(String key) Check if there is a property value defined for the given key.
boolean	getBooleanProperty(String key, boolean defaultValue) Get a boolean property value.
Boolean	getBooleanProperty(String key, Boolean defaultValue) Get a Boolean property value.
Color	getColorProperty(String key, Color defaultValue) Get a Color property value.
Dimension	getDimensionProperty(String key, Dimension defaultValue) Get a Dimension property value.
double	getDoubleProperty(String key, double defaultValue) Get a double property value.
<T extends Enum<T>> T	getEnumProperty(String key, T defaultValue) Get a enumerated property value.
FilePathUtils	getFilePathUtils() Get the FilePathUtils used by this settings object.
String	getFileProperty(String key, String defaultValue) Get a absolute File or Directory property value.
String	getFileProperty(String key, String defaultValue, boolean absolute) Get a File or Directory property value.
int[]	getIntArrayProperty(String key, int[] defaultValue) Get a int array property value.
Integer	getIntegerProperty(String key, Integer defaultValue) Get a Integer property value.
int	getIntProperty(String key, int defaultValue) Get a int property value.
Iterator<String>	getKeys() Return an iterator for all the defined keys.
String	getPasswordProperty(String key, String defaultValue) Get a String property value to be used as a password.
<T> T	getProperty(String key, TypeHelper<T> helper, T defaultValue) Get a property of type defined by the helper.
String	getPropertyAsInternalString(String key) Get a property as stored internally by the map (as string).
String	getPropertyFilePath() Get the path to the property file used to store the settings.
Rectangle	getRectangleProperty(String key, Rectangle defaultValue) Get a Rectangle property value.
String[]	getStringArrayProperty(String key, String[] defaultValue) Get a String array property value.
String	getStringProperty(String key, String defaultValue) Get a String property value.
void	load() Ask the settings implementation to load the settings values.
void	removeProperty(String key) Remove the property.
void	removePropertyChangeListener(String settingKey, PropertyChangeListener listener) Remove a PropertyChangeListener for a specific setting.
void	save() Ask the settings implementation to save the settings values.
void	saveAs(File fil) Save all the settings to a new property file.
void	setBooleanProperty(String key, boolean value) Set a new value for a boolean property.
void	setBooleanProperty(String key, Boolean value) Set a new value for a Boolean property.
void	setColorProperty(String key, Color value) Set a new value for a Color property.
void	setDimensionProperty(String key, Dimension value) Set a new value for a Dimension property.
void	setDoubleProperty(String key, double value) Set a new value for a double property.
<T extends Enum<T>> void	setEnumProperty(String key, T value) Set a new value for a enumerated property.
void	setFileProperty(String key, String value) Set a new value for a File or Directory property.
void	setIntArrayProperty(String key, int[] value) Set a new value for a int array property.
void	setIntegerProperty(String key, Integer value) Set a new value for a Integer property.
void	setIntProperty(String key, int value) Set a new value for a int property.
void	setPasswordProperty(String key, String value) Set a new value for a String property.
<T> void	setProperty(String key, TypeHelper<T> helper, T value) Set a property of type defined by the helper.
void	setPropertyAsInternalString(String key, String value) Set a property value using its internal string representation.
void	setPropertyFile(File fil) Set a new property file to store the settings.
void	setRectangleProperty(String key, Rectangle value) Set a new value for a Rectangle property.
void	setStringArrayProperty(String key, String[] value) Set a new value for a String array property.
void	setStringProperty(String key, String value) Set a new value for a String property.

Method Detail

getFilePathUtils

FilePathUtils getFilePathUtils()

Get the FilePathUtils used by this settings object.
This FilePathUtils is used to convert between absolute and relative file path settings. (So it holds the default base path).

Returns:

The FilePathUtils used by this settings object.

getPropertyFilePath

String getPropertyFilePath()

Get the path to the property file used to store the settings.
The returned path is absolute.

Returns:

The path to the property file used to store the settings.

load

void load()
          throws IOException

Ask the settings implementation to load the settings values. (the real effect of it will depend of the concrete Settings implementation.)

Throws:

IOException - If something prevents the settings to be loaded.

save

void save()
          throws IOException

Ask the settings implementation to save the settings values. (the real effect of it will depend of the concrete Settings implementation.)

Throws:

IOException - If something prevents the settings to be saved.

setPropertyFile

void setPropertyFile(File fil)

Set a new property file to store the settings. The given property file will be set as new reference for paths.

Parameters:

fil - The new properties file.

saveAs

void saveAs(File fil)
            throws IOException

Save all the settings to a new property file. If the file don't exists, it is created, if the file exists it is overriden without warning. The given property file will be set as new reference for paths.

Parameters:

fil - The new properties file.

Throws:

IOException - If something prevents the settings to be saved.

containsProperty

boolean containsProperty(String key)

Check if there is a property value defined for the given key.

Parameters:

key - Key for the value.

Returns:

True iff there is a property value defined for the given key.

removeProperty

void removeProperty(String key)

Remove the property.
If the property was not defined, it does nothing.

Parameters:

key - Key of the property to remove.

getKeys

Iterator<String> getKeys()

Return an iterator for all the defined keys.

Returns:

an iterator for all the defined keys.

getStringProperty

String getStringProperty(String key,
                         String defaultValue)

Get a String property value.

Parameters:

key - Key for the value.

defaultValue - Default value to be returned if no value is found for the key.

Returns:

The value associated to the given key (or default value if no value was found).

setStringProperty

void setStringProperty(String key,
                       String value)

Set a new value for a String property.
This method will fire an propertyChangeEvent to all registered listeners if the value set is different than the current value.

Parameters:

key - Key for the value.

value - New value to be associated with the key.

getPasswordProperty

String getPasswordProperty(String key,
                           String defaultValue)

Get a String property value to be used as a password.
The password will be obfuscated (obfuscation is much lighter that encryption, so don't store very sensitive password using this mechanism).

Parameters:

key - Key for the value.

defaultValue - Default value to be returned if no value is found for the key.

Returns:

The value associated to the given key (or default value if no value was found).

setPasswordProperty

void setPasswordProperty(String key,
                         String value)

Set a new value for a String property.
This method will fire an propertyChangeEvent to all registered listeners if the value set is different than the current value. The password will be obfuscated (obfuscation is much lighter that encryption, so don't store very sensitive password using this mechanism).

Parameters:

key - Key for the value.

value - New value to be associated with the key.

getStringArrayProperty

String[] getStringArrayProperty(String key,
                                String[] defaultValue)

Get a String array property value.

Parameters:

key - Key for the value.

defaultValue - Default value to be returned if no value is found for the key.

Returns:

The value associated to the given key (or default value if no value was found).

setStringArrayProperty

void setStringArrayProperty(String key,
                            String[] value)

Set a new value for a String array property.
This method will fire an propertyChangeEvent to all registered listeners if the value set is different than the current value.

Parameters:

key - Key for the value.

value - New value to be associated with the key.

getIntProperty

int getIntProperty(String key,
                   int defaultValue)

Get a int property value.

Parameters:

key - Key for the value.

defaultValue - Default value to be returned if no value is found for the key.

Returns:

The value associated to the given key (or default value if no value was found).

setIntProperty

void setIntProperty(String key,
                    int value)

Set a new value for a int property.
This method will fire an propertyChangeEvent to all registered listeners if the value set is different than the current value.

Parameters:

key - Key for the value.

value - New value to be associated with the key.

getIntegerProperty

Integer getIntegerProperty(String key,
                           Integer defaultValue)

Get a Integer property value.

Parameters:

key - Key for the value.

defaultValue - Default value to be returned if no value is found for the key.

Returns:

The value associated to the given key (or default value if no value was found).

setIntegerProperty

void setIntegerProperty(String key,
                        Integer value)

Set a new value for a Integer property.
This method will fire an propertyChangeEvent to all registered listeners if the value set is different than the current value.

Parameters:

key - Key for the value.

value - New value to be associated with the key.

getDoubleProperty

double getDoubleProperty(String key,
                         double defaultValue)

Get a double property value.

Parameters:

key - Key for the value.

defaultValue - Default value to be returned if no value is found for the key.

Returns:

The value associated to the given key (or default value if no value was found).

setDoubleProperty

void setDoubleProperty(String key,
                       double value)

Set a new value for a double property.
This method will fire an propertyChangeEvent to all registered listeners if the value set is different than the current value.

Parameters:

key - Key for the value.

value - New value to be associated with the key.

getBooleanProperty

boolean getBooleanProperty(String key,
                           boolean defaultValue)

Get a boolean property value.

Parameters:

key - Key for the value.

defaultValue - Default value to be returned if no value is found for the key.

Returns:

The value associated to the given key (or default value if no value was found).

setBooleanProperty

void setBooleanProperty(String key,
                        boolean value)

Set a new value for a boolean property.
This method will fire an propertyChangeEvent to all registered listeners if the value set is different than the current value.

Parameters:

key - Key for the value.

value - New value to be associated with the key.

getBooleanProperty

Boolean getBooleanProperty(String key,
                           Boolean defaultValue)

Get a Boolean property value.

Parameters:

key - Key for the value.

defaultValue - Default value to be returned if no value is found for the key.

Returns:

The value associated to the given key (or default value if no value was found).

setBooleanProperty

void setBooleanProperty(String key,
                        Boolean value)

Set a new value for a Boolean property.
This method will fire an propertyChangeEvent to all registered listeners if the value set is different than the current value.

Parameters:

key - Key for the value.

value - New value to be associated with the key.

getIntArrayProperty

int[] getIntArrayProperty(String key,
                          int[] defaultValue)

Get a int array property value.

Parameters:

key - Key for the value.

defaultValue - Default value to be returned if no value is found for the key.

Returns:

The value associated to the given key (or default value if no value was found).

setIntArrayProperty

void setIntArrayProperty(String key,
                         int[] value)

Set a new value for a int array property.
This method will fire an propertyChangeEvent to all registered listeners if the value set is different than the current value.

Parameters:

key - Key for the value.

value - New value to be associated with the key.

getRectangleProperty

Rectangle getRectangleProperty(String key,
                               Rectangle defaultValue)

Get a Rectangle property value.

Parameters:

key - Key for the value.

defaultValue - Default value to be returned if no value is found for the key.

Returns:

The value associated to the given key (or default value if no value was found).

setRectangleProperty

void setRectangleProperty(String key,
                          Rectangle value)

Set a new value for a Rectangle property.
This method will fire an propertyChangeEvent to all registered listeners if the value set is different than the current value.

Parameters:

key - Key for the value.

value - New value to be associated with the key.

getDimensionProperty

Dimension getDimensionProperty(String key,
                               Dimension defaultValue)

Get a Dimension property value.

Parameters:

key - Key for the value.

defaultValue - Default value to be returned if no value is found for the key.

Returns:

The value associated to the given key (or default value if no value was found).

setDimensionProperty

void setDimensionProperty(String key,
                          Dimension value)

Set a new value for a Dimension property.
This method will fire an propertyChangeEvent to all registered listeners if the value set is different than the current value.

Parameters:

key - Key for the value.

value - New value to be associated with the key.

getColorProperty

Color getColorProperty(String key,
                       Color defaultValue)

Get a Color property value.

Parameters:

key - Key for the value.

defaultValue - Default value to be returned if no value is found for the key.

Returns:

The value associated to the given key (or default value if no value was found).

setColorProperty

void setColorProperty(String key,
                      Color value)

Set a new value for a Color property.
This method will fire an propertyChangeEvent to all registered listeners if the value set is different than the current value.

Parameters:

key - Key for the value.

value - New value to be associated with the key.

getEnumProperty

<T extends Enum<T>> T getEnumProperty(String key,
                                      T defaultValue)

Get a enumerated property value.

Parameters:

key - Key for the value.

defaultValue - Default value to be returned if no value is found for the key.
Note: this default value cannot be null, it must be a value of the enumeration.

Returns:

The value associated to the given key (or default value if no value was found).

setEnumProperty

<T extends Enum<T>> void setEnumProperty(String key,
                                         T value)

Set a new value for a enumerated property.
This method will fire an propertyChangeEvent to all registered listeners if the value set is different than the current value.

Parameters:

key - Key for the value.

value - New value to be associated with the key.

getFileProperty

String getFileProperty(String key,
                       String defaultValue)

Get a absolute File or Directory property value.

Parameters:

key - Key for the value.

defaultValue - Default value to be returned if no value is found for the key. (if used, the default value will be processed to ensure it's absolute)

Returns:

The value associated to the given key (or default value if no value was found).

getFileProperty

String getFileProperty(String key,
                       String defaultValue,
                       boolean absolute)

Get a File or Directory property value.

Parameters:

key - Key for the value.

defaultValue - Default value to be returned if no value is found for the key. (if used, the default value will be processed to ensure it's relative or absolute as requested)

absolute - tells if the returned file should be absolute or relative to the settings base directory.

Returns:

The absolute or relative file path associated to the given key (or default value if no value was found).

setFileProperty

void setFileProperty(String key,
                     String value)
                     throws InvalidPathException

Set a new value for a File or Directory property.
The specified file can be absolute or relative. If a relative file is specifed, it's taken as relative to the base path of this settings.
This method will fire an propertyChangeEvent to all registered listeners if the value set is different than the current value.

Parameters:

key - Key for the value.

value - New value to be associated with the key.

Throws:

InvalidPathException - if the file set is invalid.

getPropertyAsInternalString

String getPropertyAsInternalString(String key)

Get a property as stored internally by the map (as string).
This is used to act on the key/values independently actual type of the value (that can be not known yet). The actual format of the string object depends on the implementation.

Parameters:

key - Key for the property value.

Returns:

The property value associated to the given key using the internal string representation. returns null if the property is not defined.

setPropertyAsInternalString

void setPropertyAsInternalString(String key,
                                 String value)

Set a property value using its internal string representation. Setting a null value will remove the property.

Parameters:

key - Key for the property value.

value - The new value of the property to associate to the given key.

getProperty

<T> T getProperty(String key,
                  TypeHelper<T> helper,
                  T defaultValue)

Get a property of type defined by the helper. This method is useful when you want to extend this class to new types (by creating new TypeHelper classes). For properties using a pre-defined type you should use the type-specific method.

Note that if you create a new data type the same type helper INSTANCE should be used in all set and get for this type.

Parameters:

key - Key for the property value.

helper - Helper identifying the value type and knowing how to convert between string and the requested type. If the helper is null, a string value is returned.

Returns:

The property value associated to the given key and of given type.

setProperty

<T> void setProperty(String key,
                     TypeHelper<T> helper,
                     T value)

Set a property of type defined by the helper. This method is usefull when you want to extend this class to new types (by creating new TypeHelper classes). For properties using a pre-defined type you should use the type-specific method.
Giving a null value removes the property (values and keys are removed).
If the new value is different than the previous one, a property change event is fired.

Note that if you create a new data type the same type helper INSTANCE should be used in all set and get for this type.

Parameters:

key - Key for the property value.

helper - Helper identifying the value type and knowing how to convert between string and the requested type. If the given helper is null, the property will be stored as string (with basic toString conversion in the backing properties map). When the given helper is null, no propertyChange event is generated.

value - The new value of the property to associate to the given key.

addPropertyChangeListener

void addPropertyChangeListener(String settingKey,
                               PropertyChangeListener listener)

Add a PropertyChangeListener for a specific setting.

Parameters:

settingKey - The key of the setting to listen on.

listener - The PropertyChangeListener to be added

removePropertyChangeListener

void removePropertyChangeListener(String settingKey,
                                  PropertyChangeListener listener)

Remove a PropertyChangeListener for a specific setting.

Parameters:

settingKey - The key of the setting that was listened on.

listener - The PropertyChangeListener to be removed