|
Eclipse Platform 2.0 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--org.eclipse.core.runtime.Preferences
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
using setToDefault
. 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 (with setDefault
)
does not cause any events to be reported.
Clients may instantiate this class. This class was not designed to be subclassed.
The implementation is based on a pair of internal
java.util.Properties
objects, one holding explicitly set values
(set using setValue
), the other holding the default values
(set using setDefaultValue
). The load
and
store
methods persist the non-default property values to
streams (the default values are not saved).
Nested Class Summary | |
static interface |
Preferences.IPropertyChangeListener
Listener for property changes. |
static class |
Preferences.PropertyChangeEvent
An event object describing a change to a named property. |
Field Summary | |
static boolean |
BOOLEAN_DEFAULT_DEFAULT
The default-default value for boolean properties ( false ). |
static double |
DOUBLE_DEFAULT_DEFAULT
The default-default value for double properties ( 0.0 ). |
static float |
FLOAT_DEFAULT_DEFAULT
The default-default value for float properties ( 0.0f ). |
static int |
INT_DEFAULT_DEFAULT
The default-default value for int properties ( 0 ). |
static long |
LONG_DEFAULT_DEFAULT
The default-default value for long properties ( 0L ). |
static String |
STRING_DEFAULT_DEFAULT
The default-default value for String properties ( "" ). |
Constructor Summary | |
Preferences()
Creates an empty preference table. |
Method Summary | |
void |
addPropertyChangeListener(Preferences.IPropertyChangeListener listener)
Adds a property change listener to this preference object. |
boolean |
contains(String name)
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()
Returns a list of all properties known to this preference object which have default values other than their default-default value. |
static void |
exportPreferences(IPath file)
Exports all non-default-valued preferences for all installed plugins to the provided file. |
boolean |
getBoolean(String name)
Returns the current value of the boolean-valued property with the given name. |
boolean |
getDefaultBoolean(String name)
Returns the default value for the boolean-valued property with the given name. |
double |
getDefaultDouble(String name)
Returns the default value for the double-valued property with the given name. |
float |
getDefaultFloat(String name)
Returns the default value for the float-valued property with the given name. |
int |
getDefaultInt(String name)
Returns the default value for the integer-valued property with the given name. |
long |
getDefaultLong(String name)
Returns the default value for the long-valued property with the given name. |
String |
getDefaultString(String name)
Returns the default value for the string-valued property with the given name. |
double |
getDouble(String name)
Returns the current value of the double-valued property with the given name. |
float |
getFloat(String name)
Returns the current value of the float-valued property with the given name. |
int |
getInt(String name)
Returns the current value of the integer-valued property with the given name. |
long |
getLong(String name)
Returns the current value of the long-valued property with the given name. |
String |
getString(String name)
Returns the current value of the string-valued property with the given name. |
static void |
importPreferences(IPath file)
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)
Returns whether the property with the given name has the default value in virtue of having no explicitly set value. |
void |
load(InputStream in)
Loads the non-default-valued properties for this preference object from the given input stream using java.util.Properties.load(InputStream) . |
boolean |
needsSaving()
Returns whether the current values in this preference object require saving. |
String[] |
propertyNames()
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)
Removes the given listener from this preference object. |
void |
setDefault(String name,
boolean value)
Sets the default value for the boolean-valued property with the given name. |
void |
setDefault(String name,
double value)
Sets the default value for the double-valued property with the given name. |
void |
setDefault(String name,
float value)
Sets the default value for the float-valued property with the given name. |
void |
setDefault(String name,
int value)
Sets the default value for the integer-valued property with the given name. |
void |
setDefault(String name,
long value)
Sets the default value for the long-valued property with the given name. |
void |
setDefault(String name,
String value)
Sets the default value for the string-valued property with the given name. |
void |
setToDefault(String name)
Sets the current value of the property with the given name back to its default value. |
void |
setValue(String name,
boolean value)
Sets the current value of the boolean-valued property with the given name. |
void |
setValue(String name,
double value)
Sets the current value of the double-valued property with the given name. |
void |
setValue(String name,
float value)
Sets the current value of the float-valued property with the given name. |
void |
setValue(String name,
int value)
Sets the current value of the integer-valued property with the given name. |
void |
setValue(String name,
long value)
Sets the current value of the long-valued property with the given name. |
void |
setValue(String name,
String value)
Sets the current value of the string-valued property with the given name. |
void |
store(OutputStream out,
String header)
Saves the non-default-valued properties known to this preference object to the given output stream using Properties.store(OutputStream,String) . |
static IStatus |
validatePreferenceVersions(IPath file)
Validates that the preference versions in the given file match the versions of the currently installed plugins. |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
public static final boolean BOOLEAN_DEFAULT_DEFAULT
false
).
public static final double DOUBLE_DEFAULT_DEFAULT
0.0
).
public static final float FLOAT_DEFAULT_DEFAULT
0.0f
).
public static final int INT_DEFAULT_DEFAULT
0
).
public static final long LONG_DEFAULT_DEFAULT
0L
).
public static final String STRING_DEFAULT_DEFAULT
""
).
Constructor Detail |
public Preferences()
Use the methods load(InputStream)
and
store(InputStream)
to load and store these preferences.
load(java.io.InputStream)
,
store(java.io.OutputStream, java.lang.String)
Method Detail |
public static void exportPreferences(IPath file) throws CoreException
The file that is written can be read later using the importPreferences method.
file
- The absolute filesystem path of the file to export preferences to.
CoreException
- if this method fails. Reasons include:
importPreferences(org.eclipse.core.runtime.IPath)
,
validatePreferenceVersions(org.eclipse.core.runtime.IPath)
public static void importPreferences(IPath file) throws CoreException
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.
file
- The absolute filesystem path of the file to import preferences from.
CoreException
- if this method fails. Reasons include:
exportPreferences(org.eclipse.core.runtime.IPath)
,
validatePreferenceVersions(org.eclipse.core.runtime.IPath)
public static IStatus validatePreferenceVersions(IPath file)
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 a
IStatus.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.
file
- The absolute filesystem path of the preference file to validate.exportPreferences(org.eclipse.core.runtime.IPath)
,
importPreferences(org.eclipse.core.runtime.IPath)
public void addPropertyChangeListener(Preferences.IPropertyChangeListener listener)
listener
- a property change listenerpublic void removePropertyChangeListener(Preferences.IPropertyChangeListener listener)
listener
- a property change listenerpublic boolean contains(String name)
name
- the name of the property
true
if either a current value or a default
value is known for the named property, and false
otherwisepublic boolean getBoolean(String name)
false
) if there
is no property with the given name, or if the current value
cannot be treated as a boolean.
name
- the name of the property
public void setValue(String name, boolean value)
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
.
name
- the name of the propertyvalue
- the new current value of the propertypublic boolean getDefaultBoolean(String name)
false
) if there
is no default property with the given name, or if the default
value cannot be treated as a boolean.
name
- the name of the property
public void setDefault(String name, boolean value)
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.
name
- the name of the propertyvalue
- the new default value for the propertypublic double getDouble(String name)
0.0
) if there
is no property with the given name, or if the current value
cannot be treated as a double.
name
- the name of the property
public void setValue(String name, double value)
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
.
name
- the name of the propertyvalue
- the new current value of the property; must be
a number (not a NaN)public double getDefaultDouble(String name)
0.0
) if there
is no default property with the given name, or if the default
value cannot be treated as a double.
name
- the name of the property
public void setDefault(String name, double value)
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.
name
- the name of the propertyvalue
- the new default value for the property; must be
a number (not a NaN)public float getFloat(String name)
0.0f
) if there
is no property with the given name, or if the current value
cannot be treated as a float.
name
- the name of the property
public void setValue(String name, float value)
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
.
name
- the name of the propertyvalue
- the new current value of the property; must be
a number (not a NaN)public float getDefaultFloat(String name)
0.0f
) if there
is no default property with the given name, or if the default
value cannot be treated as a float.
name
- the name of the property
public void setDefault(String name, float value)
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.
name
- the name of the propertyvalue
- the new default value for the property; must be
a number (not a NaN)public int getInt(String name)
0
) if there
is no property with the given name, or if the current value
cannot be treated as an integter.
name
- the name of the property
public void setValue(String name, int value)
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
.
name
- the name of the propertyvalue
- the new current value of the propertypublic int getDefaultInt(String name)
0
) if there
is no default property with the given name, or if the default
value cannot be treated as an integer.
name
- the name of the property
public void setDefault(String name, int value)
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.
name
- the name of the propertyvalue
- the new default value for the propertypublic long getLong(String name)
0L
) if there
is no property with the given name, or if the current value
cannot be treated as a long.
name
- the name of the property
public void setValue(String name, long value)
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
.
name
- the name of the propertyvalue
- the new current value of the propertypublic long getDefaultLong(String name)
0L
) if there
is no default property with the given name, or if the default
value cannot be treated as a long.
name
- the name of the property
public void setDefault(String name, long value)
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.
name
- the name of the propertyvalue
- the new default value for the propertypublic String getString(String name)
""
)
if there is no property with the given name.
name
- the name of the property
public void setValue(String name, String value)
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
.
name
- the name of the propertyvalue
- the new current value of the propertypublic String getDefaultString(String name)
""
)
is no default property with the given name, or if the default
value cannot be treated as a string.
name
- the name of the property
public void setDefault(String name, String value)
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.
name
- the name of the propertyvalue
- the new default value for the propertypublic boolean isDefault(String name)
name
- the name of the property
true
if the property has no explicitly set value,
and false
otherwise (including the case where the property
is unknown to this object)public void setToDefault(String name)
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.
name
- the name of the propertypublic String[] propertyNames()
public String[] defaultPropertyNames()
public boolean needsSaving()
true
if at least one of the properties
known to this preference object has a current value different from its
default value, and false
otherwisepublic void store(OutputStream out, String header) throws IOException
Properties.store(OutputStream,String)
.
Note that the output is unconditionally written, even when
needsSaving
is false
.
out
- the output streamheader
- a comment to be included in the output, or
null
if none
IOException
- if there is a problem saving this preference objectProperties.store(OutputStream,String)
public void load(InputStream in) throws IOException
java.util.Properties.load(InputStream)
. Default property
values are not affected.
in
- the input stream
IOException
- if there is a problem loading this preference
objectProperties.load(InputStream)
|
Eclipse Platform 2.0 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |