org.eclipse.platform.doc.isv/porting/3.3/incompatibilities.html

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.19 - (view) (download) (as text)

1 : johna 1.1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2 : mcq 1.19 <html lang="en">
3 : johna 1.1 <head>
4 : aniefer 1.8 <meta name="copyright" content="Copyright (c) IBM Corporation and others 2006, 2007. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
5 : johna 1.1 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6 :     <meta http-equiv="Content-Style-Type" content="text/css">
7 :     <link rel="STYLESHEET" href="../../book.css" charset="ISO-8859-1" type="text/css">
8 :     <title>Incompatibilities between Eclipse 3.2 and 3.3</title>
9 :     </head>
10 :     <body>
11 :     <h1>Incompatibilities between Eclipse 3.2 and 3.3</h1>
12 :    
13 :     <p> Eclipse changed in incompatible ways between 3.2 and 3.3 in ways that affect
14 :     plug-ins. The following entries describe the areas that changed and provide
15 :     instructions for migrating 3.2 plug-ins to 3.3. Note that you only need to look
16 :     here if you are experiencing problems running your 3.2 plug-in on 3.3.</p>
17 :     <p></p>
18 :     <ol>
19 : johna 1.4 <li><a href="#launchConfigWorkingCopies">Nested Launch Configuration Working Copies</a></li>
20 :     <li><a href="#FileEditorInput">Incompatible source change to getStorage() on FileEditorInput</a></li>
21 : twatson 1.5 <li><a href="#BootDelegation">Boot delegation changes</a></li>
22 :     <li><a href="#LazyActivation">Lazy activation changes</a></li>
23 :     <li><a href="#getEntryPaths">Clarification to Bundle.getEntryPaths</a></li>
24 : mvalenta 1.6 <li><a href="#HistoryView">History View didn't follow spec of IHistoryPageSource</a></li>
25 : mvalenta 1.7 <li><a href="#Proxy">Proxy settings are now managed by the platform</a></li>
26 : aniefer 1.8 <li><a href="#startup.jar">Launching Eclipse with startup.jar</a></li>
27 : sfranklin 1.9 <li><a href="#DeviceResourceDescriptor">Incompatible source change to DeviceResourceDescriptor#createResource</a></li>
28 : sfranklin 1.10 <li><a href="#ResourceManager">Incompatible source change to ResourceManager resource creation methods</a></li>
29 : tod 1.11 <li><a href="#jface-backcalls">JFace viewers and recursive back-calls</a></li>
30 : tod 1.12 <li><a href="#IIDEActionConstants">IIDEActionConstants.FIND_EXT corrected to conform to specification</a></li>
31 : tod 1.13 <li><a href="#IDEEncoding">IDEEncoding#setResourceEncoding deleted</a></li>
32 : tod 1.14 <li><a href="#ErrorDialog">ErrorDialog client area has a potential extra column</a></li>
33 : cgoldthor 1.16 <li><a href="#IIndexEntry">Binary incompatibility in IIndexEntry</a></li>
34 :     <li><a href="#FormColors">Constant changed in FormColors</a></li>
35 : pwebster 1.18 <li><a href="#ActionHandler">UI ActionHandler depends on IAction#ENABLED</a></li>
36 : tod 1.11 </ol>
37 : johna 1.1 <hr>
38 :    
39 :     <!-- ############################################## -->
40 : tod 1.12 <h2>1. <a name="launchConfigWorkingCopies">Nested Launch Configuration Working Copies</a></h2>
41 : darin 1.2 <p><strong>What is affected:</strong> Launch configuration working copies support
42 :     nesting in 3.3. Clients that programmatically create and save launch configurations
43 :     may be affected by the change in behavior of the <code>ILaunchConfigurationWorkingCopy.doSave()
44 :     </code> method. </p>
45 :     <p><strong>Description:</strong> When a working copy (B) is created from a working
46 :     copy (A) which was created from a launch configuration (X), the newly created
47 :     working copy (B) is initialized with the attributes from the first working copy
48 :     (A). In 3.3, whenever a working copy is saved, it is written back to the configuration
49 :     from which it was created. In this example working copy B will saves changes
50 :     back to working copy A, and A will save changes back to the original launch
51 :     configuration. A nested working copy has a parent working copy that can be retrieved
52 :     by calling <code>getParent()</code> (newly added in 3.3). In 3.2, working copies
53 :     were not nested and saving a working copy always resulted in the changes being
54 :     saved back to the original launch configuration.</p>
55 : darin 1.3 <p><strong>Action required:</strong> APIs are binary compatible but clients should
56 :     examine calls to <code>ILaunchConfiguration.getWorkingCopy()</code> and <code>ILaunchConfigurationWorkingCopy.doSave()</code>
57 :     to determine if nested working copies might be created. Note that saving a nested
58 :     working copy will not save changes back to the original launch configuration.</p>
59 : johna 1.1 <!-- ############################################## -->
60 : tod 1.12 <h2>2. <a name="FileEditorInput">Incompatible source change to getStorage() on FileEditorInput</a></h2>
61 : johna 1.4 <p><strong>What is affected:</strong> Clients that call getStorage() on FileEditorInput.</p>
62 :     <p><strong>Description:</strong> The signature of getStorage() was changed to
63 :     no longer throw a checked exception. This may cause compile errors in source code
64 :     previously compiled against Eclipse 3.2 that is recompiled against 3.3. This change
65 :     does not break binary compatibility - existing clients built against Eclipse 3.2 or
66 :     earlier will continue to function normally.</p>
67 :     <p><strong>Action required:</strong> Clients should recompile against Eclipse 3.3,
68 :     and remove any catch block that is now unnecessary due to the removed exception.</p>
69 :     <!-- ############################################## -->
70 : tod 1.12 <h2>3. <a name="BootDelegation">Boot delegation changes</a></h2>
71 : twatson 1.5 <p><strong>What is affected:</strong> The boot delegation order has changed in 3.3. Bundles that depend on delegating
72 :     to the boot (parent) class loader first may be affected by this change.</p>
73 : johna 1.15 <p><strong>Description:</strong> In Eclipse 3.3 the default class loader delegation model has been changed to the following order:</p>
74 : twatson 1.5 <ol>
75 :     <li>Imported packages (i.e. packages specified in the Import-Package manifest header).</li>
76 :     <li>Required bundles (i.e. bundles specified in the Require-Bundle manifest header).</li>
77 :     <li>Local bundle and fragments.</li>
78 :     <li>Boot (parent) class loader as a last resort. This is only done if no source was found in the previous steps. </li>
79 :     </ol>
80 : johna 1.15 <p>In 3.2 the boot (parent) class loader is always delegated to first. This provides no isolation from the
81 : twatson 1.5 classes provided by the VM. It also affects performance because the boot class loader must be delegated to for every
82 :     load even though it is known that the class or resource is located in a bundle. Because of the boot delegation changes
83 :     in 3.3, a bundle can now provide their own version of a package which is also available from the VM boot classpath.
84 : johna 1.15 See <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=162231"> bug 162231</a>.</p>
85 : tod 1.12
86 : twatson 1.5 <p><strong>Action required:</strong> Bundles that export packages which may be available by the boot (parent) class loader
87 :     need to evaluate whether the classes/resources they export should be added to the content from the boot class loader or replace it.
88 :     If the exporting bundle should replace the content of the boot class loader then no action is required. If the exporting bundle should
89 :     add to the content of the boot class loader then the exporting bundle should add &quot;system.bundle&quot; as a required bundle
90 :     (i.e. Require-Bundle: system.bundle). To revert back to the behavior in 3.2 the configuration property
91 :     &quot;org.osgi.framework.bootdelegation=*&quot; can be added to the config.ini file. </p>
92 :     <!-- ############################################## -->
93 : mvalenta 1.6 <h2>4. <a name="LazyActivation">Lazy activation changes</a></h2>
94 : twatson 1.5 <p><strong>What is affected:</strong> Bundles that use the lazy activation policy (i.e. &quot;Eclipse-LazyStart: true&quot;)
95 :     will enter the Bundle.STARTING state as soon as they are eligible for lazy activation. Clients that monitor the Bundle.STARTING
96 :     state may be affected by this change.
97 :     </p>
98 :     <p><strong>Description:</strong> Eclipse 3.3 implements the OSGi R4.1 specification. The OSGi R4.1 specification
99 :     standardizes the lazy activation policy implemented in Eclipse. Part of the standardization work changed the behavior of how
100 :     bundles states are transitioned when a lazy activation policy is used. When a bundle becomes available for lazy activation the bundle
101 :     enters the Bundle.STATING state and a BundleEvent.LAZY_ACTIVATION event is fired. This occurs before any class load
102 :     request is made to the bundle. The bundle will remain in the Bundle.STARTING state until the first class load is made and
103 :     the bundle is activated. When the bundle is activated a BundleEvent.STARTING event is fired and the BundleActivator.start method
104 :     is called. See <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=135885">bug 135885</a>.
105 :     </p>
106 :     <p>
107 :     Bundles with a lazy activation policy could remain in the Bundle.STARTING state for a long time waiting for the first class load
108 :     (trigger load) to occur. Entering the Bundle.STARTING state does not mean the BundleActivator.start method has been called.
109 :     The BundleActivator.start method is only called right after the BundleEvent.STARTING event is fired. Bundles that monitor calls to
110 :     BundleActivators must use a SynchronousBundleListener to listen for the BundleEvent.STARTING and BundleEvent.STOPPING
111 :     events.
112 :     </p>
113 :     <p><strong>Action required:</strong> A SynchronousBundleListener must be used to monitor BundleEvent.STARTING and
114 :     BundleEvent.STOPPING events for clients that are monitoring the calls to BundleActivators.</p>
115 :     <!-- ############################################## -->
116 : mvalenta 1.6 <h2>5. <a name="getEntryPaths">Clarification to Bundle.getEntryPaths</a></h2>
117 : twatson 1.5 <p><strong>What is affected:</strong> Clients of the Bundle.getEntryPaths method.
118 :     </p>
119 :     <p><strong>Description:</strong> The OSGi R4.1 specification has made a clarification on the behavior of the
120 :     org.osgi.framework.Bundle#getEntryPaths method. The javadoc for the method Bundle#getEntryPaths did not
121 :     make it clear whether the String paths returned had a leading &quot;/&quot; character or not. The following clarification has
122 : johna 1.15 been made:</p>
123 : twatson 1.5 <p>
124 :     The returned paths are all relative to the root of this bundle and must not begin with &quot;/&quot;.
125 :     </p>
126 :     Eclipse 3.2 had a bug for directory (non-jarred) bundles where a leading &quot;/&quot; character was included in the result if
127 :     the client used a path argument that contained a leading &quot;/&quot;. For jarred bundles Eclipse 3.2 always ensures
128 :     the returned paths do not have a leading &quot;/&quot; character. This is inconsistent behavior. Directory bundles have
129 :     been fixed to be consistent with jarred bundles. See <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=174101"> bug 174101</a>.
130 : tod 1.12
131 : twatson 1.5 <p><strong>Action required:</strong> Some clients may have a dependency on the old behavior for directory bundles. If a client
132 :     uses the method Bundle#getEntryPaths then ensure that it can handle returned paths that do not begin with a &quot;/&quot; character.
133 :     This dependency is a bug in the client code because it would have failed for jarred bundles.
134 :     </p>
135 :     <!-- ############################################## -->
136 : mvalenta 1.6 <h2>6. <a name="HistoryView">History View didn't follow spec of IHistoryPageSource</a></h2>
137 :     <p><strong>What is affected:</strong> The History view may no longer show the history for certain elements.
138 :     </p>
139 :     <p><strong>Description:</strong> In 3.2, the History view did not follow the specification of IHistoryPageSource in
140 :     the sense that, in some situations, it did not call canShowHistoryFor(Object) before requesting a history page.
141 :     In 3.3, this was corrected which has lead to a situation where client code may have worked in 3.2 even though their implementation of
142 :     IHistoryPageSource did not follow the specification in the javadoc.
143 :     </p>
144 :     <p><strong>Action required:</strong> Implementors of IHistoryPageSource need to ensure that their implementation follows
145 :     the specification defined in the javadoc of the interface.
146 :     </p>
147 :     <!-- ############################################## -->
148 : mvalenta 1.7 <h2>7. <a name="Proxy">Proxy settings are now managed by the platform</a></h2>
149 :     <p><strong>What is affected:</strong> plug-ins in Eclipse that provided their own support for proxy specification
150 :     (e.g HTTP, SSL or SOCKS).</p>
151 :     <p><strong>Description:</strong> A preference page and API was added in 3.3 to support the specification
152 :     of HTTP, SSL and SOCKS proxies. Any tooling that provided their own support for this may conflict with the new
153 :     settings being managed by the Platform. The fix should be for tooling to remove their support for specifying
154 :     proxies and adopt the support provided by the Platform.
155 : aniefer 1.8 </p>
156 :     <!-- ############################################## -->
157 :     <h2>8. <a name="startup.jar">Launching Eclipse with startup.jar</a></h2>
158 :     <p><strong>What is affected:</strong> Eclipse can no longer be started
159 :     with <tt>java -jar startup.jar</tt>.<br>
160 :     </p>
161 :     <p><strong>Description:</strong> In 3.2, Eclipse was started using
162 :     startup.jar from the root of the Eclipse install. In 3.3, this jar is a
163 :     bundle in the plugins directory named org.eclipse.equinox.launcher. </p>
164 :     <p><strong>Action required:</strong> Change the command to <tt>java
165 :     -jar
166 :     plugins/org.eclipse.equinox.launcher_1.0.0.&lt;version&gt;.jar</tt> or
167 :     use
168 :     the eclipse launcher executable.
169 :     </p>
170 : mvalenta 1.7 <!-- ############################################## -->
171 : tod 1.11 <h2>9. <a name="DeviceResourceDescriptor">Incompatible source change to DeviceResourceDescriptor#createResource</a></h2>
172 : sfranklin 1.10 <p><strong>What is affected:</strong> Clients that call createResource(Device) on
173 :     DeviceResourceDescriptor.</p>
174 :     <p><strong>Description:</strong> The DeviceResourceException thrown by JFace has been
175 :     changed to a runtime exception. As part of this change, the method signature of
176 :     createResource(Device) was changed to no longer throw the exception. This may cause
177 :     compile errors in source code
178 :     previously compiled against Eclipse 3.2 that is recompiled against 3.3. This change
179 :     does not break binary compatibility - existing clients built against Eclipse 3.2 or
180 :     earlier will continue to function normally.</p>
181 :     <p><strong>Action required:</strong> Clients should recompile against Eclipse 3.3,
182 :     and remove any catch block that is now unnecessary due to the removed exception.</p>
183 :     <!-- ############################################## -->
184 : tod 1.11 <h2>10. <a name="ResourceManager">Incompatible source change to ResourceManager resource creation methods</a></h2>
185 : sfranklin 1.10 <p><strong>What is affected:</strong> Clients that call resource creation methods on
186 :     ResourceManager.</p>
187 :     <p><strong>Description:</strong> The DeviceResourceException thrown by JFace has been
188 :     changed to a runtime exception. As part of this change, the following method signatures
189 :     were changed to no longer throw the exception.
190 :     </p>
191 :     <ul>
192 :     <li>ResourceManager#create(DeviceResourceDescriptor)</li>
193 :     <li>ResourceManager#createColor(ColorDescriptor)</li>
194 :     <li>ResourceManager#createColor(RGB)</li>
195 :     <li>ResourceManager#createFont(FontDescriptor)</li>
196 :     <li>ResourceManager#createImage(ImageDescriptor)</li>
197 :     </ul>
198 :     <p>
199 :     These changes may cause compile errors in source code
200 : sfranklin 1.9 previously compiled against Eclipse 3.2 that is recompiled against 3.3. This change
201 :     does not break binary compatibility - existing clients built against Eclipse 3.2 or
202 :     earlier will continue to function normally.</p>
203 :     <p><strong>Action required:</strong> Clients should recompile against Eclipse 3.3,
204 :     and remove any catch block that is now unnecessary due to the removed exception.</p>
205 :     <!-- ############################################## -->
206 : tod 1.11
207 :     <h2>11. <a name="jface-backcalls">JFace viewers and recursive back-calls</a></h2>
208 :     <p><strong>What is affected:</strong> Clients of <tt>TableViewer</tt> and <tt>TreeViewer</tt>, implementers of <tt>IStructuredContentProvider</tt> or <tt>IBaseLabelProvider</tt></p>
209 :     <p><strong>Description:</strong> <tt>StructuredViewer</tt> and its subclasses were never designed to handle
210 :     recursive back-calls to methods such as <tt>setInput()</tt>, <tt>refresh()</tt>, <tt>add()</tt>,
211 :     <tt>remove()</tt>, <tt>update()</tt> etc. In the past, calls to one of these update
212 :     methods that happened while the viewer was already in the process of
213 :     processing another update, lead to unpredictable behavior or even
214 :     runtime errors later on that were hard to debug. Starting with 3.3,
215 :     subclasses of ColumnViewer detect recursive back-calls, log an error and
216 :     ignore the nested update request. This helps uncover programming errors
217 :     such as spinning the event loop from a content provider or label
218 :     provider, but potentially changes the behavior in cases where clients
219 :     used recursive back-calls but didn't see immediate problems in the past in
220 :     their particular usage scenarios. See <a
221 :     href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=154571">bug
222 :     154571</a> for details.</p>
223 :     <p><strong>Action required:</strong> No action required if you don't see
224 :     entries about ignored calls in the .log file. If you do see log entries,
225 :     the provided stack trace should have sufficient information to find the
226 :     problematic back-call. Depending on the situation, you might need to post
227 :     an asyncExec runnable to avoid the back-call.</p>
228 :     <!-- ############################################## -->
229 : tod 1.12 <h2>12. <a name="IIDEActionConstants"> IIDEActionConstants.FIND_EXT corrected to conform to specification</a></h2>
230 :     <p><strong>What is affected:</strong> Clients of <tt>IIDEActionConstants</tt> who use the values directly instead of via the constant.</p>
231 : johna 1.15 <p><strong>Description:</strong> Edit menu: name of group for extra Find-like actions (value <code>"find.ext"</code>).</p>
232 : tod 1.12 <p>The value of this constant has changed in 3.3 to match the specification; before 3.3, its value was incorrect (<code>"cut.ext"</code>).
233 :     See <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=155856">bug 155856</a> for details.</p>
234 :     <p><strong>Action required:</strong> No action required if you refer to the constant rather than its value.</p>
235 :     <!-- ############################################## -->
236 : tod 1.13 <h2>13. <a name="IDEEncoding">IDEEncoding#setResourceEncoding deleted</a></h2>
237 :     <p><strong>What is affected:</strong> Clients of <tt>IDEEncoding</tt>.</p>
238 :     <p><strong>Description:</strong> <code>IDEEncoding#setResourceEncoding</code> was deprecated in 3.2 (the same release it was
239 :     added in) in favor of setting the ResourcesPlugin.PREF_ENCODING value
240 :     in the Resources plug-ins preference store. It was not deleted in the 3.2 release despite never having been valid API.
241 :     It was deleted in the 3.3 release. </p>
242 :     <p><strong>Action required:</strong> Update references to <code>IDEEncoding#setEncoding</code> to calls to
243 :     <code>ResourcesPlugin#getPlugin()#getPluginPreferences()#setValue(ResourcesPlugin.PREF_ENCODING,value)</code>.</p>
244 :     <!-- ############################################## -->
245 : tod 1.14 <h2>14. <a name="ErrorDialog">ErrorDialog client area has a potential extra column</a></h2>
246 : cgoldthor 1.16 <p><strong>What is affected:</strong> Subclasses of <tt>ErrorDialog</tt>.</p>
247 : tod 1.14 <p><strong>Description:</strong> <code>ErrorDialogs</code> will have an extra column in their client area
248 : cgoldthor 1.16 if there is an <code>ErrorSupportProvider</code> registered in an install. ErrorDialog subclasses that assume
249 : johna 1.15 there are 2 columns should call <code>IconAndMessageDialog#getColumnCount</code> instead.</p>
250 : tod 1.14 <p><strong>Action required:</strong> Update hard coded column counts to call to <code>IconAndMessageDialog#getColumnCount</code> .</p>
251 :     <!-- ############################################## -->
252 : cgoldthor 1.16 <h2>15. <a name="IIndexEntry">Binary incompatibility in IIndexEntry</a></h2>
253 : johna 1.17 <p><strong>What is affected:</strong> Clients of IIndexEntry who rely on binary compatibility.</p>
254 : cgoldthor 1.16 <p><strong>Description:</strong> The return type of function getTopics() has changed from IHelpResource[] to the subclass ITopic[].
255 :     See <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=191224">bug 191224</a> for details.</p>
256 :     <p><strong>Action required:</strong> Source which uses this interface must be recompiled.</p>
257 :     <!-- ############################################## -->
258 :     <h2>16. <a name="FormColors">Constant changed in FormColors</a></h2>
259 :     <p><strong>What is affected:</strong> Clients of FormColors who rely on binary compatibility.</p>
260 :     <p><strong>Description:</strong> The value of the constant org.eclipse.ui.forms.FormColors.TB_GBG changed in Eclipse 3.3.
261 :     See <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=191233">bug 191233</a> for details.</p>
262 :     <p><strong>Action required:</strong> Update hard coded column counts to call to <code>IconAndMessageDialog#getColumnCount</code> .</p>
263 :     <!-- ############################################## -->
264 : pwebster 1.18 <h2>17. <a name="ActionHandler">UI ActionHandler depends on IAction#ENABLED</a></h2>
265 :     <p><strong>What is affected:</strong> Clients using <code>IKeyBindingService#registerAction(IAction)</code> or using <code>org.eclipse.ui.commands.ActionHandler</code>
266 :     to submit <code>IActions</code> to the handler service.</p>
267 :     <p><strong>Description:</strong> Commands now add listeners to their handlers. The <code>ActionHandler</code> will now depend on
268 :     the IAction firing the property change for <b>ENABLED</b> to update its enabled state. One side effect is that
269 :     <code>IAction#isEnabled()</code> will not be called frequently.</p>
270 :     <p><strong>Action required:</strong> Clients must ensure their <code>IActions</code> do not require frequent callings of <code>isEnabled()</code> to manage their enabled state,
271 :     and must fire the <b>ENABLED</b> property at the appropriate times.</p>
272 :     <!-- ############################################## -->
273 : johna 1.1 </body>
274 :     </html>