Class PreferenceStore

  • All Implemented Interfaces:
    IPersistentPreferenceStore, IPreferenceStore

    public class PreferenceStore
    extends EventManager
    implements IPersistentPreferenceStore
    A concrete preference store implementation based on an internal java.util.Properties object, with support for persisting the non-default preference values to files or streams.

    This class was not designed to be subclassed.

    See Also:
    IPreferenceStore
    Restriction:
    This class is not intended to be subclassed by clients.
    • Constructor Summary

      Constructors 
      Constructor Description
      PreferenceStore()
      Creates an empty preference store.
      PreferenceStore​(String filename)
      Creates an empty preference store that loads from and saves to the a file.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addPropertyChangeListener​(IPropertyChangeListener listener)
      Adds a property change listener to this preference store.
      boolean contains​(String name)
      Returns whether the named preference is known to this preference store.
      void firePropertyChangeEvent​(String name, Object oldValue, Object newValue)
      Fires a property change event corresponding to a change to the current value of the preference with the given name.
      boolean getBoolean​(String name)
      Returns the current value of the boolean-valued preference with the given name.
      boolean getDefaultBoolean​(String name)
      Returns the default value for the boolean-valued preference with the given name.
      double getDefaultDouble​(String name)
      Returns the default value for the double-valued preference with the given name.
      float getDefaultFloat​(String name)
      Returns the default value for the float-valued preference with the given name.
      int getDefaultInt​(String name)
      Returns the default value for the integer-valued preference with the given name.
      long getDefaultLong​(String name)
      Returns the default value for the long-valued preference with the given name.
      String getDefaultString​(String name)
      Returns the default value for the string-valued preference with the given name.
      double getDouble​(String name)
      Returns the current value of the double-valued preference with the given name.
      float getFloat​(String name)
      Returns the current value of the float-valued preference with the given name.
      int getInt​(String name)
      Returns the current value of the integer-valued preference with the given name.
      long getLong​(String name)
      Returns the current value of the long-valued preference with the given name.
      String getString​(String name)
      Returns the current value of the string-valued preference with the given name.
      boolean isDefault​(String name)
      Returns whether the current value of the preference with the given name has the default value.
      void list​(PrintStream out)
      Prints the contents of this preference store to the given print stream.
      void list​(PrintWriter out)
      Prints the contents of this preference store to the given print writer.
      void load()
      Loads this preference store from the file established in the constructor PreferenceStore(java.lang.String) (or by setFileName).
      void load​(InputStream in)
      Loads this preference store from the given input stream.
      boolean needsSaving()
      Returns whether the current values in this property store require saving.
      String[] preferenceNames()
      Returns an enumeration of all preferences known to this store which have current values other than their default value.
      void putValue​(String name, String value)
      Sets the current value of the preference with the given name to the given string value without sending a property change.
      void removePropertyChangeListener​(IPropertyChangeListener listener)
      Removes the given listener from this preference store.
      void save()
      Saves the non-default-valued preferences known to this preference store to the file from which they were originally loaded.
      void save​(OutputStream out, String header)
      Saves this preference store to the given output stream.
      void setDefault​(String name, boolean value)
      Sets the default value for the boolean-valued preference with the given name.
      void setDefault​(String name, double value)
      Sets the default value for the double-valued preference with the given name.
      void setDefault​(String name, float value)
      Sets the default value for the float-valued preference with the given name.
      void setDefault​(String name, int value)
      Sets the default value for the integer-valued preference with the given name.
      void setDefault​(String name, long value)
      Sets the default value for the long-valued preference with the given name.
      void setDefault​(String name, String value)
      Sets the default value for the string-valued preference with the given name.
      void setFilename​(String name)
      Sets the name of the file used when loading and storing this preference store.
      void setToDefault​(String name)
      Sets the current value of the preference with the given name back to its default value.
      void setValue​(String name, boolean value)
      Sets the current value of the boolean-valued preference with the given name.
      void setValue​(String name, double value)
      Sets the current value of the double-valued preference with the given name.
      void setValue​(String name, float value)
      Sets the current value of the float-valued preference with the given name.
      void setValue​(String name, int value)
      Sets the current value of the integer-valued preference with the given name.
      void setValue​(String name, long value)
      Sets the current value of the long-valued preference with the given name.
      void setValue​(String name, String value)
      Sets the current value of the string-valued preference with the given name.
    • Constructor Detail

      • PreferenceStore

        public PreferenceStore()
        Creates an empty preference store.

        Use the methods load(InputStream) and save(InputStream) to load and store this preference store.

        See Also:
        load(InputStream), save(OutputStream, String)
      • PreferenceStore

        public PreferenceStore​(String filename)
        Creates an empty preference store that loads from and saves to the a file.

        Use the methods load() and save() to load and store this preference store.

        Parameters:
        filename - the file name
        See Also:
        load(), save()
    • Method Detail

      • contains

        public boolean contains​(String name)
        Description copied from interface: IPreferenceStore
        Returns whether the named preference is known to this preference store.
        Specified by:
        contains in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        Returns:
        true if either a current value or a default value is known for the named preference, and false otherwise
      • firePropertyChangeEvent

        public void firePropertyChangeEvent​(String name,
                                            Object oldValue,
                                            Object newValue)
        Description copied from interface: IPreferenceStore
        Fires a property change event corresponding to a change to the current value of the preference with the given name.

        This method is provided on this interface to simplify the implementation of decorators. There is normally no need to call this method since setValue and setToDefault report such events in due course. Implementations should funnel all preference changes through this method.

        Specified by:
        firePropertyChangeEvent in interface IPreferenceStore
        Parameters:
        name - the name of the preference, to be used as the property in the event object
        oldValue - the old value
        newValue - the new value
      • getBoolean

        public boolean getBoolean​(String name)
        Description copied from interface: IPreferenceStore
        Returns the current value of the boolean-valued preference with the given name. Returns the default-default value (false) if there is no preference with the given name, or if the current value cannot be treated as a boolean.
        Specified by:
        getBoolean in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        Returns:
        the boolean-valued preference
      • getDefaultBoolean

        public boolean getDefaultBoolean​(String name)
        Description copied from interface: IPreferenceStore
        Returns the default value for the boolean-valued preference with the given name. Returns the default-default value (false) if there is no default preference with the given name, or if the default value cannot be treated as a boolean.
        Specified by:
        getDefaultBoolean in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        Returns:
        the default value of the named preference
      • getDefaultDouble

        public double getDefaultDouble​(String name)
        Description copied from interface: IPreferenceStore
        Returns the default value for the double-valued preference with the given name. Returns the default-default value (0.0) if there is no default preference with the given name, or if the default value cannot be treated as a double.
        Specified by:
        getDefaultDouble in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        Returns:
        the default value of the named preference
      • getDefaultFloat

        public float getDefaultFloat​(String name)
        Description copied from interface: IPreferenceStore
        Returns the default value for the float-valued preference with the given name. Returns the default-default value (0.0f) if there is no default preference with the given name, or if the default value cannot be treated as a float.
        Specified by:
        getDefaultFloat in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        Returns:
        the default value of the named preference
      • getDefaultInt

        public int getDefaultInt​(String name)
        Description copied from interface: IPreferenceStore
        Returns the default value for the integer-valued preference with the given name. Returns the default-default value (0) if there is no default preference with the given name, or if the default value cannot be treated as an integer.
        Specified by:
        getDefaultInt in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        Returns:
        the default value of the named preference
      • getDefaultLong

        public long getDefaultLong​(String name)
        Description copied from interface: IPreferenceStore
        Returns the default value for the long-valued preference with the given name. Returns the default-default value (0L) if there is no default preference with the given name, or if the default value cannot be treated as a long.
        Specified by:
        getDefaultLong in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        Returns:
        the default value of the named preference
      • getDefaultString

        public String getDefaultString​(String name)
        Description copied from interface: IPreferenceStore
        Returns the default value for the string-valued preference with the given name. Returns the default-default value (the empty string "") is no default preference with the given name, or if the default value cannot be treated as a string.
        Specified by:
        getDefaultString in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        Returns:
        the default value of the named preference
      • getDouble

        public double getDouble​(String name)
        Description copied from interface: IPreferenceStore
        Returns the current value of the double-valued preference with the given name. Returns the default-default value (0.0) if there is no preference with the given name, or if the current value cannot be treated as a double.
        Specified by:
        getDouble in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        Returns:
        the double-valued preference
      • getFloat

        public float getFloat​(String name)
        Description copied from interface: IPreferenceStore
        Returns the current value of the float-valued preference with the given name. Returns the default-default value (0.0f) if there is no preference with the given name, or if the current value cannot be treated as a float.
        Specified by:
        getFloat in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        Returns:
        the float-valued preference
      • getInt

        public int getInt​(String name)
        Description copied from interface: IPreferenceStore
        Returns the current value of the integer-valued preference with the given name. Returns the default-default value (0) if there is no preference with the given name, or if the current value cannot be treated as an integer.
        Specified by:
        getInt in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        Returns:
        the int-valued preference
      • getLong

        public long getLong​(String name)
        Description copied from interface: IPreferenceStore
        Returns the current value of the long-valued preference with the given name. Returns the default-default value (0L) if there is no preference with the given name, or if the current value cannot be treated as a long.
        Specified by:
        getLong in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        Returns:
        the long-valued preference
      • getString

        public String getString​(String name)
        Description copied from interface: IPreferenceStore
        Returns the current value of the string-valued preference with the given name. Returns the default-default value (the empty string "") if there is no preference with the given name, or if the current value cannot be treated as a string.
        Specified by:
        getString in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        Returns:
        the string-valued preference
      • isDefault

        public boolean isDefault​(String name)
        Description copied from interface: IPreferenceStore
        Returns whether the current value of the preference with the given name has the default value.
        Specified by:
        isDefault in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        Returns:
        true if the preference has a known default value and its current value is the same, and false otherwise (including the case where the preference is unknown to this store)
      • list

        public void list​(PrintStream out)
        Prints the contents of this preference store to the given print stream.
        Parameters:
        out - the print stream
      • list

        public void list​(PrintWriter out)
        Prints the contents of this preference store to the given print writer.
        Parameters:
        out - the print writer
      • load

        public void load()
                  throws IOException
        Loads this preference store from the file established in the constructor PreferenceStore(java.lang.String) (or by setFileName). Default preference values are not affected.
        Throws:
        IOException - if there is a problem loading this store
      • load

        public void load​(InputStream in)
                  throws IOException
        Loads this preference store from the given input stream. Default preference values are not affected.
        Parameters:
        in - the input stream
        Throws:
        IOException - if there is a problem loading this store
      • needsSaving

        public boolean needsSaving()
        Description copied from interface: IPreferenceStore
        Returns whether the current values in this property store require saving.
        Specified by:
        needsSaving in interface IPreferenceStore
        Returns:
        true if at least one of values of the preferences known to this store has changed and requires saving, and false otherwise.
      • preferenceNames

        public String[] preferenceNames()
        Returns an enumeration of all preferences known to this store which have current values other than their default value.
        Returns:
        an array of preference names
      • putValue

        public void putValue​(String name,
                             String value)
        Description copied from interface: IPreferenceStore
        Sets the current value of the preference with the given name to the given string value without sending a property change.

        This method does not fire a property change event and should only be used for setting internal preferences that are not meant to be processed by listeners. Normal clients should instead call #setValue.

        Specified by:
        putValue in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        value - the new current value of the preference
      • save

        public void save()
                  throws IOException
        Saves the non-default-valued preferences known to this preference store to the file from which they were originally loaded.
        Specified by:
        save in interface IPersistentPreferenceStore
        Throws:
        IOException - if there is a problem saving this store
      • save

        public void save​(OutputStream out,
                         String header)
                  throws IOException
        Saves this preference store to the given output stream. The given string is inserted as header information.
        Parameters:
        out - the output stream
        header - the header
        Throws:
        IOException - if there is a problem saving this store
      • setDefault

        public void setDefault​(String name,
                               double value)
        Description copied from interface: IPreferenceStore
        Sets the default value for the double-valued preference with the given name.

        Note that the current value of the preference is affected if the preference's current value was its old default value, in which case it changes to the new default value. If the preference's current is different from its old default value, its current value is unaffected. No property change events are reported by changing default values.

        Specified by:
        setDefault in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        value - the new default value for the preference
      • setDefault

        public void setDefault​(String name,
                               float value)
        Description copied from interface: IPreferenceStore
        Sets the default value for the float-valued preference with the given name.

        Note that the current value of the preference is affected if the preference's current value was its old default value, in which case it changes to the new default value. If the preference's current is different from its old default value, its current value is unaffected. No property change events are reported by changing default values.

        Specified by:
        setDefault in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        value - the new default value for the preference
      • setDefault

        public void setDefault​(String name,
                               int value)
        Description copied from interface: IPreferenceStore
        Sets the default value for the integer-valued preference with the given name.

        Note that the current value of the preference is affected if the preference's current value was its old default value, in which case it changes to the new default value. If the preference's current is different from its old default value, its current value is unaffected. No property change events are reported by changing default values.

        Specified by:
        setDefault in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        value - the new default value for the preference
      • setDefault

        public void setDefault​(String name,
                               long value)
        Description copied from interface: IPreferenceStore
        Sets the default value for the long-valued preference with the given name.

        Note that the current value of the preference is affected if the preference's current value was its old default value, in which case it changes to the new default value. If the preference's current is different from its old default value, its current value is unaffected. No property change events are reported by changing default values.

        Specified by:
        setDefault in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        value - the new default value for the preference
      • setDefault

        public void setDefault​(String name,
                               String value)
        Description copied from interface: IPreferenceStore
        Sets the default value for the string-valued preference with the given name.

        Note that the current value of the preference is affected if the preference's current value was its old default value, in which case it changes to the new default value. If the preference's current is different from its old default value, its current value is unaffected. No property change events are reported by changing default values.

        Specified by:
        setDefault in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        value - the new default value for the preference
      • setDefault

        public void setDefault​(String name,
                               boolean value)
        Description copied from interface: IPreferenceStore
        Sets the default value for the boolean-valued preference with the given name.

        Note that the current value of the preference is affected if the preference's current value was its old default value, in which case it changes to the new default value. If the preference's current is different from its old default value, its current value is unaffected. No property change events are reported by changing default values.

        Specified by:
        setDefault in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        value - the new default value for the preference
      • setFilename

        public void setFilename​(String name)
        Sets the name of the file used when loading and storing this preference store.

        Afterward, the methods load() and save() can be used to load and store this preference store.

        Parameters:
        name - the file name
        See Also:
        load(), save()
      • setToDefault

        public void setToDefault​(String name)
        Description copied from interface: IPreferenceStore
        Sets the current value of the preference with the given name back to its default value.

        Note that the preferred way of re-initializing a preference to the appropriate default value is to call setToDefault. This is implemented by removing the named value from the store, thereby exposing the default value.

        Specified by:
        setToDefault in interface IPreferenceStore
        Parameters:
        name - the name of the preference
      • setValue

        public void setValue​(String name,
                             double value)
        Description copied from interface: IPreferenceStore
        Sets the current value of the double-valued preference with the given name.

        A property change event is reported if the current value of the preference actually changes from its previous value. In the event object, the property name is the name of the preference, and the old and new values are wrapped as objects.

        Note that the preferred way of re-initializing a preference to its default value is to call setToDefault.

        Specified by:
        setValue in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        value - the new current value of the preference
      • setValue

        public void setValue​(String name,
                             float value)
        Description copied from interface: IPreferenceStore
        Sets the current value of the float-valued preference with the given name.

        A property change event is reported if the current value of the preference actually changes from its previous value. In the event object, the property name is the name of the preference, and the old and new values are wrapped as objects.

        Note that the preferred way of re-initializing a preference to its default value is to call setToDefault.

        Specified by:
        setValue in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        value - the new current value of the preference
      • setValue

        public void setValue​(String name,
                             int value)
        Description copied from interface: IPreferenceStore
        Sets the current value of the integer-valued preference with the given name.

        A property change event is reported if the current value of the preference actually changes from its previous value. In the event object, the property name is the name of the preference, and the old and new values are wrapped as objects.

        Note that the preferred way of re-initializing a preference to its default value is to call setToDefault.

        Specified by:
        setValue in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        value - the new current value of the preference
      • setValue

        public void setValue​(String name,
                             long value)
        Description copied from interface: IPreferenceStore
        Sets the current value of the long-valued preference with the given name.

        A property change event is reported if the current value of the preference actually changes from its previous value. In the event object, the property name is the name of the preference, and the old and new values are wrapped as objects.

        Note that the preferred way of re-initializing a preference to its default value is to call setToDefault.

        Specified by:
        setValue in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        value - the new current value of the preference
      • setValue

        public void setValue​(String name,
                             String value)
        Description copied from interface: IPreferenceStore
        Sets the current value of the string-valued preference with the given name.

        A property change event is reported if the current value of the preference actually changes from its previous value. In the event object, the property name is the name of the preference, and the old and new values are wrapped as objects.

        Note that the preferred way of re-initializing a preference to its default value is to call setToDefault.

        Specified by:
        setValue in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        value - the new current value of the preference
      • setValue

        public void setValue​(String name,
                             boolean value)
        Description copied from interface: IPreferenceStore
        Sets the current value of the boolean-valued preference with the given name.

        A property change event is reported if the current value of the preference actually changes from its previous value. In the event object, the property name is the name of the preference, and the old and new values are wrapped as objects.

        Note that the preferred way of re-initializing a preference to its default value is to call setToDefault.

        Specified by:
        setValue in interface IPreferenceStore
        Parameters:
        name - the name of the preference
        value - the new current value of the preference