com.emarsys.ecommon.prefs.config
Interface ISetting

All Superinterfaces:
java.io.Serializable
All Known Implementing Classes:
GenericSetting

public interface ISetting
extends java.io.Serializable

ISetting represents the abstract notion of a single setting or property, that means more or less a name-value pair of Strings, in the Configuration API.

The Configuration (or more precise ConfigurationBackends) defines an API for accessing configuration storages. The backends are not only maps of key-value pairs of Strings but collections of ISettings that are indexed by their unique name.
Using a seperate setting type is uncommon in the traditional Java configuration API's like the ones around Properties and Preferences but for the sake of a richer yet easier to use Configuration it makes sense to do so.
For instance ISettings have a transient and volatile SettingMode associated with them which eases the implementation of arbitrary fallback and default values as well as the chaining of ConfigurationBackends a lot.
Furthmore there are several convenience methods that do the parsing of the setting's string value.

Because the Configuration API has its own setting class specified as an interface there are arbitrary implementations possible, for instance an implementation could be achieved as an DB entity.
NOTE: Because arbitrary ISetting implementations should be supported there's an important invariant for their equals(Object) and hashCode() implementations: both methods must refer solely to the settings name! See the methods' documentation for details.

Author:
Michael "kULO" Kulovits

Field Summary
static java.lang.String DEF_DATE_FORMAT
           
 
Method Summary
 boolean equals(java.lang.Object that)
           Returns false if the passed Object is not an instance of ISetting or has a different String name than this instance.
 boolean getBooleanValue()
          Parses the setting's value and converts it to a boolean value.
 java.util.Date getDateValue()
          Parses the setting's value assuming the default date format and converts it to a Date instance.
 java.util.Date getDateValue(java.lang.String format)
          Parses the setting's value using the passed date format and converts it to a Date instance.
 double getDoubleValue()
          Parses the setting's value and converts it to a double value.
 int getIntValue()
          Parses the setting's value and converts it to an int.
 java.util.List<java.lang.String> getListValues()
          Parses the setting's value which is assumed to be a comma seperated list and converts it to a List instance.
 long getLongValue()
          Parses the setting's value and converts it to a long value.
 SettingMode getMode()
          Retrieves the SettingMode associated with the ISetting.
 java.lang.String getName()
          The unique and persistent name of the setting.
 java.lang.String getValue()
          Retrieves the persistent String value of the ISetting.
 int hashCode()
          Creates a hash code for this ISetting that solely refers to its unique name.
 void setMode(SettingMode mode)
          Set/updates the ISetting's mode.
 void setName(java.lang.String name)
          Sets/updates the unique name of the ISetting.
 void setValue(java.lang.String value)
          Sets/updates the value of the ISetting.
 

Field Detail

DEF_DATE_FORMAT

static final java.lang.String DEF_DATE_FORMAT
See Also:
Constant Field Values
Method Detail

getName

java.lang.String getName()
The unique and persistent name of the setting.

Returns:
the non-null name of the ISetting

setName

void setName(java.lang.String name)
Sets/updates the unique name of the ISetting. The update needs not to have a persistent effect (altough it might be case if your ISetting is implemented as a managed JPA entity, for instance). Thus if you want to persistently update your Configuration you have to use ConfigurationBackend.set(ISetting).

Parameters:
name - - the name of the setting

getValue

java.lang.String getValue()
Retrieves the persistent String value of the ISetting.

Returns:
the non-null value of the ISetting

setValue

void setValue(java.lang.String value)
Sets/updates the value of the ISetting. The update needs not to have a persistent effect (altough it might be case if your ISetting is implemented as a managed JPA entity, for instance). Thus if you want to persistently update your Configuration you have to use ConfigurationBackend.set(ISetting).

Parameters:
value - - the (new) value of the setting

getMode

SettingMode getMode()
Retrieves the SettingMode associated with the ISetting. The SettingMode is transient and volatile, that means it needs not to be stored persistently in the backend and might be changed by chained backends several times during a call to ConfigurationBackend.get(String).

Returns:
the SettingMode of this ISetting, never null.

setMode

void setMode(SettingMode mode)
Set/updates the ISetting's mode. The SettingMode is not stored persistently for settings and mighty change on its way through ConfigurationBackends.

Parameters:
mode - the mode to set

equals

boolean equals(java.lang.Object that)

Returns false if the passed Object is not an instance of ISetting or has a different String name than this instance.

Only the name is relevant for an equality check of ISetting instances, this has to ensured in every subtype!

Overrides:
equals in class java.lang.Object
Parameters:
that - the object with which to compare
Returns:
true if this object has the same setting name as 'that'; false otherwise.
See Also:
hashCode(), Object.equals(Object)

hashCode

int hashCode()
Creates a hash code for this ISetting that solely refers to its unique name. This has to be ensured in subclasses too!

Overrides:
hashCode in class java.lang.Object
Returns:
a hash code value for this setting
See Also:
equals(Object), Object.hashCode()

getIntValue

int getIntValue()
Parses the setting's value and converts it to an int. Throws a an unchecked instance of RuntimeException on parsing errors.

Returns:
the setting's integer value

getLongValue

long getLongValue()
Parses the setting's value and converts it to a long value. Throws a an unchecked instance of RuntimeException on parsing errors.

Returns:
the setting's long value

getDoubleValue

double getDoubleValue()
Parses the setting's value and converts it to a double value. Throws a an unchecked instance of RuntimeException on parsing errors.

Returns:
the setting's double value

getBooleanValue

boolean getBooleanValue()
Parses the setting's value and converts it to a boolean value. Throws a an unchecked instance of RuntimeException on parsing errors.

Returns:
the setting's boolean value

getDateValue

java.util.Date getDateValue()
                            throws java.text.ParseException
Parses the setting's value assuming the default date format and converts it to a Date instance.

Returns:
the setting's Date value
Throws:
java.text.ParseException - - on any parsing error.

getDateValue

java.util.Date getDateValue(java.lang.String format)
                            throws java.text.ParseException
Parses the setting's value using the passed date format and converts it to a Date instance.

Parameters:
format - - the SimpleDateFormat in a String form
Returns:
the setting's Date value
Throws:
java.text.ParseException - - on any parsing error.

getListValues

java.util.List<java.lang.String> getListValues()
Parses the setting's value which is assumed to be a comma seperated list and converts it to a List instance. Throws a an unchecked instance of RuntimeException on parsing errors.

Returns:
the setting's List values


Copyright © 2010 emarsys AG. All Rights Reserved.