public interface

Preferences

com.microstrategy.web.preferences.Preferences

Class Overview

This interface defines the facilities available in the Preferences API. A preference is a key-value pair (both String objects). The framework also supports different levels of preferences (PreferenceLevels), such that if a value is not defined at a given level (PreferenceLevel), the lookup will default to a parent level recursively. Each preference is also associated with a definition (PreferenceDefinition). This allows us to associate extra information with a preference, such as a description, and support features such as validation. Furthermore, ensuring that every preference has a definition minimizes typographical errors when creating new preferences.

Many of the methods require a PreferenceLevel to be set. However, there are several methods that have an implicit PreferenceLevel, which depends upon the context in which the Preferences object is obtained. This provides a degree of convenience over having to specify the PreferenceLevel for every method invocation.

All of these methods also throw a MSTRUncheckedException, which is a RuntimeException if they are interrupted while attempting to acquire an internal synchronization lock. This should not normally happen since no explicit thread interrupt is ever used. Nevertheless, they are incorporated for correctness, and perhaps future use.

Summary

Public Methods
abstract void addPreference(PreferenceDefinition definition)
Add a new preference.
abstract void clear()
Removes all the preferences in the preferences object at the given PreferenceLevel.
abstract void clear(PreferenceLevel level, Collection names)

Removes named preferences at the specified PreferenceLevel.

abstract void clear(PreferenceLevel level)
Removes all the preferences at the given PreferenceLevel.
abstract boolean containsPreference(String name)
Returns true if preferences collection contains preference with specified name.
abstract List<PreferenceAllowableValue> getAllowableValues(String name)
Retrieves a list of PreferenceAllowableValue objects which are supported by thie preference.
abstract boolean getBooleanValue(String name, boolean defaultValue)
Retrieve the boolean preference value for the given key name or defaultValue if preference does not exist.
abstract boolean getBooleanValue(String name)
Retrieve the boolean preference value for the given key name.
abstract PreferenceDefinition getDefinition(String name)
In addition to the key/name-value pair, extra information such as the description of a preferences is encapsulated within a PreferenceDefinition.
abstract PreferenceLevels getEnumPreferenceLevels()
Returns the enumeration of PreferenceLevels supported by this Preferences declaration.
abstract int getIntValue(String name, int defaultValue)
Retrieve the preference value for the given key name converted into integer or defaultValue if preference does not exist.
abstract PreferenceLevel getLevel(String name)
Retrieves the finest level of granularity that defines the given name.
abstract PreferenceLevel getPropagateChangeDepth(PreferenceLevel target)
Checks to see whether changing values in this preference level will remove the corresponding key in its immediate child Preferences object in the PreferenceLevel below this one.
abstract String getValue(String name)
Retrieve the preference value for the given key name.
abstract String getValue(String name, String defaultValue)
Retrieve the preference value for the given key name or defaultValue if preference does not exist.
abstract String getValueAt(String name, PreferenceLevel level)
Retrieve a preference value at the given PreferenceLevel, ignoring preferences defined in all other levels.
abstract String getValueFrom(String name, PreferenceLevel level)
Retrieve a preference value closest but not finer than the given PreferenceLevel.
abstract boolean isDirty()
Returns true if any of the preferences have changed, irrespective of the PreferenceLevel.
abstract Enumeration listNames()
The names of all preferences available.
abstract void save()
Saves the preferences to persistent storage.
abstract void setPropagateChangeDepth(PreferenceLevel target, PreferenceLevel depth)
This method is deprecated. limited propagation as it only affects currently loaded preference hierarchy, i.e. cannot propagate server changes to ALL projects - only the one loaded
abstract void setValue(String name, String value)
Sets a name-value preference pair.
abstract void setValue(String name, PreferenceLevel level, String value)
Set a new preference value.
abstract void setValue(String name, String value, Object validationObject)
Sets a name-value preference pair.
abstract void setValue(String name, PreferenceLevel level, String value, Object validationObject)
Set a new preference value.
abstract void setValues(PreferenceLevel level, Map values)
Set several values at once.
abstract void setValues(PreferenceLevel level, Map values, Object validationObject)
Set several values at once.
abstract void setValues(Map values)
See setValues(PreferenceLevel, Map).
abstract void setValues(Map values, Object validationObject)
See setValues(PreferenceLevel, Map).
abstract void validate(PreferenceLevel level, Map values, Object validationObject)
Validate the values against their PreferenceDefinition implementation.
abstract void validate(String name, String value)
Validate the value against its PreferenceDefinition implementation.
abstract void validate(Map values, Object validationObject)
Validate the values against their PreferenceDefinition implementation.
abstract void validate(String name, PreferenceLevel level, String value, Object validationObject)
Validate the value against its PreferenceDefinition implementation.
abstract void validate(String name, String value, Object validationObject)
Validate the value against its PreferenceDefinition implementation.
abstract void validate(Map values)
Validate the values against their PreferenceDefinition implementation.
abstract void validate(String name, PreferenceLevel level, String value)
Validate the value against its PreferenceDefinition implementation.
abstract void validate(PreferenceLevel level, Map values)
Validate the values against their PreferenceDefinition implementation.

Public Methods

public abstract void addPreference (PreferenceDefinition definition)

Add a new preference. Several factory methods are defined in PreferencesMgr. The definition object must not be null. The name field in the definition should not be blank either.

Parameters
definition the new preference.
Throws
IllegalArgumentException if the definition is null.
PreferencesException if the definition is not properly defined (e.g. name cannot be null).

public abstract void clear ()

Removes all the preferences in the preferences object at the given PreferenceLevel. This is a convenience method for which the PreferenceLevel is implicit because (1) the chain only contains one Preferences object, or (2) a default PreferenceLevel may be assumed.

public abstract void clear (PreferenceLevel level, Collection names)

Removes named preferences at the specified PreferenceLevel.

Parameters
level the PreferenceLevel to be cleared.
names collection of String preference names.

public abstract void clear (PreferenceLevel level)

Removes all the preferences at the given PreferenceLevel.

Parameters
level The PreferenceLevel.

public abstract boolean containsPreference (String name)

Returns true if preferences collection contains preference with specified name.

Parameters
name the preference name.
Returns
  • if the preferences collection contains preference with the given name

public abstract List<PreferenceAllowableValue> getAllowableValues (String name)

Retrieves a list of PreferenceAllowableValue objects which are supported by thie preference.

Returns
  • A list of allowable value objects supoprted by this preference.

public abstract boolean getBooleanValue (String name, boolean defaultValue)

Retrieve the boolean preference value for the given key name or defaultValue if preference does not exist. This is a convenience method for which the PreferenceLevel is implicit because (1) the chain only contains one Preferences object, or (2) a default PreferenceLevel may be assumed.

Parameters
name Key of the preference.
defaultValue the default value.
Returns
  • The preference value or defaultValue if the preference does not exist.

public abstract boolean getBooleanValue (String name)

Retrieve the boolean preference value for the given key name. This is a convenience method for which the PreferenceLevel is implicit because (1) the chain only contains one Preferences object, or (2) a default PreferenceLevel may be assumed.

Parameters
name key of the preference.
Returns
  • the preference value.

public abstract PreferenceDefinition getDefinition (String name)

In addition to the key/name-value pair, extra information such as the description of a preferences is encapsulated within a PreferenceDefinition. If no definition is associated with the given name, null is returned - to create a new definition see PreferencesMgr.

Parameters
name key of the preference.
Returns
  • the definition detailing the preference.

public abstract PreferenceLevels getEnumPreferenceLevels ()

Returns the enumeration of PreferenceLevels supported by this Preferences declaration. Each Preferences object is associated with a PreferenceLevel in PreferenceLevels. They are chained in a parent-child fashion according to their position in the enumeration, and are used to determine the default value chain.

Returns
  • enumeration of available PreferenceLevel scopes.

public abstract int getIntValue (String name, int defaultValue)

Retrieve the preference value for the given key name converted into integer or defaultValue if preference does not exist. This is a convenience method for which the PreferenceLevel is implicit because (1) the chain only contains one Preferences object, or (2) a default PreferenceLevel may be assumed.

Parameters
name Key of the preference.
defaultValue the default value.
Returns
  • The preference value converted into integer or defaultValue if the preference does not exist.

public abstract PreferenceLevel getLevel (String name)

Retrieves the finest level of granularity that defines the given name.

Parameters
name The name of the preference.
Returns
  • The finest level defining preference.

public abstract PreferenceLevel getPropagateChangeDepth (PreferenceLevel target)

Checks to see whether changing values in this preference level will remove the corresponding key in its immediate child Preferences object in the PreferenceLevel below this one.

Returns
  • whether the child key will be removed if any values are set here.
See Also

public abstract String getValue (String name)

