Docjar: A Java Source and Docuemnt Enginecom.*    java.*    javax.*    org.*    all    new    plug-in

Quick Search    Search Deep
Overview  Package   Class  Use  Deprecated  Index 
Home >> All >> org >> eclipse >> core >> [ runtime overview ]  PREV CLASS  NEXT CLASS
SUMMARY: JavaDoc of org.eclipse.core.runtime.Preferences JAVADOC | Sourc code of org.eclipse.core.runtime.Preferences SOURCE | Download org.eclipse.core.runtime.Preferences DOWNLOAD | NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.eclipse.core.runtime
Class Preferences  view Preferences download Preferences.java

java.lang.Object
  extended byorg.eclipse.core.runtime.Preferences
public class Preferences
extends java.lang.Object

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:

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).

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 and contains methods.

Since:
2.0

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).
private  java.util.Properties defaultProperties
          The mapping from property name to default property value (represented as strings); null if none.
protected  boolean dirty
          Indicates whether a value has been changed by setToDefault or setValue; initially false.
static double DOUBLE_DEFAULT_DEFAULT
          The default-default value for double properties (0.0).
private static java.lang.String[] EMPTY_STRING_ARRAY
          Singleton empty string array (optimization)
protected static java.lang.String FALSE
          The string representation used for false ("false").
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).
protected  org.eclipse.core.internal.runtime.ListenerList listeners
          List of registered listeners (element type: IPropertyChangeListener).
static long LONG_DEFAULT_DEFAULT
          The default-default value for long properties (0L).
private  java.util.Properties properties
          The mapping from property name to property value (represented as strings).
static java.lang.String STRING_DEFAULT_DEFAULT
          The default-default value for String properties ("").
protected static java.lang.String TRUE
          The string representation used for true ("true").
 
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(java.lang.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.
private  double convertToDouble(java.lang.String rawPropertyValue, double defaultValue)
          Converts the given raw property value string to a double.
private  float convertToFloat(java.lang.String rawPropertyValue, float defaultValue)
          Converts the given raw property value string to a float.
private  int convertToInt(java.lang.String rawPropertyValue, int defaultValue)
          Converts the given raw property value string to an int.
private  long convertToLong(java.lang.String rawPropertyValue, long defaultValue)
          Converts the given raw property value string to a long.
 java.lang.String[] defaultPropertyNames()
          Returns a list of all properties known to this preference object which have an explicit default value set.
static void exportPreferences(IPath path)
          Exports all non-default-valued preferences for all installed plugins to the provided file.
protected  void firePropertyChangeEvent(java.lang.String name, java.lang.Object oldValue, java.lang.Object newValue)
          Fires a property change event corresponding to a change to the current value of the property with the given name.
 boolean getBoolean(java.lang.String name)
          Returns the current value of the boolean-valued property with the given name.
 boolean getDefaultBoolean(java.lang.String name)
          Returns the default value for the boolean-valued property with the given name.
 double getDefaultDouble(java.lang.String name)
          Returns the default value for the double-valued property with the given name.
 float getDefaultFloat(java.lang.String name)
          Returns the default value for the float-valued property with the given name.
 int getDefaultInt(java.lang.String name)
          Returns the default value for the integer-valued property with the given name.
 long getDefaultLong(java.lang.String name)
          Returns the default value for the long-valued property with the given name.
 java.lang.String getDefaultString(java.lang.String name)
          Returns the default value for the string-valued property with the given name.
 double getDouble(java.lang.String name)
          Returns the current value of the double-valued property with the given name.
 float getFloat(java.lang.String name)
          Returns the current value of the float-valued property with the given name.
 int getInt(java.lang.String name)
          Returns the current value of the integer-valued property with the given name.
 long getLong(java.lang.String name)
          Returns the current value of the long-valued property with the given name.
 java.lang.String getString(java.lang.String name)
          Returns the current value of the string-valued property with the given name.
static void importPreferences(IPath path)
          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(java.lang.String name)
          Returns whether the property with the given name has the default value in virtue of having no explicitly set value.
 void load(java.io.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.
 java.lang.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(java.lang.String name, boolean value)
          Sets the default value for the boolean-valued property with the given name.
 void setDefault(java.lang.String name, double value)
          Sets the default value for the double-valued property with the given name.
 void setDefault(java.lang.String name, float value)
          Sets the default value for the float-valued property with the given name.
 void setDefault(java.lang.String name, int value)
          Sets the default value for the integer-valued property with the given name.
 void setDefault(java.lang.String name, long value)
          Sets the default value for the long-valued property with the given name.
 void setDefault(java.lang.String name, java.lang.String value)
          Sets the default value for the string-valued property with the given name.
 void setToDefault(java.lang.String name)
          Sets the current value of the property with the given name back to its default value.
 void setValue(java.lang.String name, boolean value)
          Sets the current value of the boolean-valued property with the given name.
 void setValue(java.lang.String name, double value)
          Sets the current value of the double-valued property with the given name.
 void setValue(java.lang.String name, float value)
          Sets the current value of the float-valued property with the given name.
 void setValue(java.lang.String name, int value)
          Sets the current value of the integer-valued property with the given name.
 void setValue(java.lang.String name, long value)
          Sets the current value of the long-valued property with the given name.
 void setValue(java.lang.String name, java.lang.String value)
          Sets the current value of the string-valued property with the given name.
 void store(java.io.OutputStream out, java.lang.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

BOOLEAN_DEFAULT_DEFAULT

public static final boolean BOOLEAN_DEFAULT_DEFAULT
The default-default value for boolean properties (false).

See Also:
Constant Field Values

DOUBLE_DEFAULT_DEFAULT

public static final double DOUBLE_DEFAULT_DEFAULT
The default-default value for double properties (0.0).

See Also:
Constant Field Values

FLOAT_DEFAULT_DEFAULT

public static final float FLOAT_DEFAULT_DEFAULT
The default-default value for float properties (0.0f).

See Also:
Constant Field Values

INT_DEFAULT_DEFAULT

public static final int INT_DEFAULT_DEFAULT
The default-default value for int properties (0).

See Also:
Constant Field Values

LONG_DEFAULT_DEFAULT

public static final long LONG_DEFAULT_DEFAULT
The default-default value for long properties (0L).

See Also:
Constant Field Values

STRING_DEFAULT_DEFAULT

public static final java.lang.String STRING_DEFAULT_DEFAULT
The default-default value for String properties ("").

See Also:
Constant Field Values

TRUE

protected static final java.lang.String TRUE
The string representation used for true ("true").

See Also:
Constant Field Values

FALSE

protected static final java.lang.String FALSE
The string representation used for false ("false").

See Also:
Constant Field Values

EMPTY_STRING_ARRAY

private static final java.lang.String[] EMPTY_STRING_ARRAY
Singleton empty string array (optimization)

listeners

protected org.eclipse.core.internal.runtime.ListenerList listeners
List of registered listeners (element type: IPropertyChangeListener). These listeners are to be informed when the current value of a property changes.

properties

private java.util.Properties properties
The mapping from property name to property value (represented as strings).

defaultProperties

private java.util.Properties defaultProperties
The mapping from property name to default property value (represented as strings); null if none.

dirty

protected boolean dirty
Indicates whether a value has been changed by setToDefault or setValue; initially false.

Constructor Detail

Preferences

public Preferences()
Creates an empty preference table.

Use the methods load(InputStream) and store(InputStream) to load and store these preferences.

Method Detail

exportPreferences

public static void exportPreferences(IPath path)
                              throws CoreException
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.

importPreferences

public static void importPreferences(IPath path)
                              throws CoreException
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.

validatePreferenceVersions

public static IStatus validatePreferenceVersions(IPath file)
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 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.

addPropertyChangeListener

public void addPropertyChangeListener(Preferences.IPropertyChangeListener listener)
Adds a property change listener to this preference object. Has no affect if the identical listener is already registered.

removePropertyChangeListener

public void removePropertyChangeListener(Preferences.IPropertyChangeListener listener)
Removes the given listener from this preference object. Has no affect if the listener is not registered.

contains

public boolean contains(java.lang.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. Returns false if the given name is null.

firePropertyChangeEvent

protected void firePropertyChangeEvent(java.lang.String name,
                                       java.lang.Object oldValue,
                                       java.lang.Object newValue)
Fires a property change event corresponding to a change to the current value of the property with the given name.

getBoolean

public boolean getBoolean(java.lang.String name)
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 be null.

setValue

public void setValue(java.lang.String name,
                     boolean value)
Sets the current value of the boolean-valued property with the given name. The given name must not be null.

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.

getDefaultBoolean

public boolean getDefaultBoolean(java.lang.String name)
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 be null.

setDefault

public void setDefault(java.lang.String name,
                       boolean value)
Sets the default value for the boolean-valued property with the given name. The given name must not be null.

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.

getDouble

public double getDouble(java.lang.String name)
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 be null.

setValue

public void setValue(java.lang.String name,
                     double value)
Sets the current value of the double-valued property with the given name. The given name must not be null.

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.

getDefaultDouble

public double getDefaultDouble(java.lang.String name)
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 be null.

setDefault

public void setDefault(java.lang.String name,
                       double value)
Sets the default value for the double-valued property with the given name. The given name must not be null.

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.

convertToDouble

private double convertToDouble(java.lang.String rawPropertyValue,
                               double defaultValue)
Converts the given raw property value string to a double.

getFloat

public float getFloat(java.lang.String name)
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 be null.

setValue

public void setValue(java.lang.String name,
                     float value)
Sets the current value of the float-valued property with the given name. The given name must not be null.

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.

getDefaultFloat

public float getDefaultFloat(java.lang.String name)
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 be null.

setDefault

public void setDefault(java.lang.String name,
                       float value)
Sets the default value for the float-valued property with the given name. The given name must not be null.

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.

convertToFloat

private float convertToFloat(java.lang.String rawPropertyValue,
                             float defaultValue)
Converts the given raw property value string to a float.

getInt

public int getInt(java.lang.String name)
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 integter. The given name must not be null.

setValue

public void setValue(java.lang.String name,
                     int value)
Sets the current value of the integer-valued property with the given name. The given name must not be null.

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.

getDefaultInt

public int getDefaultInt(java.lang.String name)
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 be null.

setDefault

public void setDefault(java.lang.String name,
                       int value)
Sets the default value for the integer-valued property with the given name. The given name must not be null.

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.

convertToInt

private int convertToInt(java.lang.String rawPropertyValue,
                         int defaultValue)
Converts the given raw property value string to an int.

getLong

public long getLong(java.lang.String name)
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 be null.

setValue

public void setValue(java.lang.String name,
                     long value)
Sets the current value of the long-valued property with the given name. The given name must not be null.

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.

getDefaultLong

public long getDefaultLong(java.lang.String name)
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 be null.

setDefault

public void setDefault(java.lang.String name,
                       long value)
Sets the default value for the long-valued property with the given name. The given name must not be null.

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.

convertToLong

private long convertToLong(java.lang.String rawPropertyValue,
                           long defaultValue)
Converts the given raw property value string to a long.

getString

public java.lang.String getString(java.lang.String name)
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 be null.

setValue

public void setValue(java.lang.String name,
                     java.lang.String value)
Sets the current value of the string-valued property with the given name. The given name must not be null.

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.

getDefaultString

public java.lang.String getDefaultString(java.lang.String name)
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 be null.

setDefault

public void setDefault(java.lang.String name,
                       java.lang.String value)
Sets the default value for the string-valued property with the given name. The given name must not be null.

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.

isDefault

public boolean isDefault(java.lang.String name)
Returns whether the property with the given name has the default value in virtue of having no explicitly set value. Returns false if the given name is null.

setToDefault

public void setToDefault(java.lang.String name)
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 be null.

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.

propertyNames

public java.lang.String[] propertyNames()
Returns a list of all properties known to this preference object which have current values other than their default value.

defaultPropertyNames

public java.lang.String[] defaultPropertyNames()
Returns a list of all properties known to this preference object which have an explicit default value set.

needsSaving

public boolean needsSaving()
Returns whether the current values in this preference object require saving.

store

public void store(java.io.OutputStream out,
                  java.lang.String header)
           throws java.io.IOException
Saves the non-default-valued properties known to this preference object to the given output stream using Properties.store(OutputStream,String).

Note that the output is unconditionally written, even when needsSaving is false.

load

public void load(java.io.InputStream in)
          throws java.io.IOException
Loads the non-default-valued properties for this preference object from the given input stream using java.util.Properties.load(InputStream). Default property values are not affected.

Overview  Package   Class  Use  Deprecated  Index 
Home >> All >> org >> eclipse >> core >> [ runtime overview ]  PREV CLASS  NEXT CLASS
SUMMARY: JavaDoc of org.eclipse.core.runtime.Preferences JAVADOC | Sourc code of org.eclipse.core.runtime.Preferences SOURCE | Download org.eclipse.core.runtime.Preferences DOWNLOAD | NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD