Package com.microstrategy.web.preferences

Interface Preferences

  • public interface Preferences

    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.

    Since:
    MicroStrategy Web 7.3.1 or earlier

    • Method Summary

      All Methods Instance Methods Abstract Methods Deprecated Methods 
      Modifier and Type Method Description
      void addPreference​(PreferenceDefinition definition)
      Add a new preference.
      void clear()
      Removes all the preferences in the preferences object at the given PreferenceLevel.
      void clear​(PreferenceLevel level)
      Removes all the preferences at the given PreferenceLevel.
      void clear​(PreferenceLevel level, java.util.Collection names)
      Removes named preferences at the specified PreferenceLevel.
      boolean containsPreference​(java.lang.String name)
      Returns true if preferences collection contains preference with specified name.
      java.util.List<PreferenceAllowableValue> getAllowableValues​(java.lang.String name)
      Retrieves a list of PreferenceAllowableValue objects which are supported by thie preference.
      boolean getBooleanValue​(java.lang.String name)
      Retrieve the boolean preference value for the given key name.
      boolean getBooleanValue​(java.lang.String name, boolean defaultValue)
      Retrieve the boolean preference value for the given key name or defaultValue if preference does not exist.
      PreferenceDefinition getDefinition​(java.lang.String name)
      In addition to the key/name-value pair, extra information such as the description of a preferences is encapsulated within a PreferenceDefinition.
      PreferenceLevels getEnumPreferenceLevels()
      Returns the enumeration of PreferenceLevels supported by this Preferences declaration.
      int getIntValue​(java.lang.String name, int defaultValue)
      Retrieve the preference value for the given key name converted into integer or defaultValue if preference does not exist.
      PreferenceLevel getLevel​(java.lang.String name)
      Retrieves the finest level of granularity that defines the given name.
      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.
      java.lang.String getValue​(java.lang.String name)
      Retrieve the preference value for the given key name.
      java.lang.String getValue​(java.lang.String name, java.lang.String defaultValue)
      Retrieve the preference value for the given key name or defaultValue if preference does not exist.
      java.lang.String getValueAt​(java.lang.String name, PreferenceLevel level)
      Retrieve a preference value at the given PreferenceLevel, ignoring preferences defined in all other levels.
      java.lang.String getValueFrom​(java.lang.String name, PreferenceLevel level)
      Retrieve a preference value closest but not finer than the given PreferenceLevel.
      boolean isDirty()
      Returns true if any of the preferences have changed, irrespective of the PreferenceLevel.
      java.util.Enumeration listNames()
      The names of all preferences available.
      void save()
      Saves the preferences to persistent storage.
      void setPropagateChangeDepth​(PreferenceLevel target, PreferenceLevel depth)
      Deprecated.
      limited propagation as it only affects currently loaded preference hierarchy, i.e.
      void setValue​(java.lang.String name, PreferenceLevel level, java.lang.String value)
      Set a new preference value.
      void setValue​(java.lang.String name, PreferenceLevel level, java.lang.String value, java.lang.Object validationObject)
      Set a new preference value.
      void setValue​(java.lang.String name, java.lang.String value)
      Sets a name-value preference pair.
      void setValue​(java.lang.String name, java.lang.String value, java.lang.Object validationObject)
      Sets a name-value preference pair.
      void setValues​(PreferenceLevel level, java.util.Map values)
      Set several values at once.
      void setValues​(PreferenceLevel level, java.util.Map values, java.lang.Object validationObject)
      Set several values at once.
      void setValues​(java.util.Map values)
      See setValues(PreferenceLevel, Map).
      void setValues​(java.util.Map values, java.lang.Object validationObject)
      See setValues(PreferenceLevel, Map).
      void validate​(PreferenceLevel level, java.util.Map values)
      Validate the values against their PreferenceDefinition implementation.
      void validate​(PreferenceLevel level, java.util.Map values, java.lang.Object validationObject)
      Validate the values against their PreferenceDefinition implementation.
      void validate​(java.lang.String name, PreferenceLevel level, java.lang.String value)
      Validate the value against its PreferenceDefinition implementation.
      void validate​(java.lang.String name, PreferenceLevel level, java.lang.String value, java.lang.Object validationObject)
      Validate the value against its PreferenceDefinition implementation.
      void validate​(java.lang.String name, java.lang.String value)
      Validate the value against its PreferenceDefinition implementation.
      void validate​(java.lang.String name, java.lang.String value, java.lang.Object validationObject)
      Validate the value against its PreferenceDefinition implementation.
      void validate​(java.util.Map values)
      Validate the values against their PreferenceDefinition implementation.
      void validate​(java.util.Map values, java.lang.Object validationObject)
      Validate the values against their PreferenceDefinition implementation.

    • Method Detail

      • getEnumPreferenceLevels

        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.

      • getValueAt

        java.lang.String getValueAt​(java.lang.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.

      • getValueFrom

        java.lang.String getValueFrom​(java.lang.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.

      • setValue

        void setValue​(java.lang.String name,
              PreferenceLevel level,
              java.lang.String value)
       throws PreferencesException
        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.

      • setValue

        void setValue​(java.lang.String name,
              PreferenceLevel level,
              java.lang.String value,
              java.lang.Object validationObject)
       throws PreferencesException
        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.

      • setValues

        void setValues​(PreferenceLevel level,
               java.util.Map values)
        throws PreferencesException
        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 PreferencesException.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.

      • setValues

        void setValues​(PreferenceLevel level,
               java.util.Map values,
               java.lang.Object validationObject)
        throws PreferencesException
        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 PreferencesException.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.

      • getDefinition

        PreferenceDefinition getDefinition​(java.lang.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.

      • containsPreference

        boolean containsPreference​(java.lang.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

      • addPreference

        void addPreference​(PreferenceDefinition definition)
            throws java.lang.IllegalArgumentException,
                   PreferencesException
        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:
        java.lang.IllegalArgumentException - if the definition is null.
        PreferencesException - if the definition is not properly defined (e.g. name cannot be null).

      • getLevel

        PreferenceLevel getLevel​(java.lang.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.

      • listNames

        java.util.Enumeration listNames()
        The names of all preferences available.
        Returns:
        The list of names.

      • clear

        void clear​(PreferenceLevel level)
        Removes all the preferences at the given PreferenceLevel.
        Parameters:
        level - The PreferenceLevel.

      • isDirty

        boolean isDirty()
        Returns true if any of the preferences have changed, irrespective of the PreferenceLevel.
        Returns:
        whether any of the preference definitions have changed.

      • getValue

        java.lang.String getValue​(java.lang.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.

      • getValue

        java.lang.String getValue​(java.lang.String name,
                          java.lang.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.

      • getIntValue

        int getIntValue​(java.lang.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.

      • setValue

        void setValue​(java.lang.String name,
              java.lang.String value)
       throws PreferencesException
        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

      • setValue

        void setValue​(java.lang.String name,
              java.lang.String value,
              java.lang.Object validationObject)
       throws PreferencesException
        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

      • setValues

        void setValues​(java.util.Map values,
               java.lang.Object validationObject)
        throws PreferencesException
        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.

      • clear

        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.

      • setPropagateChangeDepth

        void setPropagateChangeDepth​(PreferenceLevel target,
                             PreferenceLevel depth)
                      throws java.lang.IllegalArgumentException
        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:
        Designated - depth must be a descendent depth of target, otherwise a IllegalArgumentException is thrown.
        java.lang.IllegalArgumentException

      • validate

        void validate​(java.lang.String name,
              PreferenceLevel level,
              java.lang.String value)
       throws PreferencesException
        Validate the value against its PreferenceDefinition implementation. Throws a PreferencesException if it fails.
        Parameters:
        level - the scope of the preference.
        name - the key of preference.
        value - the intended value of the preference.
        Throws:
        PreferencesException - if validation fails.

      • validate

        void validate​(java.lang.String name,
              PreferenceLevel level,
              java.lang.String value,
              java.lang.Object validationObject)
       throws PreferencesException
        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:
        level - the scope of the preference.
        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.

      • validate

        void validate​(java.lang.String name,
              java.lang.String value)
       throws PreferencesException
        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.

      • validate

        void validate​(java.lang.String name,
              java.lang.String value,
              java.lang.Object validationObject)
       throws PreferencesException
        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.

      • validate

        void validate​(PreferenceLevel level,
              java.util.Map values)
       throws PreferencesException
        Validate the values against their PreferenceDefinition implementation. Throws a PreferencesException if it fails. PreferencesException.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 PreferencesException.getValidationExceptions().

      • validate

        void validate​(PreferenceLevel level,
              java.util.Map values,
              java.lang.Object validationObject)
       throws PreferencesException
        Validate the values against their PreferenceDefinition implementation. Throws a PreferencesException if it fails. PreferencesException.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 PreferencesException.getValidationExceptions().

      • validate

        void validate​(java.util.Map values)
       throws PreferencesException
        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 PreferencesException.getValidationExceptions().

      • validate

        void validate​(java.util.Map values,
              java.lang.Object validationObject)
       throws PreferencesException
        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 PreferencesException.getValidationExceptions().

      • clear

        void clear​(PreferenceLevel level,
           java.util.Collection names)

        Removes named preferences at the specified PreferenceLevel.

        Parameters:
        names - collection of String preference names.
        level - the PreferenceLevel to be cleared.
        Since:
        MicroStrategy Web 8.0.0

      • getAllowableValues

        java.util.List<PreferenceAllowableValue> getAllowableValues​(java.lang.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.
        Since:
        MicroStrategy Web 9.0.0

      • getBooleanValue

        boolean getBooleanValue​(java.lang.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.

      • getBooleanValue

        boolean getBooleanValue​(java.lang.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.