Retrieve the preference value for the given key name. This is a convenience method for which the PreferenceLevel is implicit because (1) the chain only contains one Preferences object, or (2) a default PreferenceLevel may be assumed.

Parameters
name key of the preference.
Returns
  • the preference value.

public abstract String getValue (String name, String defaultValue)

Retrieve the preference value for the given key name or defaultValue if preference does not exist. This is a convenience method for which the PreferenceLevel is implicit because (1) the chain only contains one Preferences object, or (2) a default PreferenceLevel may be assumed.

Parameters
name Key of the preference.
defaultValue the default value.
Returns
  • The preference value or defaultValue if the preference does not exist.

public abstract String getValueAt (String name, PreferenceLevel level)

Retrieve a preference value at the given PreferenceLevel, ignoring preferences defined in all other levels.

Parameters
name key of the preference.
level scope of the preference.
Returns
  • the preference value.

public abstract String getValueFrom (String name, PreferenceLevel level)

Retrieve a preference value closest but not finer than the given PreferenceLevel.

Parameters
name key of the preference.
level delimiting scope of the preference.
Returns
  • the preference value.

public abstract boolean isDirty ()

Returns true if any of the preferences have changed, irrespective of the PreferenceLevel.

Returns
  • whether any of the preference definitions have changed.

public abstract Enumeration listNames ()

The names of all preferences available.

Returns
  • The list of names.

public abstract void save ()

Saves the preferences to persistent storage.

Throws
PreferencesException if saving fails.
PreferencesException

public abstract void setPropagateChangeDepth (PreferenceLevel target, PreferenceLevel depth)

This method is deprecated.
limited propagation as it only affects currently loaded preference hierarchy, i.e. cannot propagate server changes to ALL projects - only the one loaded

This method determines whether altering a preference at the target level will trigger the removal of the same preference residing in the levels between the target and the specified depth level. The given depth must of course be at a level finer (i.e. a descendant) of the target level.

Parameters
target the level where value changes occur.
depth the child depth where keys are automatically removed.
Throws
depth must be a descendent depth of target, otherwise a IllegalArgumentException is thrown.
IllegalArgumentException

public abstract void setValue (String name, String value)

Sets a name-value preference pair. This is a convenience method for which the PreferenceLevel is implicit because (1) the chain only contains one Preferences object, or (2) a default PreferenceLevel may be assumed.

Parameters
name key of the preference.
value the preference value.
Throws
PreferencesException

public abstract void setValue (String name, PreferenceLevel level, String value)

Set a new preference value. Note that the preference name must already have a definition defined, otherwise an exception will be thrown.

Parameters
level scope of new values.
value new values.
Throws
PreferencesException if validation fails.

public abstract void setValue (String name, String value, Object validationObject)

Sets a name-value preference pair. This is a convenience method for which the PreferenceLevel is implicit because (1) the chain only contains one Preferences object, or (2) a default PreferenceLevel may be assumed. The validaton object is only used during the validation phase.

Parameters
name key of the preference.
value the preference value.
validationObject the validation object.
Throws
PreferencesException

public abstract void setValue (String name, PreferenceLevel level, String value, Object validationObject)

Set a new preference value. Note that the preference name must already have a definition defined, otherwise an exception will be thrown. The validation object is only used during the validation phase.

Parameters
level scope of new values.
value new values.
validationObject the validation object.
Throws
PreferencesException if validation fails.

public abstract void setValues (PreferenceLevel level, Map values)

Set several values at once. Note that the new values are actually visible during the validation phase. However, if validation fails, the values will be rolled-back. For a description of each validation failure, use getValidationExceptions() - each problem is keyed by the name of the value. Note that each and every value must have a corresponding definition declared, otherwise this operation will fail with an exception.

Parameters
level scope of new values.
values new values.
Throws
PreferencesException if one or more validations fail, they will be encapsulated in the PreferencesException.

public abstract void setValues (PreferenceLevel level, Map values, Object validationObject)

Set several values at once. Note that the new values are actually visible during the validation phase. However, if validation fails, the values will be rolled-back. For a description of each validation failure, use getValidationExceptions() - each problem is keyed by the name of the value. Note that each and every value must have a corresponding definition declared, otherwise this operation will fail with an exception. The validation object is only used during the validation phase.

Parameters
level scope of new values.
values new values.
validationObject the validation object.
Throws
PreferencesException if one or more validations fail, they will be encapsulated in the PreferencesException.

public abstract void setValues (Map values)

See setValues(PreferenceLevel, Map). This is a convenience method for which the PreferenceLevel is implicit because (1) the chain only contains one Preferences object, or (2) a default PreferenceLevel may be assumed.

Parameters
values the new values.
Throws
PreferencesException if one or more validations fail, they will be encapsulated in the PreferencesException.

public abstract void setValues (Map values, Object validationObject)

See setValues(PreferenceLevel, Map). This is a convenience method for which the PreferenceLevel is implicit because (1) the chain only contains one Preferences object, or (2) a default PreferenceLevel may be assumed. The validation object is only used during the validation phase.

Parameters
values the new values.
validationObject the validation object.
Throws
PreferencesException if one or more validations fail, they will be encapsulated in the PreferencesException.

public abstract void validate (PreferenceLevel level, Map values, Object validationObject)

Validate the values against their PreferenceDefinition implementation. Throws a PreferencesException if it fails. getValidationExceptions() returns a Map containing the PreferenceException for every preference that failed its validation. Note that the values in the input parameter will take precedence over existing preference values during validation. The validation object partakes in the validation process, as determined by the custom PreferenceDefinition.

Parameters
level the scope of the preference.
values the intended preference values.
validationObject additional parameter to ascertain validity of name-value pair.
Throws
PreferencesException if validation fails for any of the values - each exception is individually encapsulated in getValidationExceptions().

public abstract void validate (String name, String value)

Validate the value against its PreferenceDefinition implementation. Throws a PreferencesException if it fails. This is a convenience method for which the PreferenceLevel is implicit because (1) the chain only contains one Preferences object, or (2) a default PreferenceLevel may be assumed.

Parameters
name the key of preference.
value the intended value of the preference.
Throws
PreferencesException if validation fails.

public abstract void validate (Map values, Object validationObject)

Validate the values against their PreferenceDefinition implementation. Throws a PreferencesException if it fails. This is a convenience method for which the PreferenceLevel is implicit because (1) the chain only contains one Preferences object, or (2) a default PreferenceLevel may be assumed. The validation object partakes in the validation process, as determined by the custom PreferenceDefinition.

Parameters
values the intended preference values.
validationObject additional parameter to ascertain validity of name-value pair.
Throws
PreferencesException if validation fails for any of the values - each exception is individually encapsulated in getValidationExceptions().

public abstract void validate (String name, PreferenceLevel level, String value, Object validationObject)

Validate the value against its PreferenceDefinition implementation. Throws a PreferencesException if it fails. The validation object partakes in the validation process, as determined by the custom PreferenceDefinition.

Parameters
name the key of preference.
level the scope of the preference.
value the intended value of the preference.
validationObject additional parameter to ascertain validity of name-value pair.
Throws
PreferencesException if validation fails.

public abstract void validate (String name, String value, Object validationObject)

Validate the value against its PreferenceDefinition implementation. Throws a PreferencesException if it fails. This is a convenience method for which the PreferenceLevel is implicit because (1) the chain only contains one Preferences object, or (2) a default PreferenceLevel may be assumed. The validation object partakes in the validation process, as determined by the custom PreferenceDefinition.

Parameters
name the key of preference.
value the intended value of the preference.
validationObject additional parameter to ascertain validity of name-value pair.
Throws
PreferencesException if validation fails.

public abstract void validate (Map values)

Validate the values against their PreferenceDefinition implementation. Throws a PreferencesException if it fails. This is a convenience method for which the PreferenceLevel is implicit because (1) the chain only contains one Preferences object, or (2) a default PreferenceLevel may be assumed.

Parameters
values the intended preference values.
Throws
PreferencesException if validation fails for any of the values - each exception is individually encapsulated in getValidationExceptions().

public abstract void validate (String name, PreferenceLevel level, String value)

Validate the value against its PreferenceDefinition implementation. Throws a PreferencesException if it fails.

Parameters
name the key of preference.
level the scope of the preference.
value the intended value of the preference.
Throws
PreferencesException if validation fails.

public abstract void validate (PreferenceLevel level, Map values)

Validate the values against their PreferenceDefinition implementation. Throws a PreferencesException if it fails. getValidationExceptions() returns a Map containing the PreferenceException for every preference that failed its validation. Note that the values in the input parameter will take precedence over existing preference values during validation.

Parameters
level the scope of the preference.
values the intended preference values.
Throws
PreferencesException if validation fails for any of the values - each exception is individually encapsulated in getValidationExceptions().