Class Preferences
- java.lang.Object
-
- org.eclipse.core.runtime.Preferences
-
@Deprecated public class Preferences extends Object
Deprecated.This class is replaced byIEclipsePreferences
. Setting a default value is accomplished by a setting a value in theDefaultScope
, and setting an explicit non-default value is accomplished by setting a value in theInstanceScope
. To obtain a preference value, use the preference accessor methods onIPreferencesService
.A table of preference settings, mapping named properties to values. Property names are non-empty strings; property values can be either booleans, non-null strings, or values of one of the primitive number types. The table consists of two, sparse, layers: the lower layer holds default values for properties, and the upper layer holds explicitly set values for properties. Normal retrieval looks for an explicitly set value for the given property in the upper layer; if there is nothing for that property in the upper layer, it next looks for a default value for the given property in the lower layer; if there is nothing for that property in the lower layer, it returns a standard default-default value. The default-default values for the primitive types are as follows:boolean
=false
double
=0.0
float
=0.0f
int
=0
long
=0L
String
=""
(the empty string)
Internally, all properties values (in both layers) are stored as strings. Standard conversions to and from numeric and boolean types are performed on demand.
The typical usage is to establish the defaults for all known properties and then restore previously stored values for properties whose values were explicitly set. The existing settings can be changed and new properties can be set (
setValue
). If the values specified is the same as the default value, the explicit setting is deleted from the top layer. It is also possible to reset a property value back to the default value usingsetToDefault
. After the properties have been modified, the properties with explicit settings are written to disk. The default values are never saved. This two-tiered approach to saving and restoring property setting minimizes the number of properties that need to be persisted; indeed, the normal starting state does not require storing any properties at all. It also makes it easy to use different default settings in different environments while maintaining just those property settings the user has adjusted.A property change event is reported whenever a property's value actually changes (either through
setValue
,setToDefault
). Note, however, that manipulating default values (withsetDefault
) does not cause any events to be reported.Clients may instantiate this class.
The implementation is based on a pair of internal
java.util.Properties
objects, one holding explicitly set values (set usingsetValue
), the other holding the default values (set usingsetDefaultValue
). Theload
andstore
methods persist the non-default property values to streams (the default values are not saved).If a client sets a default value to be equivalent to the default-default for that type, the value is still known to the preference store as having a default value. That is, the name will still be returned in the result of the
defaultPropertyNames
andcontains
methods.- Since:
- 2.0
- Restriction:
- This class is not intended to be subclassed by clients.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static interface
Preferences.IPropertyChangeListener
Deprecated.Listener for property changes.static class
Preferences.PropertyChangeEvent
Deprecated.An event object describing a change to a named property.
-
Field Summary
Fields Modifier and Type Field Description static boolean
BOOLEAN_DEFAULT_DEFAULT
Deprecated.The default-default value for boolean properties (false
).protected boolean
dirty
Deprecated.Indicates whether a value has been changed bysetToDefault
orsetValue
; initiallyfalse
.static double
DOUBLE_DEFAULT_DEFAULT
Deprecated.The default-default value for double properties (0.0
).protected static String
FALSE
Deprecated.The string representation used forfalse
("false"
).static float
FLOAT_DEFAULT_DEFAULT
Deprecated.The default-default value for float properties (0.0f
).static int
INT_DEFAULT_DEFAULT
Deprecated.The default-default value for int properties (0
).protected ListenerList<Preferences.IPropertyChangeListener>
listeners
Deprecated.List of registered listeners (element type:IPropertyChangeListener
).static long
LONG_DEFAULT_DEFAULT
Deprecated.The default-default value for long properties (0L
).static String
PT_PREFERENCES
Deprecated.The simple identifier constant (value "preferences
") of the extension point of the Core Runtime plug-in where plug-ins declare extensions to the preference facility.static String
STRING_DEFAULT_DEFAULT
Deprecated.The default-default value for String properties (""
).protected static String
TRUE
Deprecated.The string representation used fortrue
("true"
).
-
Constructor Summary
Constructors Constructor Description Preferences()
Deprecated.Creates an empty preference table.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
addPropertyChangeListener(Preferences.IPropertyChangeListener listener)
Deprecated.Adds a property change listener to this preference object.boolean
contains(String name)
Deprecated.Returns whether the given property is known to this preference object, either by having an explicit setting or by having a default setting.String[]
defaultPropertyNames()
Deprecated.Returns a list of all properties known to this preference object which have an explicit default value set.static void
exportPreferences(IPath path)
Deprecated.Exports all non-default-valued preferences for all installed plugins to the provided file.protected void
firePropertyChangeEvent(String name, Object oldValue, Object newValue)
Deprecated.Fires a property change event corresponding to a change to the current value of the property with the given name.boolean
getBoolean(String name)
Deprecated.Returns the current value of the boolean-valued property with the given name.boolean
getDefaultBoolean(String name)
Deprecated.Returns the default value for the boolean-valued property with the given name.double
getDefaultDouble(String name)
Deprecated.Returns the default value for the double-valued property with the given name.float
getDefaultFloat(String name)
Deprecated.Returns the default value for the float-valued property with the given name.int
getDefaultInt(String name)
Deprecated.Returns the default value for the integer-valued property with the given name.long
getDefaultLong(String name)
Deprecated.Returns the default value for the long-valued property with the given name.String
getDefaultString(String name)
Deprecated.Returns the default value for the string-valued property with the given name.double
getDouble(String name)
Deprecated.Returns the current value of the double-valued property with the given name.float
getFloat(String name)
Deprecated.Returns the current value of the float-valued property with the given name.int
getInt(String name)
Deprecated.Returns the current value of the integer-valued property with the given name.long
getLong(String name)
Deprecated.Returns the current value of the long-valued property with the given name.String
getString(String name)
Deprecated.Returns the current value of the string-valued property with the given name.static void
importPreferences(IPath path)
Deprecated.Loads the plugin preferences from the given file, and replaces all non-default-valued preferences for all plugins with the values from this file.boolean
isDefault(String name)
Deprecated.Returns whether the property with the given name has the default value in virtue of having no explicitly set value.void
load(InputStream in)
Deprecated.Loads the non-default-valued properties for this preference object from the given input stream usingjava.util.Properties.load(InputStream)
.boolean
needsSaving()
Deprecated.Returns whether the current values in this preference object require saving.String[]
propertyNames()
Deprecated.Returns a list of all properties known to this preference object which have current values other than their default value.void
removePropertyChangeListener(Preferences.IPropertyChangeListener listener)
Deprecated.Removes the given listener from this preference object.void
setDefault(String name, boolean value)
Deprecated.Sets the default value for the boolean-valued property with the given name.void
setDefault(String name, double value)
Deprecated.Sets the default value for the double-valued property with the given name.void
setDefault(String name, float value)
Deprecated.Sets the default value for the float-valued property with the given name.void
setDefault(String name, int value)
Deprecated.Sets the default value for the integer-valued property with the given name.void
setDefault(String name, long value)
Deprecated.Sets the default value for the long-valued property with the given name.void
setDefault(String name, String value)
Deprecated.Sets the default value for the string-valued property with the given name.void
setToDefault(String name)
Deprecated.Sets the current value of the property with the given name back to its default value.void
setValue(String name, boolean value)
Deprecated.Sets the current value of the boolean-valued property with the given name.void
setValue(String name, double value)
Deprecated.Sets the current value of the double-valued property with the given name.void
setValue(String name, float value)
Deprecated.Sets the current value of the float-valued property with the given name.void
setValue(String name, int value)
Deprecated.Sets the current value of the integer-valued property with the given name.void
setValue(String name, long value)
Deprecated.Sets the current value of the long-valued property with the given name.void
setValue(String name, String value)
Deprecated.Sets the current value of the string-valued property with the given name.void
store(OutputStream out, String header)
Deprecated.Saves the non-default-valued properties known to this preference object to the given output stream usingProperties.store(OutputStream,String)
.static IStatus
validatePreferenceVersions(IPath file)
Deprecated.Validates that the preference versions in the given file match the versions of the currently installed plugins.
-
-
-
Field Detail
-
BOOLEAN_DEFAULT_DEFAULT
public static final boolean BOOLEAN_DEFAULT_DEFAULT
Deprecated.The default-default value for boolean properties (false
).- See Also:
- Constant Field Values
-
DOUBLE_DEFAULT_DEFAULT
public static final double DOUBLE_DEFAULT_DEFAULT
Deprecated.The default-default value for double properties (0.0
).- See Also:
- Constant Field Values
-
FLOAT_DEFAULT_DEFAULT
public static final float FLOAT_DEFAULT_DEFAULT
Deprecated.The default-default value for float properties (0.0f
).- See Also:
- Constant Field Values
-
INT_DEFAULT_DEFAULT
public static final int INT_DEFAULT_DEFAULT
Deprecated.The default-default value for int properties (0
).- See Also:
- Constant Field Values
-
LONG_DEFAULT_DEFAULT
public static final long LONG_DEFAULT_DEFAULT
Deprecated.The default-default value for long properties (0L
).- See Also:
- Constant Field Values
-
STRING_DEFAULT_DEFAULT
public static final String STRING_DEFAULT_DEFAULT
Deprecated.The default-default value for String properties (""
).- See Also:
- Constant Field Values
-
TRUE
protected static final String TRUE
Deprecated.The string representation used fortrue
("true"
).- See Also:
- Constant Field Values
-
FALSE
protected static final String FALSE
Deprecated.The string representation used forfalse
("false"
).- See Also:
- Constant Field Values
-
PT_PREFERENCES
public static final String PT_PREFERENCES
Deprecated.The simple identifier constant (value "preferences
") of the extension point of the Core Runtime plug-in where plug-ins declare extensions to the preference facility. A plug-in may define any number of preference extensions.- Since:
- 3.2
- See Also:
- Constant Field Values
-
listeners
protected ListenerList<Preferences.IPropertyChangeListener> listeners
Deprecated.List of registered listeners (element type:IPropertyChangeListener
). These listeners are to be informed when the current value of a property changes.
-
dirty
protected boolean dirty
Deprecated.Indicates whether a value has been changed bysetToDefault
orsetValue
; initiallyfalse
.
-
-
Constructor Detail
-
Preferences
public Preferences()
Deprecated.Creates an empty preference table.Use the methods
load(InputStream)
andstore(InputStream)
to load and store these preferences.- See Also:
load(InputStream)
,store(OutputStream, String)
-
-
Method Detail
-
exportPreferences
public static void exportPreferences(IPath path) throws CoreException
Deprecated.Exports all non-default-valued preferences for all installed plugins to the provided file. If a file already exists at the given location, it will be deleted. If there are no preferences to export, no file will be written.The file that is written can be read later using the importPreferences method.
- Parameters:
path
- The absolute file system path of the file to export preferences to.- Throws:
CoreException
- if this method fails. Reasons include:- The file could not be written.
- See Also:
importPreferences(IPath)
,validatePreferenceVersions(IPath)
-
importPreferences
public static void importPreferences(IPath path) throws CoreException
Deprecated.Loads the plugin preferences from the given file, and replaces all non-default-valued preferences for all plugins with the values from this file.If the file contains preferences for plug-ins that don't exist in the current install, they are ignored. This method does not validate if the plug-in versions in the preference file match the currently installed plug-ins. Clients should first call validatePreferenceVersions on the file to ensure that the versions are compatible.
The file must have been written by the exportPreferences method.
- Parameters:
path
- The absolute file system path of the file to import preferences from.- Throws:
CoreException
- if this method fails. Reasons include:- The file does not exist.
- The file could not be read.
- See Also:
exportPreferences(IPath)
,validatePreferenceVersions(IPath)
-
validatePreferenceVersions
public static IStatus validatePreferenceVersions(IPath file)
Deprecated.Validates that the preference versions in the given file match the versions of the currently installed plugins. Returns an OK status if all preferences match the currently installed plugins, otherwise a MultiStatus describing what plugins have preferences that don't match.If the returned status has a
IStatus.WARNING
severity, it means that some preferences may not be applicable but for the most part they will be compatible. If the returned status has aIStatus.ERROR
severity, it means that the preferences will probably not be compatible.If the file contains preferences for plug-ins that don't exist in the current install, they are ignored.
The file must have been written by the exportPreferences method.
- Parameters:
file
- The absolute file system path of the preference file to validate.- See Also:
exportPreferences(IPath)
,importPreferences(IPath)
-
addPropertyChangeListener
public void addPropertyChangeListener(Preferences.IPropertyChangeListener listener)
Deprecated.Adds a property change listener to this preference object. Has no effect if the identical listener is already registered.Note: Depending on the means in which the property values changed, the old and new values for the property can be either typed, a string representation of the value, or
null
. Clients who wish to behave properly in all cases should all three cases in their implementation of the property change listener.- Parameters:
listener
- a property change listener
-
removePropertyChangeListener
public void removePropertyChangeListener(Preferences.IPropertyChangeListener listener)
Deprecated.Removes the given listener from this preference object. Has no effect if the listener is not registered.- Parameters:
listener
- a property change listener
-
contains
public boolean contains(String name)
Deprecated.Returns whether the given property is known to this preference object, either by having an explicit setting or by having a default setting. Returnsfalse
if the given name isnull
.- Parameters:
name
- the name of the property, ornull
- Returns:
true
if either a current value or a default value is known for the named property, andfalse
otherwise
-
firePropertyChangeEvent
protected void firePropertyChangeEvent(String name, Object oldValue, Object newValue)
Deprecated.Fires a property change event corresponding to a change to the current value of the property with the given name.- Parameters:
name
- the name of the property, to be used as the property in the event objectoldValue
- the old value, ornull
if not known or not relevantnewValue
- the new value, ornull
if not known or not relevant
-
getBoolean
public boolean getBoolean(String name)
Deprecated.Returns the current value of the boolean-valued property with the given name. Returns the default-default value (false
) if there is no property with the given name, or if the current value cannot be treated as a boolean. The given name must not benull
.- Parameters:
name
- the name of the property- Returns:
- the boolean-valued property
-
setValue
public void setValue(String name, boolean value)
Deprecated.Sets the current value of the boolean-valued property with the given name. The given name must not benull
.A property change event is reported if the current value of the property actually changes from its previous value. In the event object, the property name is the name of the property, and the old and new values are wrapped as objects.
If the given value is the same as the corresponding default value for the given property, the explicit setting is deleted. Note that the recommended way of re-initializing a property to its default value is to call
setToDefault
.- Parameters:
name
- the name of the propertyvalue
- the new current value of the property
-
getDefaultBoolean
public boolean getDefaultBoolean(String name)
Deprecated.Returns the default value for the boolean-valued property with the given name. Returns the default-default value (false
) if there is no default property with the given name, or if the default value cannot be treated as a boolean. The given name must not benull
.- Parameters:
name
- the name of the property- Returns:
- the default value of the named property
-
setDefault
public void setDefault(String name, boolean value)
Deprecated.Sets the default value for the boolean-valued property with the given name. The given name must not benull
.Note that the current value of the property is affected if the property's current value was its old default value, in which case it changes to the new default value. If the property's current is different from its old default value, its current value is unaffected. No property change events are reported by changing default values.
- Parameters:
name
- the name of the propertyvalue
- the new default value for the property
-
getDouble
public double getDouble(String name)
Deprecated.Returns the current value of the double-valued property with the given name. Returns the default-default value (0.0
) if there is no property with the given name, or if the current value cannot be treated as a double. The given name must not benull
.- Parameters:
name
- the name of the property- Returns:
- the double-valued property
-
setValue
public void setValue(String name, double value)
Deprecated.Sets the current value of the double-valued property with the given name. The given name must not benull
.A property change event is reported if the current value of the property actually changes from its previous value. In the event object, the property name is the name of the property, and the old and new values are wrapped as objects.
If the given value is the same as the corresponding default value for the given property, the explicit setting is deleted. Note that the recommended way of re-initializing a property to its default value is to call
setToDefault
.- Parameters:
name
- the name of the propertyvalue
- the new current value of the property; must be a number (not a NaN)
-
getDefaultDouble
public double getDefaultDouble(String name)
Deprecated.Returns the default value for the double-valued property with the given name. Returns the default-default value (0.0
) if there is no default property with the given name, or if the default value cannot be treated as a double. The given name must not benull
.- Parameters:
name
- the name of the property- Returns:
- the default value of the named property
-
setDefault
public void setDefault(String name, double value)
Deprecated.Sets the default value for the double-valued property with the given name. The given name must not benull
.Note that the current value of the property is affected if the property's current value was its old default value, in which case it changes to the new default value. If the property's current is different from its old default value, its current value is unaffected. No property change events are reported by changing default values.
- Parameters:
name
- the name of the propertyvalue
- the new default value for the property; must be a number (not a NaN)
-
getFloat
public float getFloat(String name)
Deprecated.Returns the current value of the float-valued property with the given name. Returns the default-default value (0.0f
) if there is no property with the given name, or if the current value cannot be treated as a float. The given name must not benull
.- Parameters:
name
- the name of the property- Returns:
- the float-valued property
-
setValue
public void setValue(String name, float value)
Deprecated.Sets the current value of the float-valued property with the given name. The given name must not benull
.A property change event is reported if the current value of the property actually changes from its previous value. In the event object, the property name is the name of the property, and the old and new values are wrapped as objects.
If the given value is the same as the corresponding default value for the given property, the explicit setting is deleted. Note that the recommended way of re-initializing a property to its default value is to call
setToDefault
.- Parameters:
name
- the name of the propertyvalue
- the new current value of the property; must be a number (not a NaN)
-
getDefaultFloat
public float getDefaultFloat(String name)
Deprecated.Returns the default value for the float-valued property with the given name. Returns the default-default value (0.0f
) if there is no default property with the given name, or if the default value cannot be treated as a float. The given name must not benull
.- Parameters:
name
- the name of the property- Returns:
- the default value of the named property
-
setDefault
public void setDefault(String name, float value)
Deprecated.Sets the default value for the float-valued property with the given name. The given name must not benull
.Note that the current value of the property is affected if the property's current value was its old default value, in which case it changes to the new default value. If the property's current is different from its old default value, its current value is unaffected. No property change events are reported by changing default values.
- Parameters:
name
- the name of the propertyvalue
- the new default value for the property; must be a number (not a NaN)
-
getInt
public int getInt(String name)
Deprecated.Returns the current value of the integer-valued property with the given name. Returns the default-default value (0
) if there is no property with the given name, or if the current value cannot be treated as an integer. The given name must not benull
.- Parameters:
name
- the name of the property- Returns:
- the int-valued property
-
setValue
public void setValue(String name, int value)
Deprecated.Sets the current value of the integer-valued property with the given name. The given name must not benull
.A property change event is reported if the current value of the property actually changes from its previous value. In the event object, the property name is the name of the property, and the old and new values are wrapped as objects.
If the given value is the same as the corresponding default value for the given property, the explicit setting is deleted. Note that the recommended way of re-initializing a property to its default value is to call
setToDefault
.- Parameters:
name
- the name of the propertyvalue
- the new current value of the property
-
getDefaultInt
public int getDefaultInt(String name)
Deprecated.Returns the default value for the integer-valued property with the given name. Returns the default-default value (0
) if there is no default property with the given name, or if the default value cannot be treated as an integer. The given name must not benull
.- Parameters:
name
- the name of the property- Returns:
- the default value of the named property
-
setDefault
public void setDefault(String name, int value)
Deprecated.Sets the default value for the integer-valued property with the given name. The given name must not benull
.Note that the current value of the property is affected if the property's current value was its old default value, in which case it changes to the new default value. If the property's current is different from its old default value, its current value is unaffected. No property change events are reported by changing default values.
- Parameters:
name
- the name of the propertyvalue
- the new default value for the property
-
getLong
public long getLong(String name)
Deprecated.Returns the current value of the long-valued property with the given name. Returns the default-default value (0L
) if there is no property with the given name, or if the current value cannot be treated as a long. The given name must not benull
.- Parameters:
name
- the name of the property- Returns:
- the long-valued property
-
setValue
public void setValue(String name, long value)
Deprecated.Sets the current value of the long-valued property with the given name. The given name must not benull
.A property change event is reported if the current value of the property actually changes from its previous value. In the event object, the property name is the name of the property, and the old and new values are wrapped as objects.
If the given value is the same as the corresponding default value for the given property, the explicit setting is deleted. Note that the recommended way of re-initializing a property to its default value is to call
setToDefault
.- Parameters:
name
- the name of the propertyvalue
- the new current value of the property
-
getDefaultLong
public long getDefaultLong(String name)
Deprecated.Returns the default value for the long-valued property with the given name. Returns the default-default value (0L
) if there is no default property with the given name, or if the default value cannot be treated as a long. The given name must not benull
.- Parameters:
name
- the name of the property- Returns:
- the default value of the named property
-
setDefault
public void setDefault(String name, long value)
Deprecated.Sets the default value for the long-valued property with the given name. The given name must not benull
.Note that the current value of the property is affected if the property's current value was its old default value, in which case it changes to the new default value. If the property's current is different from its old default value, its current value is unaffected. No property change events are reported by changing default values.
- Parameters:
name
- the name of the propertyvalue
- the new default value for the property
-
getString
public String getString(String name)
Deprecated.Returns the current value of the string-valued property with the given name. Returns the default-default value (the empty string""
) if there is no property with the given name. The given name must not benull
.- Parameters:
name
- the name of the property- Returns:
- the string-valued property
-
setValue
public void setValue(String name, String value)
Deprecated.Sets the current value of the string-valued property with the given name. The given name must not benull
.A property change event is reported if the current value of the property actually changes from its previous value. In the event object, the property name is the name of the property, and the old and new values are wrapped as objects.
If the given value is the same as the corresponding default value for the given property, the explicit setting is deleted. Note that the recommended way of re-initializing a property to its default value is to call
setToDefault
.- Parameters:
name
- the name of the propertyvalue
- the new current value of the property
-
getDefaultString
public String getDefaultString(String name)
Deprecated.Returns the default value for the string-valued property with the given name. Returns the default-default value (the empty string""
) is no default property with the given name, or if the default value cannot be treated as a string. The given name must not benull
.- Parameters:
name
- the name of the property- Returns:
- the default value of the named property
-
setDefault
public void setDefault(String name, String value)
Deprecated.Sets the default value for the string-valued property with the given name. The given name must not benull
.Note that the current value of the property is affected if the property's current value was its old default value, in which case it changes to the new default value. If the property's current is different from its old default value, its current value is unaffected. No property change events are reported by changing default values.
- Parameters:
name
- the name of the propertyvalue
- the new default value for the property
-
isDefault
public boolean isDefault(String name)
Deprecated.Returns whether the property with the given name has the default value in virtue of having no explicitly set value. Returnsfalse
if the given name isnull
.- Parameters:
name
- the name of the property, ornull
- Returns:
true
if the property has no explicitly set value, andfalse
otherwise (including the case where the property is unknown to this object)
-
setToDefault
public void setToDefault(String name)
Deprecated.Sets the current value of the property with the given name back to its default value. Has no effect if the property does not have its own current value. The given name must not benull
.Note that the recommended way of re-initializing a property to the appropriate default value is to call
setToDefault
. This is implemented by removing the named value from the object, thereby exposing the default value.A property change event is always reported. In the event object, the property name is the name of the property, and the old and new values are either strings, or
null
indicating the default-default value.- Parameters:
name
- the name of the property
-
propertyNames
public String[] propertyNames()
Deprecated.Returns a list of all properties known to this preference object which have current values other than their default value.- Returns:
- an array of property names
-
defaultPropertyNames
public String[] defaultPropertyNames()
Deprecated.Returns a list of all properties known to this preference object which have an explicit default value set.- Returns:
- an array of property names
-
needsSaving
public boolean needsSaving()
Deprecated.Returns whether the current values in this preference object require saving.- Returns:
true
if at least one of the properties known to this preference object has a current value different from its default value, andfalse
otherwise
-
store
public void store(OutputStream out, String header) throws IOException
Deprecated.Saves the non-default-valued properties known to this preference object to the given output stream usingProperties.store(OutputStream,String)
.Note that the output is unconditionally written, even when
needsSaving
isfalse
.- Parameters:
out
- the output streamheader
- a comment to be included in the output, ornull
if none- Throws:
IOException
- if there is a problem saving this preference object- See Also:
Properties.store(OutputStream,String)
-
load
public void load(InputStream in) throws IOException
Deprecated.Loads the non-default-valued properties for this preference object from the given input stream usingjava.util.Properties.load(InputStream)
. Default property values are not affected.- Parameters:
in
- the input stream- Throws:
IOException
- if there is a problem loading this preference object- See Also:
Properties.load(InputStream)
-
-