the foundation of the platform

[home] [documents] [downloads] [resources] [planning] [testing]

Potential API problems in Eclipse 3.1
Property change events (typing)

Summary: Property change events occur when a new property key/value pair is added to the preference store, when a value is changed, or when a key is removed. The old and new values for the key/value pair are included in the property change event objects that are broadcast to all registered listeners.

The lowest Core level preference APIs specify the types of the value in the event object to be either a String representation of the value or null. The upper Core level APIs and the JFace APIs specify the types to be real types. (e.g. Integer for int, Boolean for boolean, etc)

There is also a problem with the upper Core and JFace preferences that has always existed but has surfaced recently with the move to the new implementation underneath. Since the preferences are store un-typed on the file system, there are certain cases where we donít know the type of the preference value when replacing it or removing it from the store. One example occurs when you import new preference values.

Solution: We discussed the problem with Jeem and came to the conclusion that the old specs should be updated to say that the values in the property change events will be typed if possible, but also may be String values. Proper clients should be able to react to both situations.

Status: Done.


No notification during #putValue()

Summary: The JFace APIs have a new method called IPreferenceStore#putValue() which stores the value of the preference in the preference store but does not notify any listeners. This method is intended for use by client decorators and in other applications where setting preference values are required to be more performent.

One of the client use cases for preference change listeners is to cache the preference values locally and then update the cache when someone changes the values via the regular API and a change event is received. The problem occurs when another client calls the #putValue() API and the cache's listener is not notified and the cache will become out of sync.

A concrete example of this occurs with the org.eclipse.core.resources plug-in and the workspace description. For performance reasons, it was decided to cache the preference value of whether or not the workspace is in auto-build mode. A preference change listener is registered and when any client changes this value, the cache is updated. If clients change this value via #putValue() then the Resources plug-in's listener will not be notified and the value for IWorkspaceDescription#isAutoBuilding() will be out of date.

Solution: The spec for IPreferenceStore#putValue() should be updated to say that clients should only be calling this method on their own private preference keys and should not be modifying any preference keys which are public API.

Status: To Be Done. Bug 76940 follows the status of this problem.


RCP plug-ins and no instance location

Summary: Plug-ins which are part of the RCP should be able to handle the case where we are running with no instance location. This includes accessing their preferences via Plugin#getPluginPreferences() and AbstractUIPlugin#getPreferenceStore() which accesses the preferences in the instance scope.

Currently the org.eclipse.ui plug-in accesses its instance preferences indirectly by calling #getPreferenceStore().setDefault() in its preference initialization code. Other plug-ins did the same thing but have been converted to use the new API to access the default preference scope.

Solution: Code in the preference initializer which accessed the instance and default scopes should be changed only to access the default scope and set the default preference values on that node directly.

Status: Done. Bug 76506 was entered to track the last of the issues. It has been verified that all the plug-ins that are part of the RCP use the new preference APIs and don't access the instance area before it has been set.