platform-core/documents/user_settings/pref_apis.html - www.eclipse.org/eclipse - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 <html>
 <head>
 <title>Eclipse Platform/Core</title>
 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
 <link rel="stylesheet" href="http://dev.eclipse.org/default_style.css" type="text/css">
 </head>
 <body>
 <center>
 	<font class=indextop>core</font><br>
 	<font class=indexsub>the foundation of the platform</font><p></p>
 	<a href="../../main.html">[home]</a>
 	<a href="../../documents.html">[documents]</a>
 	<a href="../../downloads.html">[downloads]</a>
 	<a href="../../resources.html">[resources]</a>
 	<a href="../../planning.html">[planning]</a>
 	<a href="../../testing.html">[testing]</a>
 </center>
 <br>
 <table BORDER=0 CELLPADDING=2 WIDTH="100%" >
 	<tr>
 		<td ALIGN=LEFT VALIGN=TOP COLSPAN="2" BGCOLOR="#0080C0"><b><font face="Arial,Helvetica" color="#FFFFFF">Potential API problems in Eclipse 3.1</font></b></td>
 	</tr>
 	<tr><td colspan="2">&nbsp;</td></tr>
 	<tr>
 		<td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>
     	<td WIDTH="98%"><b>Property change events (typing)</b>
 <p><u>Summary:</u> 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.</p>
 <p>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. <code>Integer</code> for <code>int</code>, <code>Boolean</code> for <code>boolean</code>,
   etc)</p>
 <p>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 dont 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.</p>
 <p><u>Solution:</u> 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.</p>
 <p><u>Status:</u> Done.</p><p>&nbsp;</p>
 		</td>
 	</tr>
 	<tr>
 		<td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>
     	<td WIDTH="98%"><b>No notification during <code>#putValue()</code></b>
 <p><u>Summary:</u> The JFace APIs have a new method called <code>IPreferenceStore#putValue()</code>
   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.</p>
 <p>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 <code>#putValue()</code> API and the cache's listener
   is not notified and the cache will become out of sync.
 </p>
 <p>A concrete example of this occurs with the <code>org.eclipse.core.resources</code>
 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 <code>#putValue()</code> then the Resources plug-in's
 listener will not be notified and the value for <code>IWorkspaceDescription#isAutoBuilding()</code> will be out of date.
 </p>

 <p><u>Solution:</u> The spec for <code>IPreferenceStore#putValue()</code> 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.</p>
 <p><u>Status:</u> To Be Done. Bug <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=76940">76940</a> follows the status of this problem.</p><p>&nbsp;</p>
 		</td>
 	</tr>
 	<tr>
 		<td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>
     	<td WIDTH="98%"><b>RCP plug-ins and no instance location</b>
 <p><u>Summary:</u> 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 <code>Plugin#getPluginPreferences()</code> and <code>AbstractUIPlugin#getPreferenceStore()</code> which accesses the preferences in the instance scope.</p>
   <p>Currently the <code>org.eclipse.ui</code> plug-in accesses its instance preferences
   indirectly by calling <code>#getPreferenceStore().setDefault()</code> 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.</p>
 <p><u>Solution:</u> 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. </p>
 <p><u>Status:</u> Done. Bug <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=76506">76506</a>
 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.</p><p>&nbsp;</p>
 		</td>
 	</tr>
 </table>


 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	<html>
	<head>
	<title>Eclipse Platform/Core</title>
	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
	<link rel="stylesheet" href="http://dev.eclipse.org/default_style.css" type="text/css">
	</head>
	<body>
	<center>
	<font class=indextop>core</font><br>
	<font class=indexsub>the foundation of the platform</font><p></p>
	<a href="../../main.html">[home]</a>
	<a href="../../documents.html">[documents]</a>
	<a href="../../downloads.html">[downloads]</a>
	<a href="../../resources.html">[resources]</a>
	<a href="../../planning.html">[planning]</a>
	<a href="../../testing.html">[testing]</a>
	</center>
	<br>
	<table BORDER=0 CELLPADDING=2 WIDTH="100%" >
	<tr>
	<td ALIGN=LEFT VALIGN=TOP COLSPAN="2" BGCOLOR="#0080C0"><b><font face="Arial,Helvetica" color="#FFFFFF">Potential API problems in Eclipse 3.1</font></b></td>
	</tr>
	<tr><td colspan="2"> </td></tr>
	<tr>
	<td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>
	<td WIDTH="98%"><b>Property change events (typing)</b>
	<p><u>Summary:</u> 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.</p>
	<p>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. <code>Integer</code> for <code>int</code>, <code>Boolean</code> for <code>boolean</code>,
	etc)</p>
	<p>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 dont 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.</p>
	<p><u>Solution:</u> 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.</p>
	<p><u>Status:</u> Done.</p><p> </p>
	</td>
	</tr>
	<tr>
	<td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>
	<td WIDTH="98%"><b>No notification during <code>#putValue()</code></b>
	<p><u>Summary:</u> The JFace APIs have a new method called <code>IPreferenceStore#putValue()</code>
	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.</p>
	<p>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 <code>#putValue()</code> API and the cache's listener
	is not notified and the cache will become out of sync.
	</p>
	<p>A concrete example of this occurs with the <code>org.eclipse.core.resources</code>
	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 <code>#putValue()</code> then the Resources plug-in's
	listener will not be notified and the value for <code>IWorkspaceDescription#isAutoBuilding()</code> will be out of date.
	</p>

	<p><u>Solution:</u> The spec for <code>IPreferenceStore#putValue()</code> 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.</p>
	<p><u>Status:</u> To Be Done. Bug <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=76940">76940</a> follows the status of this problem.</p><p> </p>
	</td>
	</tr>
	<tr>
	<td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>
	<td WIDTH="98%"><b>RCP plug-ins and no instance location</b>
	<p><u>Summary:</u> 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 <code>Plugin#getPluginPreferences()</code> and <code>AbstractUIPlugin#getPreferenceStore()</code> which accesses the preferences in the instance scope.</p>
	<p>Currently the <code>org.eclipse.ui</code> plug-in accesses its instance preferences
	indirectly by calling <code>#getPreferenceStore().setDefault()</code> 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.</p>
	<p><u>Solution:</u> 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. </p>
	<p><u>Status:</u> Done. Bug <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=76506">76506</a>
	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.</p><p> </p>
	</td>
	</tr>
	</table>


	</body>
	</html>