org.eclipse.platform.doc.isv/porting/3.0/incompatibilities.html
Parent Directory
| 
Revision Log
Revision 1.11 - (view) (download) (as text)
| 1 : | johna | 1.1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 : | <html> | ||
| 3 : | |||
| 4 : | <head> | ||
| 5 : | tod | 1.4 | |
| 6 : | <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." > | ||
| 7 : | tod | 1.3 | |
| 8 : | johna | 1.1 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| 9 : | <meta http-equiv="Content-Style-Type" content="text/css"> | ||
| 10 : | mvalenta | 1.5 | <link rel="STYLESHEET" href="../../book.css" charset="ISO-8859-1" type="text/css"> |
| 11 : | johna | 1.1 | <title>Incompatibilities between Eclipse 2.1 and 3.0</title> |
| 12 : | </head> | ||
| 13 : | |||
| 14 : | <body> | ||
| 15 : | |||
| 16 : | <h1>Incompatibilities between Eclipse 2.1 and 3.0</h1> | ||
| 17 : | dmegert | 1.6 | |
| 18 : | <p> Eclipse changed in | ||
| 19 : | johna | 1.1 | incompatible ways between 2.1 and 3.0 in ways that affect plug-ins. The |
| 20 : | following entries describe the areas that changed and provide instructions for | ||
| 21 : | migrating | ||
| 22 : | 2.1 plug-ins to 3.0. Note that you only need to look here if you are experiencing | ||
| 23 : | problems running your 2.1 plug-in on 3.0.</p> | ||
| 24 : | <ol> | ||
| 25 : | <li><a href="#Plug-in manifest version">Plug-in manifest version</a></li> | ||
| 26 : | <li><a href="#Restructuring of Platform UI plug-ins">Restructuring of Platform UI plug-ins</a></li> | ||
| 27 : | <li><a href="#Restructuring of Platform Core Runtime plug-ins"> Restructuring of Platform Core Runtime plug-ins</a></li> | ||
| 28 : | <li><a href="#Removal of Xerces plug-in"> Removal of Xerces plug-in</a></li> | ||
| 29 : | <li><a href="#Eclipse 3.0 is more concurrent"> Eclipse 3.0 is more concurrent</a></li> | ||
| 30 : | <li><a href="#Opening editors on IFiles"> Opening editors on IFiles</a></li> | ||
| 31 : | <li><a href="#Editor goto marker">Editor goto marker</a></li> | ||
| 32 : | <li><a href="#Editor launcher">Editor launcher</a></li> | ||
| 33 : | <li><a href="#Editor registry">Editor registry</a></li> | ||
| 34 : | <li><a href="#Workbench marker help registry"> Workbench marker help registry</a></li> | ||
| 35 : | <li><a href="#Text editor document providers"> Text editor document providers</a></li> | ||
| 36 : | <li><a href="#Text editors">Text editors</a></li> | ||
| 37 : | <li><a href="#Headless annotation support">Headless annotation support</a></li> | ||
| 38 : | <li><a href="#Console view">Console view</a></li> | ||
| 39 : | <li><a href="#Java breakpoint listeners">Java breakpoint listeners</a></li> | ||
| 40 : | <li><a href="#Clipboard access in UI thread"> Clipboard access in UI thread</a></li> | ||
| 41 : | <li><a href="#Key down events">Key down events</a></li> | ||
| 42 : | <li><a href="#Tab traversal of custom controls"> Tab traversal of custom controls</a></li> | ||
| 43 : | <li><a href="#Selection event order in SWT table and tree widgets"> Selection event order in SWT table and tree widgets</a></li> | ||
| 44 : | <li><a href="#New severity level in status objects"> New severity level in status objects</a></li> | ||
| 45 : | <li><a href="#Build-related resource change notifications"> Build-related resource change notifications</a></li> | ||
| 46 : | <li><a href="#Intermediate notifications during workspace operations"> Intermediate notifications during workspace operations</a></li> | ||
| 47 : | <li><a href="#URL stream handler extensions"> URL stream handler extensions</a></li> | ||
| 48 : | <li><a href="#Class load order">Class load order</a></li> | ||
| 49 : | <li><a href="#Class loader protection domain not set"> Class loader protection domain not set</a></li> | ||
| 50 : | <li><a href="#PluginModel object casting"> PluginModel object casting</a></li> | ||
| 51 : | <li><a href="#ILibrary implementation incomplete"> ILibrary implementation incomplete</a></li> | ||
| 52 : | <li><a href="#Invalid assumptions regarding form of URLs"> Invalid assumptions regarding form of URLs</a></li> | ||
| 53 : | <li><a href="#BootLoader methods moved/deleted"> BootLoader methods moved/deleted</a></li> | ||
| 54 : | <li><a href="#Plug-in export does not include the plug-in's JARs automatically"> Plug-in export does not include the | ||
| 55 : | plug-in's JARs automatically</a></li> | ||
| 56 : | <li><a href="#Re-exporting runtime API"> Re-exporting runtime API</a></li> | ||
| 57 : | <li><a href="#Plug-in parsing methods on Platform"> Plug-in parsing methods on Platform</a></li> | ||
| 58 : | <li><a href="#Plug-in libraries supplied by fragments"> Plug-in libraries supplied by fragments</a></li> | ||
| 59 : | <li><a href="#Changes to build scripts"> Changes to build scripts</a></li> | ||
| 60 : | <li><a href="#Changes to PDE build Ant task"> Changes to PDE build Ant task</a></li> | ||
| 61 : | <li><a href="#Changes to eclipse.buildScript Ant task">Changes to | ||
| 62 : | eclipse.build Ant task</a></li> | ||
| 63 : | <li><a href="#Changes to eclipse.fetch Ant task">Changes to eclipse.fetch Ant | ||
| 64 : | task</a></li> | ||
| 65 : | <li><a href="#Replacement of install.ini">Replacement of install.ini</a></li> | ||
| 66 : | </ol> | ||
| 67 : | <hr> | ||
| 68 : | <h2><a name="Plug-in manifest version"></a>1. Plug-in manifest version</h2> | ||
| 69 : | <p>The header of the manifest files for plug-ins (and plug-in fragments) has | ||
| 70 : | changed to include a new line which identifies the appropriate plug-in manifest | ||
| 71 : | version. Prior to 3.0, plug-ins did not carry one of these <?eclipse ...?> | ||
| 72 : | lines; after 3.0, they must always have one. This change is to allow the Eclipse | ||
| 73 : | runtime to reliably recognize pre-3.0 plug-ins that have not been ported to 3.0, | ||
| 74 : | so that it can automatically provide greater binary compatibility for such | ||
| 75 : | plug-ins. This is the general form of the plugin.xml file (fragment.xml is | ||
| 76 : | similar):</p> | ||
| 77 : | <p><code><?xml version="1.0" encoding="UTF-8"?><br> | ||
| 78 : | <u><?eclipse version="3.0"?><br> | ||
| 79 : | </u><plugin ...><br> | ||
| 80 : | ...<br> | ||
| 81 : | mcq | 1.9 | </plugin></code></p> |
| 82 : | johna | 1.1 | <p>Plug-in manifests created by PDE 3.0 automatically have this form. <strong>It |
| 83 : | is strongly recommended that you use the PDE plug-in migration tool.</strong> It | ||
| 84 : | automatically inserts the indicated line into the | ||
| 85 : | manifest | ||
| 86 : | of 2.1 plug-ins and plug-in | ||
| 87 : | fragments and addresses many of the other changes described here.</p> | ||
| 88 : | <p>If you do add this directive to a plugin.xml (manually or using PDE), the | ||
| 89 : | file must also be updated to explicitly list the plug-ins on which it depends. | ||
| 90 : | For example, prior to Eclipse 3.0 dependencies on org.eclipse.core.runtime and | ||
| 91 : | org.eclipse.core.boot were implicit. With 3.0, org.eclipse.core.boot is no | ||
| 92 : | longer needed and developers must choose org.eclipse.core.runtime or | ||
| 93 : | org.eclipse.core.runtime.compatibility (or neither) as appropriate.</p> | ||
| 94 : | <p>Note: This is one of the incompatibilities that does <b>not</b> impact how | ||
| 95 : | 2.1 binary plug-ins are run by Eclipse 3.0.</p> | ||
| 96 : | <h2><a name="Restructuring of Platform UI plug-ins"></a>2. Restructuring of Platform UI plug-ins</h2> | ||
| 97 : | <p>The org.eclipse.ui plug-in, which used to be the main Platform UI plug-in, | ||
| 98 : | now provides just the API and extension points for the generic (i.e., | ||
| 99 : | non-IDE-specific) workbench. Optional and IDE-specific API and extension points | ||
| 100 : | have moved to other plug-ins.</p> | ||
| 101 : | <p>The impact of this change is two-fold: (1) the moved org.eclipse.ui extension | ||
| 102 : | points have new extension point ids; and (2) the list of required plug-ins has | ||
| 103 : | changed.</p> | ||
| 104 : | <p>The org.eclipse.ui extension points in the following table have moved to | ||
| 105 : | different plug-ins, causing their extension point ids to change. If an existing | ||
| 106 : | plug-in contributes an extension to the moved extension points, then the | ||
| 107 : | reference in the "point" attribute of the <extension> element in | ||
| 108 : | the plug-in manifest file must be changed to refer to the corresponding new ones | ||
| 109 : | extension point id. The PDE plug-in migration tool makes these fix-ups.</p> | ||
| 110 : | <p>Note: This is one of the incompatibilities that does <b>not</b> impact how | ||
| 111 : | 2.1 binary plug-ins are run by Eclipse 3.0. The Eclipse 3.0 runtime automatically detects pre-3.0 plug-ins (by the | ||
| 112 : | absence of the aforementioned <?eclipse version="3.0"?> line in the plug-in manifest) | ||
| 113 : | and automatically compensates for these extension point and plug-in dependency | ||
| 114 : | changes.</p> | ||
| 115 : | <table border="1" width="80%"> | ||
| 116 : | <tr> | ||
| 117 : | <td width="50%"> | ||
| 118 : | mcq | 1.9 | <p align="center"><b>Old extension point id</b></p></td> |
| 119 : | johna | 1.1 | <td width="50%"> |
| 120 : | mcq | 1.9 | <p align="center"><b>New extension point id</b></p></td> |
| 121 : | johna | 1.1 | </tr> |
| 122 : | <tr> | ||
| 123 : | <td width="50%">org.eclipse.ui.markerHelp</td> | ||
| 124 : | <td width="50%">org.eclipse.ui.<i>ide</i>.markerHelp</td> | ||
| 125 : | </tr> | ||
| 126 : | <tr> | ||
| 127 : | <td width="50%">org.eclipse.ui.markerImageProviders</td> | ||
| 128 : | <td width="50%">org.eclipse.ui.<i>ide</i>.markerImageProviders</td> | ||
| 129 : | </tr> | ||
| 130 : | <tr> | ||
| 131 : | <td width="50%">org.eclipse.ui.markerResolution</td> | ||
| 132 : | <td width="50%">org.eclipse.ui.<i>ide</i>.markerResolution</td> | ||
| 133 : | </tr> | ||
| 134 : | <tr> | ||
| 135 : | <td width="50%">org.eclipse.ui.projectNatureImages</td> | ||
| 136 : | <td width="50%">org.eclipse.ui.<i>ide</i>.projectNatureImages</td> | ||
| 137 : | </tr> | ||
| 138 : | <tr> | ||
| 139 : | <td width="50%">org.eclipse.ui.resourceFilters</td> | ||
| 140 : | <td width="50%">org.eclipse.ui.<i>ide</i>.resourceFilters</td> | ||
| 141 : | </tr> | ||
| 142 : | <tr> | ||
| 143 : | <td width="50%">org.eclipse.ui.markerUpdaters</td> | ||
| 144 : | <td width="50%">org.eclipse.ui.<i>editors</i>.markerUpdaters</td> | ||
| 145 : | </tr> | ||
| 146 : | <tr> | ||
| 147 : | <td width="50%">org.eclipse.ui.documentProviders</td> | ||
| 148 : | <td width="50%">org.eclipse.ui.<i>editors</i>.documentProviders</td> | ||
| 149 : | </tr> | ||
| 150 : | <tr> | ||
| 151 : | <td width="50%">org.eclipse.ui.workbench.texteditor.<br> | ||
| 152 : | markerAnnotationSpecification</td> | ||
| 153 : | <td width="50%">org.eclipse.ui.<i>editors</i>.markerAnnotationSpecification</td> | ||
| 154 : | </tr> | ||
| 155 : | </table> | ||
| 156 : | <p>The following table lists the API packages formerly provided by the | ||
| 157 : | org.eclipse.ui plug-in that have been moved to different plug-ins. (The names of | ||
| 158 : | the API packages, classes, fields, and methods did not change.) In some cases, | ||
| 159 : | the API packages are now split across more than one plug-in. Since the API | ||
| 160 : | classes visible to any given plug-in are determined by that plug-in's list of | ||
| 161 : | required plug-ins, these changes may require adjusting | ||
| 162 : | "<requires>" elements in an existing plug-in's manifest to | ||
| 163 : | regain access to API class.</p> | ||
| 164 : | <p>This change only affects plug-ins that depend on the org.eclipse.ui plug-in | ||
| 165 : | (that is, includes <import plugin="org.eclipse.ui"/> in the | ||
| 166 : | <requires> section of the plug-in manifest); all other plug-ins are | ||
| 167 : | unaffected. If it is affected, you <i>may</i> need to change the <import> | ||
| 168 : | element, or add additional <import> elements, so that all the API classes | ||
| 169 : | your plug-in needs are in scope. We strongly recommend that plug-ins only state | ||
| 170 : | dependencies on the plug-ins that they actually use. Including unnecessary | ||
| 171 : | dependencies reduces runtime performance because the Java class loader must | ||
| 172 : | search for classes in all dependents. (The PDE plug-in migration tool will fix | ||
| 173 : | up the dependencies, and help to determine a minimal set.)</p> | ||
| 174 : | <table border="1" width="80%"> | ||
| 175 : | <tr> | ||
| 176 : | <td width="33%"> | ||
| 177 : | mcq | 1.9 | <p align="center"><b>API package</b></p></td> |
| 178 : | johna | 1.1 | <td width="33%"> |
| 179 : | mcq | 1.9 | <p align="center"><b>2.1 plug-in</b></p></td> |
| 180 : | johna | 1.1 | <td width="34%"> |
| 181 : | mcq | 1.9 | <p align="center"><b>Corresponding 3.0 plug-in(s)</b></p></td> |
| 182 : | johna | 1.1 | </tr> |
| 183 : | <tr> | ||
| 184 : | <td width="33%">org.eclipse.jface.text.*</td> | ||
| 185 : | <td width="33%">org.eclipse.ui</td> | ||
| 186 : | <td width="34%">org.eclipse.jface.text</td> | ||
| 187 : | </tr> | ||
| 188 : | <tr> | ||
| 189 : | <td width="33%">org.eclipse.text.*</td> | ||
| 190 : | <td width="33%">org.eclipse.ui</td> | ||
| 191 : | <td width="34%">org.eclipse.jface.text</td> | ||
| 192 : | </tr> | ||
| 193 : | <tr> | ||
| 194 : | <td width="33%">org.eclipse.ui</td> | ||
| 195 : | <td width="33%">org.eclipse.ui</td> | ||
| 196 : | <td width="34%">org.eclipse.ui, org.eclipse.ui.ide</td> | ||
| 197 : | </tr> | ||
| 198 : | <tr> | ||
| 199 : | <td width="33%">org.eclipse.ui.actions</td> | ||
| 200 : | <td width="33%">org.eclipse.ui</td> | ||
| 201 : | <td width="34%">org.eclipse.ui, org.eclipse.ui.ide</td> | ||
| 202 : | </tr> | ||
| 203 : | <tr> | ||
| 204 : | <td width="33%">org.eclipse.ui.dialogs</td> | ||
| 205 : | <td width="33%">org.eclipse.ui</td> | ||
| 206 : | <td width="34%">org.eclipse.ui, org.eclipse.ui.ide</td> | ||
| 207 : | </tr> | ||
| 208 : | <tr> | ||
| 209 : | <td width="33%">org.eclipse.ui.editors.*</td> | ||
| 210 : | <td width="33%">org.eclipse.ui</td> | ||
| 211 : | <td width="34%">org.eclipse.ui.editor</td> | ||
| 212 : | </tr> | ||
| 213 : | <tr> | ||
| 214 : | <td width="33%">org.eclipse.ui.model</td> | ||
| 215 : | <td width="33%">org.eclipse.ui</td> | ||
| 216 : | <td width="34%">org.eclipse.ui, org.eclipse.ui.ide</td> | ||
| 217 : | </tr> | ||
| 218 : | <tr> | ||
| 219 : | <td width="33%">org.eclipse.ui.part</td> | ||
| 220 : | <td width="33%">org.eclipse.ui</td> | ||
| 221 : | <td width="34%">org.eclipse.ui, org.eclipse.ui.ide</td> | ||
| 222 : | </tr> | ||
| 223 : | <tr> | ||
| 224 : | <td width="33%">org.eclipse.ui.texteditor</td> | ||
| 225 : | <td width="33%">org.eclipse.ui</td> | ||
| 226 : | <td width="34%">org.eclipse.ui.workbench.texteditor, org.eclipse.ui.editors</td> | ||
| 227 : | </tr> | ||
| 228 : | <tr> | ||
| 229 : | <td width="33%">org.eclipse.ui.texteditor.*</td> | ||
| 230 : | <td width="33%">org.eclipse.ui</td> | ||
| 231 : | <td width="34%">org.eclipse.ui.workbench.texteditor</td> | ||
| 232 : | </tr> | ||
| 233 : | <tr> | ||
| 234 : | <td width="33%">org.eclipse.ui.views.bookmarkexplorer</td> | ||
| 235 : | <td width="33%">org.eclipse.ui</td> | ||
| 236 : | <td width="34%">org.eclipse.ui.ide</td> | ||
| 237 : | </tr> | ||
| 238 : | <tr> | ||
| 239 : | <td width="33%">org.eclipse.ui.views.contentoutline</td> | ||
| 240 : | <td width="33%">org.eclipse.ui</td> | ||
| 241 : | <td width="34%">org.eclipse.ui.views</td> | ||
| 242 : | </tr> | ||
| 243 : | <tr> | ||
| 244 : | <td width="33%">org.eclipse.ui.views.markers</td> | ||
| 245 : | <td width="33%">org.eclipse.ui</td> | ||
| 246 : | <td width="34%">org.eclipse.ui.ide</td> | ||
| 247 : | </tr> | ||
| 248 : | <tr> | ||
| 249 : | <td width="33%">org.eclipse.ui.views.navigator</td> | ||
| 250 : | <td width="33%">org.eclipse.ui</td> | ||
| 251 : | <td width="34%">org.eclipse.ui.ide</td> | ||
| 252 : | </tr> | ||
| 253 : | <tr> | ||
| 254 : | <td width="33%">org.eclipse.ui.views.properties</td> | ||
| 255 : | <td width="33%">org.eclipse.ui</td> | ||
| 256 : | <td width="34%">org.eclipse.ui.views</td> | ||
| 257 : | </tr> | ||
| 258 : | <tr> | ||
| 259 : | <td width="33%">org.eclipse.ui.views.tasklist</td> | ||
| 260 : | <td width="33%">org.eclipse.ui</td> | ||
| 261 : | <td width="34%">org.eclipse.ui.ide</td> | ||
| 262 : | </tr> | ||
| 263 : | <tr> | ||
| 264 : | <td width="33%">org.eclipse.ui.wizards.datatransfer</td> | ||
| 265 : | <td width="33%">org.eclipse.ui</td> | ||
| 266 : | <td width="34%">org.eclipse.ui.ide</td> | ||
| 267 : | </tr> | ||
| 268 : | <tr> | ||
| 269 : | <td width="33%">org.eclipse.ui.wizards.newresource</td> | ||
| 270 : | <td width="33%">org.eclipse.ui</td> | ||
| 271 : | <td width="34%">org.eclipse.ui.ide</td> | ||
| 272 : | </tr> | ||
| 273 : | </table> | ||
| 274 : | <h2><a name="Restructuring of Platform Core Runtime plug-ins"></a>3. Restructuring of Platform Core Runtime plug-ins</h2> | ||
| 275 : | <p>The Eclipse 3.0 Platform Runtime is based on OSGi, necessitating changes to | ||
| 276 : | the structure of the two Platform Runtime plug-ins, org.eclipse.core.runtime and | ||
| 277 : | org.eclipse.core.boot.</p> | ||
| 278 : | <p>A new org.eclipse.core.runtime.compatibility plug-in provides an | ||
| 279 : | implementation bridge between the old and new APIs, and is the new home for many | ||
| 280 : | of the obsolete APIs formerly found in org.eclipse.core.runtime and | ||
| 281 : | org.eclipse.core.boot. Platform Runtime extension points are unaffected by the | ||
| 282 : | restructuring.</p> | ||
| 283 : | <p>When migrating the existing plug-in to 3.0, the plug-in's | ||
| 284 : | manifest needs to be updated to reflect the new structure of the Eclipse | ||
| 285 : | Platform Runtime plug-ins. The PDE plug-in manifest migration tool will add a | ||
| 286 : | dependency to org.eclipse.core.runtime.compatibility if required.</p> | ||
| 287 : | <p>Note also that if you mark you plug-in as 3.0 (using <?eclipse version="3.0"?>) | ||
| 288 : | and your plug-in defines a Plugin class, you must either explicitly <import | ||
| 289 : | plugin="org.eclipse.core.runtime.compatibility"/> in the plug-in | ||
| 290 : | manifest or ensure that the Plugin class defines the default constructor.</p> | ||
| 291 : | <p>Note: This is one of the incompatibilities that does <b>not</b> impact how | ||
| 292 : | 2.1 binary plug-ins are run by Eclipse 3.0. The Eclipse 3.0 runtime automatically detects pre-3.0 plug-ins | ||
| 293 : | (by the | ||
| 294 : | absence of the <?eclipse version="3.0"?> line in the plug-in manifest) | ||
| 295 : | and automatically compensates for these changes to the Platform Runtime.</p> | ||
| 296 : | <h2><a name="Removal of Xerces plug-in"></a>4. Removal of Xerces plug-in</h2> | ||
| 297 : | <p>The org.eclipse.xerces plug-in is no longer necessary and has been deleted. | ||
| 298 : | XML parsing | ||
| 299 : | support is built in to J2SE 1.4, and the presence of the Xerces plug-in creates class loader conflicts. The | ||
| 300 : | javax.xml.parsers, org.w3c.dom.*, and org.xml.sax.* | ||
| 301 : | API packages formerly provided by the org.eclipse.xerces plug-in are now | ||
| 302 : | available from the J2SE libraries.</p> | ||
| 303 : | <p>If your plug-in requires the org.eclipse.xerces plug-in, you must change your plug-in | ||
| 304 : | manifest to remove this stated dependency. Once that is done, the plug-in's code | ||
| 305 : | should compile and run without further change.</p> | ||
| 306 : | <p>A 2.1 binary plug-ins with a stated dependency on the org.eclipse.xerces | ||
| 307 : | plug-in will be missing a prerequisite when run in a standard Eclipse 3.0 | ||
| 308 : | configuration. The plug-in will not be activated as a consequence.</p> | ||
| 309 : | <h2><a name="Eclipse 3.0 is more concurrent"></a>5. Eclipse 3.0 is more concurrent</h2> | ||
| 310 : | <p>Prior to Eclipse 3.0, Eclipse operated mostly in a single thread. Most API | ||
| 311 : | methods and extension points operated either in the UI thread, or in a thread | ||
| 312 : | spawned from a progress dialog that blocked the UI thread. Most plug-in writers | ||
| 313 : | did not have to worry much about thread safety, apart from ensuring that all UI | ||
| 314 : | activity occurred in the UI thread. In Eclipse 3.0, there is generally much more | ||
| 315 : | concurrency. Many operations now occur in a background thread, where they may | ||
| 316 : | run concurrently with other threads, including the UI thread. All plug-ins whose | ||
| 317 : | code runs in a background thread must now be aware of the thread safety of their | ||
| 318 : | code.</p> | ||
| 319 : | <p>In addition to plug-ins that are explicitly running operations in the | ||
| 320 : | background using the <code>org.eclipse.core.runtime.jobs</code> API, there are | ||
| 321 : | several platform API facilities and extension points that make use of background | ||
| 322 : | threads. Plug-ins that hook into these facilities need to ensure that their code | ||
| 323 : | is thread safe. The following table summarizes the API and extension points that | ||
| 324 : | run some or all of their code in a background thread in Eclipse 3.0:</p> | ||
| 325 : | <table border="1" width="80%"> | ||
| 326 : | <tr> | ||
| 327 : | <td width="50%"> | ||
| 328 : | mcq | 1.9 | <p align="center"><b>Extension point or API class</b></p></td> |
| 329 : | johna | 1.1 | <td width="50%"> |
| 330 : | mcq | 1.9 | <p align="center"><b>Notes</b></p></td> |
| 331 : | johna | 1.1 | </tr> |
| 332 : | <tr> | ||
| 333 : | <td width="50%">org.eclipse.core.runtime.IRegistryChangeListener</td> | ||
| 334 : | <td width="50%">New in Eclipse 3.0, runs in background</td> | ||
| 335 : | </tr> | ||
| 336 : | <tr> | ||
| 337 : | <td width="50%">org.eclipse.core.resources.IResourceChangeListener</td> | ||
| 338 : | <td width="50%"><code>AUTO_BUILD</code> events now in background</td> | ||
| 339 : | </tr> | ||
| 340 : | <tr> | ||
| 341 : | <td width="50%">org.eclipse.core.resources.builders (ext. point)</td> | ||
| 342 : | <td width="50%">Auto-build now in background</td> | ||
| 343 : | </tr> | ||
| 344 : | <tr> | ||
| 345 : | <td width="50%">org.eclipse.core.resources.ISaveParticipant</td> | ||
| 346 : | <td width="50%"><code>SNAPSHOT</code> now in background</td> | ||
| 347 : | </tr> | ||
| 348 : | <tr> | ||
| 349 : | <td width="50%">org.eclipse.ui.workbench.texteditor.quickdiffReferenceProvider | ||
| 350 : | (ext. point)</td> | ||
| 351 : | <td width="50%">New in Eclipse 3.0, runs in background</td> | ||
| 352 : | </tr> | ||
| 353 : | <tr> | ||
| 354 : | <td width="50%">org.eclipse.ui.decorators (ext. point)</td> | ||
| 355 : | <td width="50%">Already in background in Eclipse 2.1</td> | ||
| 356 : | </tr> | ||
| 357 : | <tr> | ||
| 358 : | <td width="50%">org.eclipse.ui.startup (ext. point)</td> | ||
| 359 : | <td width="50%">Already in background in Eclipse 2.1</td> | ||
| 360 : | </tr> | ||
| 361 : | <tr> | ||
| 362 : | <td width="50%">org.eclipse.team.core.org.eclipse.team.core.repository (ext. | ||
| 363 : | point)</td> | ||
| 364 : | <td width="50%">Many operations now in background</td> | ||
| 365 : | </tr> | ||
| 366 : | <tr> | ||
| 367 : | <td width="50%">org.eclipse.team.ui.synchronizeParticipants (ext. point)</td> | ||
| 368 : | <td width="50%">New in Eclipse 3.0, runs in background</td> | ||
| 369 : | </tr> | ||
| 370 : | <tr> | ||
| 371 : | <td width="50%">org.eclipse.debug.core.launchConfigurationTypes (ext. point)</td> | ||
| 372 : | <td width="50%">Now runs in background</td> | ||
| 373 : | </tr> | ||
| 374 : | <tr> | ||
| 375 : | <td width="50%">org.eclipse.jdt.core.IElementChangedListener</td> | ||
| 376 : | <td width="50%"><code>ElementChangedEvent.PRE_AUTO_BUILD</code> now runs in background, <code>POST_RECONCILE</code> | ||
| 377 : | already ran in the background</td> | ||
| 378 : | </tr> | ||
| 379 : | </table> | ||
| 380 : | <p>There are various strategies available for making code thread safe. A naive | ||
| 381 : | solution is to ensure all work occurs in the UI thread, thus ensuring serialized | ||
| 382 : | execution. This is a common approach for UI plug-ins that are not doing | ||
| 383 : | CPU-intensive processing. When doing this, be aware of the deadlock risk | ||
| 384 : | inherent in <code>Display.syncExec</code>. <code>Display.asyncExec</code> is generally | ||
| 385 : | safer as it does not introduce deadlock risk, at the expense of losing precise | ||
| 386 : | control over when the code is executed.</p> | ||
| 387 : | mcq | 1.9 | <p>Other techniques for making thread safe code include:</p> |
| 388 : | johna | 1.1 | <ul> |
| 389 : | <li>Wrapping unsafe code in semaphores or Java monitors. The new concurrency | ||
| 390 : | infrastructure includes one such semaphore object: <code>org.eclipse.core.runtime.jobs.ILock</code>. | ||
| 391 : | The advantage of <code>ILock</code> over generic locks is that they transfer | ||
| 392 : | automatically to the UI thread when doing a <code>syncExec</code>, and there is | ||
| 393 : | deadlock detection support built into their implementation that logs and | ||
| 394 : | then resolves deadlocks.</li> | ||
| 395 : | <li>Message queues. Code can be serialized by forwarding all processing to a | ||
| 396 : | message queue that is processed serially in a single thread. One such | ||
| 397 : | example is the SWT deferred event queue (<code>Display.asyncExec</code>), which | ||
| 398 : | is processed entirely in the UI thread.</li> | ||
| 399 : | <li>Immutable objects. Make data structures immutable, and make new copies on | ||
| 400 : | modification. This is the approach used to make data structures such as <code>java.lang.String</code> | ||
| 401 : | and <code>org.eclipse.core.runtime.IPath</code> thread safe. The advantage of | ||
| 402 : | immutable objects is extremely fast read access, at the cost of extra work | ||
| 403 : | on modification.</li> | ||
| 404 : | </ul> | ||
| 405 : | <h2><a name="Opening editors on IFiles"></a>6. Opening editors on IFiles</h2> | ||
| 406 : | <p>The following methods were deleted from the org.eclipse.ui.IWorkbenchPage interface. | ||
| 407 : | IWorkbenchPage is declared in the generic workbench, but the methods are inherently | ||
| 408 : | resource-specific.</p> | ||
| 409 : | <ul> | ||
| 410 : | <li>public IEditorPart openEditor(IFile input)</li> | ||
| 411 : | <li>public IEditorPart openEditor(IFile input, String editorID)</li> | ||
| 412 : | <li>public IEditorPart openEditor(IFile input, String editorID, boolean | ||
| 413 : | activate)</li> | ||
| 414 : | <li>public IEditorPart openEditor(IMarker marker)</li> | ||
| 415 : | <li>public IEditorPart openEditor(IMarker marker, boolean activate)</li> | ||
| 416 : | <li>public void openSystemEditor(IFile input)</li> | ||
| 417 : | </ul> | ||
| 418 : | <p>Clients of these IWorkbenchPage.openEditor methods should instead call the | ||
| 419 : | corresponding public static | ||
| 420 : | methods declared in the class org.eclipse.ui.ide.IDE (in the org.eclipse.ui.ide plug-in).</p> | ||
| 421 : | <p>Clients of these IWorkbenchPage.openSystemEditor(IFile) method should convert the IFile to an | ||
| 422 : | IEditorInput using new FileEditorInput(IFile) and then call the | ||
| 423 : | openEditor(IEditorInput,String) method. In other words, rewrite | ||
| 424 : | page.openSystemEditor(file) as page.openEditor(new FileEditorInput(file), | ||
| 425 : | IEditorRegistry.SYSTEM_EXTERNAL_EDITOR_ID). Note: clients using editor id | ||
| 426 : | IEditorRegistry.SYSTEM_EXTERNAL_EDITOR_ID must pass an editor input | ||
| 427 : | which implements org.eclipse.ui.IPathEditorInput (which FileEditorInput | ||
| 428 : | does).</p> | ||
| 429 : | Note: This is one of the incompatibilities that does <b>not</b> impact how | ||
| 430 : | 2.1 binary plug-ins are run by Eclipse 3.0. Eclipse 3.0 includes a binary runtime compatibility mechanism that | ||
| 431 : | ensures existing 2.1 plug-in binaries using any of the deleted openEditor | ||
| 432 : | and openSystemEditor methods continue to work as in 2.1 in spite of this API change. | ||
| 433 : | (The deleted methods are effectively "added back" by | ||
| 434 : | the org.eclipse.ui.workbench.compatibility fragment.) | ||
| 435 : | <h2><a name="Editor goto marker"></a>7. Editor goto marker</h2> | ||
| 436 : | <p>The following method was deleted from the org.eclipse.ui.IEditorPart | ||
| 437 : | interface. IEditorPart is declared in the generic workbench, but the method is inherently | ||
| 438 : | resource-specific.</p> | ||
| 439 : | <ul> | ||
| 440 : | <li>public void gotoMarker(IMarker marker)</li> | ||
| 441 : | </ul> | ||
| 442 : | The corresponding methods were also deleted from the classes in the | ||
| 443 : | org.eclipse.ui.part package that implement IEditorPart, namely EditorPart, | ||
| 444 : | MultiEditor, MultiPageEditorPart, and MultiPageEditor. | ||
| 445 : | <p>Clients that call this method should instead test if the editor part | ||
| 446 : | implements or adapts to org.eclipse.ui.ide.IGotoMarker (in the org.eclipse.ui.ide | ||
| 447 : | plug-in) and if so, call gotoMarker(IMarker). The IDE class has a convenience | ||
| 448 : | method for doing so: IDE.gotoMarker(editor, marker);</p> | ||
| 449 : | Clients that implement an editor that can position itself based on IMarker | ||
| 450 : | information should implement or adapt to org.eclipse.ui.ide.IGotoMarker. | ||
| 451 : | <p>Since IGotoMarker's only method is gotoMarker(IMarker) and has the same | ||
| 452 : | signature and specification as the old IEditorPart.gotoMarker(IMarker), existing | ||
| 453 : | editor implementations can adapt to this change simply by including IGotoMarker | ||
| 454 : | mcq | 1.9 | in the implements clause of the class definition.</p> |
| 455 : | johna | 1.1 | <p>A 2.1 binary plug-ins with code that calls this method will get an class |
| 456 : | linking error exception when run in a standard Eclipse 3.0 | ||
| 457 : | configuration.</p> | ||
| 458 : | <h2><a name="Editor launcher"></a>8. Editor launcher</h2> | ||
| 459 : | <p>The editor launcher interface org.eclipse.ui.IEditorLauncher is implemented by plug-ins that contribute | ||
| 460 : | external editors. The following method was removed from this interface. IEditorLauncher | ||
| 461 : | is declared in the generic workbench, but the method is inherently | ||
| 462 : | resource-specific.</p> | ||
| 463 : | <ul> | ||
| 464 : | <li>public void open(IFile file)</li> | ||
| 465 : | </ul> | ||
| 466 : | <p>It was replaced by</p> | ||
| 467 : | <ul> | ||
| 468 : | <li>public void open(IPath file)</li> | ||
| 469 : | </ul> | ||
| 470 : | Clients that call IEditorLauncher.open(file) should instead call | ||
| 471 : | IEditorLauncher.open(file.getLocation()). Clients that implement this interface should | ||
| 472 : | replace (or augment) their implementation | ||
| 473 : | of open(IFile) by one for open(IPath). | ||
| 474 : | <p>A 2.1 binary plug-ins with code that calls this method will get an class | ||
| 475 : | linking error exception when run in a standard Eclipse 3.0 | ||
| 476 : | configuration.</p> | ||
| 477 : | <h2><a name="Editor registry"></a>9. Editor registry</h2> | ||
| 478 : | <p>The following methods were removed from the org.eclipse.ui.IEditorRegistry interface. | ||
| 479 : | IEditorRegistry is declared in the generic workbench, but the methods are inherently | ||
| 480 : | resource-specific.</p> | ||
| 481 : | <ul> | ||
| 482 : | <li>public IEditorDescriptor getDefaultEditor(IFile file)</li> | ||
| 483 : | <li>public void setDefaultEditor(IFile file, String editorId)</li> | ||
| 484 : | <li>public IEditorDescriptor[] getEditors(IFile file)</li> | ||
| 485 : | <li>public ImageDescriptor getImageDescriptor(IFile file)</li> | ||
| 486 : | </ul> | ||
| 487 : | Clients that call getEditors(file) or getImageDescriptor(file) should call the | ||
| 488 : | "String" equivalent methods: | ||
| 489 : | <ul> | ||
| 490 : | <li>Rewrite registry.getEditors(file) to be | ||
| 491 : | registry.getEditors(file.getName())</li> | ||
| 492 : | <li>Rewrite registry.getImageDescriptor(file) to be registry.getImageDescriptor(file.getName())</li> | ||
| 493 : | </ul> | ||
| 494 : | Clients that call setDefaultEditor(IFile file, String editorId) and | ||
| 495 : | getDefaultEditor(IFile file) should should instead call the corresponding public static | ||
| 496 : | methods declared in the class org.eclipse.ui.ide.IDE (in the org.eclipse.ui.ide | ||
| 497 : | plug-in): | ||
| 498 : | <ul> | ||
| 499 : | <li>Rewrite registry.getDefaultEditor(file) to be | ||
| 500 : | IDE.getDefaultEditor(file)</li> | ||
| 501 : | <li>Rewrite registry.setDefaultEditor(file, id) to be IDE.setDefaultEditor(file, | ||
| 502 : | id)</li> | ||
| 503 : | </ul> | ||
| 504 : | Also, the API contract for the method IEditorRegistrygetDefaultEditor() was | ||
| 505 : | changed. This method, which is also now deprecated, and will | ||
| 506 : | always return the System External Editor editor descriptor. This change impacts clients that assumed the default editor returned | ||
| 507 : | would be a text editor. | ||
| 508 : | <p>There are new constants that represent the system external editor and system | ||
| 509 : | in-place editor identifiers (SYSTEM_EXTERNAL_EDITOR_ID and | ||
| 510 : | SYSTEM_INPLACE_EDITOR_ID). These two editors require an editor input that | ||
| 511 : | implements or adapts to org.eclipse.ui.IPathEditorInput. Note that the in-place | ||
| 512 : | editor descriptor will not exist in Eclipse configurations that do not support in-place | ||
| 513 : | editing.</p> | ||
| 514 : | <h2><a name="Workbench marker help registry"></a>10. Workbench marker help | ||
| 515 : | registry</h2> | ||
| 516 : | <p>The following method was deleted from the org.eclipse.ui.IWorkbench interface. | ||
| 517 : | IWorkbench is declared in the generic workbench, but the method is inherently | ||
| 518 : | resource-specific.</p> | ||
| 519 : | <ul> | ||
| 520 : | <li>public IMarkerHelpRegistry getMarkerHelpRegistry()</li> | ||
| 521 : | </ul> | ||
| 522 : | Clients of IWorkbench.getMarkerHelpRegistry() should instead call the public static | ||
| 523 : | method org.eclipse.ui.ide.IDE.getMarkerHelpRegistry() (in the org.eclipse.ui.ide plug-in). | ||
| 524 : | <p>A 2.1 binary plug-ins with code that calls this method will get an exception when run in a standard Eclipse 3.0 | ||
| 525 : | configuration.</p> | ||
| 526 : | <h2><a name="Text editor document providers"></a>11. Text editor document providers</h2> | ||
| 527 : | <p>In order to make org.eclipse.ui.texteditor.AbstractTextEditor independent of | ||
| 528 : | IFile, org.eclipse.ui.texteditor.AbstractDocumentProvider introduces the concept | ||
| 529 : | of a document provider operation (DocumentProviderOperation) and a document | ||
| 530 : | provider operation runner (IRunnableContext). When requested to perform | ||
| 531 : | reset, save, or synchronize, AbstractDocumentProvider creates document | ||
| 532 : | provider operations and uses the operation runner to execute them. The | ||
| 533 : | runnable context can be provided by subclasses via the getOperationRunner | ||
| 534 : | method. Here is a summary of the changes that clients must adapt to:</p> | ||
| 535 : | <ul> | ||
| 536 : | <li>Added protected abstract IRunnableContext getOperationRunner(); | ||
| 537 : | non-abstract subclasses must implement this method in order to provide their | ||
| 538 : | own operation runner.</li> | ||
| 539 : | <li>The method resetDocument has been changed to final in order to allow the | ||
| 540 : | document provider to wrap the function with a document provider operation. | ||
| 541 : | The document provider operation calls the newly introduced doResetDocument | ||
| 542 : | method. AbstractDocumentProvider.doResetDocument contains the code that | ||
| 543 : | originally resided inside AbstractDocumentProvider.resetDocument. Subclasses | ||
| 544 : | must change their implementation of resetDocument to doResetDocument and any | ||
| 545 : | contained call of super.resetDocument to super.doResetDocument.</li> | ||
| 546 : | <li>The method saveDocument has been changed to final in order to allow the | ||
| 547 : | document provider to wrap the function with a document provider operation. | ||
| 548 : | The document provider operation calls the newly introduced doSaveDocument | ||
| 549 : | method. AbstractDocumentProvider.doSaveDocument contains the code that | ||
| 550 : | originally resided inside AbstractDocumentProvider.saveDocument. Subclasses | ||
| 551 : | must change their implementation of saveDocument to doSaveDocument and any | ||
| 552 : | contained call of super.saveDocument to super.doSaveDocument.</li> | ||
| 553 : | <li>The method synchronize has been changed to final in order to allow the | ||
| 554 : | document provider to wrap the function with a document provider operation. | ||
| 555 : | The document provider operation calls the newly introduced doSynchronize | ||
| 556 : | method. AbstractDocumentProvider.doSynchronize contains the code that | ||
| 557 : | originally resided inside AbstractDocumentProvider.synchronize. Subclasses | ||
| 558 : | must change their implementation of synchronize to doSynchronize and any | ||
| 559 : | contained call of super.synchronized to super.doSynchronize.</li> | ||
| 560 : | </ul> | ||
| 561 : | <p>The AbstractDocumentProvider subclass org.eclipse.ui.editors.text.StorageDocumentProvider | ||
| 562 : | implements the getOperationRunner method to always returns null. This means that | ||
| 563 : | subclasses of StorageDocumentProvider should | ||
| 564 : | not be affected by this change.</p> | ||
| 565 : | <p>The StorageDocumentProvider subclass org.eclipse.ui.editors.text.FileDocumentProvider | ||
| 566 : | implements the getOperationRunner method that returns an IRunnableContext for executing the given DocumentProviderOperations | ||
| 567 : | inside a WorkspaceModifyOperation. Other changes to FileDocumentProvider | ||
| 568 : | are:</p> | ||
| 569 : | <ul> | ||
| 570 : | <li>resetDocument(Object) has been replaced by | ||
| 571 : | doResetDocument(Object,IProgressMonitor).</li> | ||
| 572 : | <li> synchronize(Object) has been replaced by | ||
| 573 : | doSynchronize(Object,IProgressMonitor).</li> | ||
| 574 : | </ul> | ||
| 575 : | <h2><a name="Text editors"></a>12. Text editors</h2> | ||
| 576 : | <p>Changes to org.eclipse.ui.texteditor.AbstractTextEditor:</p> | ||
| 577 : | <ul> | ||
| 578 : | <li>The method IEditorPart.gotoMarker(IMarker marker) was removed from the | ||
| 579 : | IEditorPart interface because it was resource-specific. The default | ||
| 580 : | implementation provided by AbstractTextEditor has been removed from | ||
| 581 : | AbstractTextEditor and has been moved to AbstractDecoratedTextEditor. Direct | ||
| 582 : | subclasses of AbstractTextEditor or StatusTextEditor that want to provide | ||
| 583 : | that functionality should follow the migration instructions for | ||
| 584 : | IEditorPart [ref Editor goto marker].</li> | ||
| 585 : | <li>AbstractTextEditor no longer differentiates between implicit and | ||
| 586 : | explicit document providers as the concrete implementation was resource | ||
| 587 : | specific. This functionality has been moved to AbstractDecoratedTextEditor. Direct | ||
| 588 : | subclasses of AbstractTextEditor or StatusTextEditor must perform the | ||
| 589 : | following steps: | ||
| 590 : | <ul> | ||
| 591 : | <li>Override getDocumentProvider.</li> | ||
| 592 : | <li>Override the newly introduced hook method for disposing the document | ||
| 593 : | provider (disposeDocumentProvider)</li> | ||
| 594 : | <li>Override the newly introduced hook method | ||
| 595 : | setDocumentProvider(IEditorInput) that is called while updating the | ||
| 596 : | document provider for the new editor input. I.e., that is the method in | ||
| 597 : | which you can configure the appropriate implicit document provider for | ||
| 598 : | the given editor input.</li> | ||
| 599 : | </ul> | ||
| 600 : | </li> | ||
| 601 : | <li>All internal occurrences of WorkspaceModifyOperation have been removed. The | ||
| 602 : | editor now calls the document provider methods directly (see described | ||
| 603 : | changes for document providers); | ||
| 604 : | <ul> | ||
| 605 : | <li>Removed createSaveOperation, changed performSaveOperation to | ||
| 606 : | performSave. Subclasses of AbstractTextEditor overriding | ||
| 607 : | createSaveOperation or performSaveOperation must now override | ||
| 608 : | performSave.</li> | ||
| 609 : | <li>Removed createdRevertOperation, changed peformRevertOperation to | ||
| 610 : | performRevert. Sunclasses overriding createRevertOperation or | ||
| 611 : | performRevertOperation must now override performRevert.</li> | ||
| 612 : | <li>The implementation of the method handleEditorInputChanged has been | ||
| 613 : | changed to not use WorkbenchModifyingOperation. Subclasses overriding | ||
| 614 : | handleEditorInputChange must adapt accordingly. Please use the changes | ||
| 615 : | applied to AbstractTextEditor.handleEditorInputChange as the blueprint.</li> | ||
| 616 : | </ul> | ||
| 617 : | </li> | ||
| 618 : | <li>AbstractTextEditor.createActions no longer registers any actions under | ||
| 619 : | ITextEditorActionConstants.ADD_TASK and ITextEditorActionConstant.BOOKMARK | ||
| 620 : | as those actions are IDE-specific. The registration of these actions has | ||
| 621 : | been moved to AbstractDecoratedTextEditor. Direct subclasses of AbstractTextEditor or | ||
| 622 : | StatusTextEditor should override the createActions method and add the | ||
| 623 : | following lines (accordingly adapted to their circumstances):</li> | ||
| 624 : | <li> | ||
| 625 : | <pre> ResourceAction action= new AddMarkerAction(TextEditorMessages.getResourceBundle(), "Editor.AddBookmark.", this, IMarker.BOOKMARK, true); //$NON-NLS-1$ | ||
| 626 : | action.setHelpContextId(ITextEditorHelpContextIds.BOOKMARK_ACTION); | ||
| 627 : | action.setActionDefinitionId(ITextEditorActionDefinitionIds.ADD_BOOKMARK); | ||
| 628 : | setAction(IDEActionFactory.BOOKMARK.getId(), action); </pre> | ||
| 629 : | <pre> action= new AddTaskAction(TextEditorMessages.getResourceBundle(), "Editor.AddTask.", this); //$NON-NLS-1$ | ||
| 630 : | action.setHelpContextId(ITextEditorHelpContextIds.ADD_TASK_ACTION); | ||
| 631 : | action.setActionDefinitionId(ITextEditorActionDefinitionIds.ADD_TASK); | ||
| 632 : | setAction(IDEActionFactory.ADD_TASK.getId(), action);</pre> | ||
| 633 : | </li> | ||
| 634 : | </ul> | ||
| 635 : | <p>The AbstractTextEditor subclass org.eclipse.ui.texteditor.StatusTextEditor provides the predicate method isErrorStatus(IStatus). | ||
| 636 : | Subclasses may override in order to decide whether a given status must | ||
| 637 : | considered an error or not.</p> | ||
| 638 : | <p>Changes to org.eclipse.ui.editors.text.AbstractDecoratedTextEditor:</p> | ||
| 639 : | <ul> | ||
| 640 : | <li>The IEditorPart method gotoMarker(IMarker marker) has been deprecated to | ||
| 641 : | allow a future change of its visibility. Clients of this method must follow | ||
| 642 : | the migration instructions in the deprecation message.</li> | ||
| 643 : | mcq | 1.9 | <li>AbstractDecoratedTextEditor returns an adapter for IGotoMarker.</li> |
| 644 : | johna | 1.1 | <li>AbstractDecoratedTextEditor implements the concept of implicit/explicit document |
| 645 : | mcq | 1.9 | providers previously provided by AbstractTextEditor, as discussed above.</li> |
| 646 : | johna | 1.1 | </ul> |
| 647 : | <h2><a name="Headless annotation support"></a>13. Headless annotation support</h2> | ||
| 648 : | <p>As part of the introduction of headless annotation support, the following changes to Annotation were made:</p> | ||
| 649 : | <ul> | ||
| 650 : | <li>Removed static Annotation.drawImage methods, use org.eclipse.jface.text.source.ImageUtilities instead.</li> | ||
| 651 : | <li>Removed setLayer, getLayer, and paint methods from Annotation, annotations which want to draw | ||
| 652 : | themselves should implement IAnnotationPresentation.</li> | ||
| 653 : | <li>MarkerAnnotation now directly implements the methods removed from Annotation (setLayer, getLayer, paint).</li> | ||
| 654 : | <li>The following classes have been moved from the plug-in org.eclipse.jface.text to the plug-in | ||
| 655 : | org.eclipse.text, the package names remain the same and org.eclipse.jface.text rexports the classes from org.eclipse.jface.text, | ||
| 656 : | such that this change is transparent to clients:</li> | ||
| 657 : | </ul> | ||
| 658 : | <pre> org.eclipse.jface.text.source.Annotation | ||
| 659 : | org.eclipse.jface.text.source.AnnotationModel | ||
| 660 : | org.eclipse.jface.text.source.AnnotationModelEvent | ||
| 661 : | org.eclipse.jface.text.source.IAnnotationModel | ||
| 662 : | org.eclipse.jface.text.source.IAnnotationModelListener | ||
| 663 : | org.eclipse.jface.text.source.IAnnotationModelListenerExtension</pre> | ||
| 664 : | <h2> <a name="Console view"></a>14. Console view</h2> | ||
| 665 : | <p>Eclipse 3.0 has new generic console support. The generic console is available via the Window | ||
| 666 : | > Show View > Basic > Console, | ||
| 667 : | and is used by the Eclipse debug and Ant integration.</p> | ||
| 668 : | <p>The view id for the console has changed from org.eclipse.debug.ui.ConsoleView | ||
| 669 : | to org.eclipse.ui.console.ConsoleView. 2.1 plug-ins that programmatically open | ||
| 670 : | the console will be unsuccessful because that the old view no longer exists.</p> | ||
| 671 : | <h2><a name="Java breakpoint listeners"></a>15. Java breakpoint listeners</h2> | ||
| 672 : | <p>In 3.0, the return types for the methods org.eclipse.jdt.debug.core.IJavaBreakpointListener.breakpointHit(IJavaBreakpoint, IJavaThread) and | ||
| 673 : | installingBreakpoing(IJavaTarget, IJavaBreakpoint, IJavaType) changed from | ||
| 674 : | boolean to int to allow listeners to vote "don't care". In releases | ||
| 675 : | prior to 3.0, listeners could only vote "suspend" or "don't | ||
| 676 : | suspend" when a breakpoint was hit, and "install" or "don't | ||
| 677 : | install" when a breakpoint was about to be installed. In 3.0, listeners can | ||
| 678 : | also vote "don't care" for either of these notifications. This allows | ||
| 679 : | clients to only make a decisive vote in situations that they care about. For | ||
| 680 : | "breakpoint hit" notifications, the breakpoint will suspend if any | ||
| 681 : | listeners vote "suspend", or all listeners vote "don't | ||
| 682 : | care"; and it will not suspend if at least one listener votes "don't | ||
| 683 : | suspend" and no listeners vote "suspend". Similarly, for | ||
| 684 : | "breakpoint installing" notifications, the breakpoint will be | ||
| 685 : | installed if any listeners vote to install, or all listeners vote "don't | ||
| 686 : | care"; and it will not be installed if at least one listener votes | ||
| 687 : | "don't install" and no listeners vote "install". In general, | ||
| 688 : | implementors should return DONT_CARE unless they have a strong opinion one way | ||
| 689 : | or the other. It is important to keep in mind, for example, that voting | ||
| 690 : | "suspend" will override any other listener's vote of "don't | ||
| 691 : | suspend".</p> | ||
| 692 : | <p>The IJavaBreakpointListener interface is implemented by clients that create | ||
| 693 : | or react to breakpoints in Java code. There are likely few clients beyond JDT | ||
| 694 : | itself, save the one that reported the problem (<a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=37760">bug | ||
| 695 : | 37760</a>) that this change remedies. This is a breaking change for existing | ||
| 696 : | code that implements the IJavaBreakpointListener interface. This code needs to | ||
| 697 : | be modified to return an appropriate int value before it will compile or run in | ||
| 698 : | 3.0.</p> | ||
| 699 : | <h2><a name="Clipboard access in UI thread"></a>16. Clipboard access in UI thread</h2> | ||
| 700 : | <p>Prior to 3.0, the methods on the SWT class org.eclipse.swt.dnd.Clipboard were tacitly permitted | ||
| 701 : | to run in threads other than the UI thread. This oversight resulted in failures | ||
| 702 : | on GTK where the operating system requires that all clipboard interactions be | ||
| 703 : | performed in the UI thread. The oversight was not revealed earlier because many | ||
| 704 : | applications are single-threaded and receive most of their testing on Windows. | ||
| 705 : | In order for the Clipboard API to be sustainable and cross-platform, in 3.0 the | ||
| 706 : | specification and implementation of all Clipboard API methods have been changed | ||
| 707 : | to throw an SWT Exception (ERROR_THREAD_INVALID_ACCESS) if invoked from a non-UI | ||
| 708 : | thread. Clipboard services are commonly provided automatically by Eclipse | ||
| 709 : | components such as the text editor, which insulate many clients from this | ||
| 710 : | breaking change. Existing code that does make direct use of Clipboard should | ||
| 711 : | ensure that the API methods are called on the correct thread, using | ||
| 712 : | Display.asyncExec or syncExec when appropriate to shift accesses into the UI thread.</p> | ||
| 713 : | <h2><a name="Key down events"></a>17. Key down events</h2> | ||
| 714 : | <p>In 3.0, SWT reports key down events before the work is done in the OS. This | ||
| 715 : | is much earlier than it was prior to 3.0. This change was made to support key | ||
| 716 : | bindings in Eclipse which necessitates intercepting key events before any widget | ||
| 717 : | has a chance to process the character. Consequences of this change are visible | ||
| 718 : | to code that handles low-level org.eclipse.swt.SWT.KeyDown events directly. For example, it | ||
| 719 : | means that when a listener on a Text widget receives a key down event, the | ||
| 720 : | widget's content (getText()) will not yet include the key just typed (it would | ||
| 721 : | have prior to 3.0). The recommended way to get the full text from the widget | ||
| 722 : | including the current key is to handle the higher-level SWT.Modify or SWT.Verify | ||
| 723 : | events rather than the low-level SWT.KeyDown event; code that already does it this way | ||
| 724 : | is unaffected by this change.</p> | ||
| 725 : | <h2><a name="Tab traversal of custom controls"></a>18. Tab traversal of custom controls</h2> | ||
| 726 : | <p>Prior to 3.0, when the focus was in the SWT class org.eclipse.swt.widgets.Canvas or one of its subclasses | ||
| 727 : | (including custom widgets), typing Ctrl+Tab, Shift+Tab, Ctrl+PgUp, or Ctrl+PgDn | ||
| 728 : | would automatically trigger traversal to the next/previous widget without | ||
| 729 : | reporting a key event. This behavior was unspecified, and runs counter to the | ||
| 730 : | rule that Canvases see every key typed in them. The proper way to handle | ||
| 731 : | traversal is by registering a traverse listener. In order to properly support | ||
| 732 : | Eclipse key bindings in 3.0, the default behavior was changed so that Canvas now | ||
| 733 : | sees Ctrl+Tab, Shift+Tab, Ctrl+PgUp, and Ctrl+PgDn key events instead of | ||
| 734 : | traversing. If you use a raw Canvas or define a subclass of Canvas, ensure that | ||
| 735 : | that you register a traverse listener.</p> | ||
| 736 : | <h2><a name="Selection event order in SWT table and tree widgets"></a>19. Selection event order in SWT table and tree widgets</h2> | ||
| 737 : | <p>Mouse selections of items in the SWT classes org.eclipse.swt.widgets.Table and Tree generate the event | ||
| 738 : | sequence MouseDown-Selection-MouseUp uniformly in all operating environments. | ||
| 739 : | Similarly, keyboard selections generate the event sequence | ||
| 740 : | KeyDown-Selection-KeyUp uniformly in all operating environments. Prior to 3.0, | ||
| 741 : | the event order was not uniform, with Motif and Photon at variance with the rest | ||
| 742 : | by always reporting the Selection event first; i.e., Selection-MouseDown-MouseUp | ||
| 743 : | or Selection-KeyDown-KeyUp. For 3.0, the event order on Motif and Photon has | ||
| 744 : | been changed to match the others. Existing code that was functioning correctly | ||
| 745 : | on {Windows, GTK} and on {Motif, Photon} is unlikely to be affected. But it is | ||
| 746 : | wise to check your code to ensure that it does not rely on an invalid event | ||
| 747 : | order.</p> | ||
| 748 : | <h2><a name="New severity level in status objects"></a>20. New severity level in status objects</h2> | ||
| 749 : | <p><code>org.eclipse.core.runtime.IStatus</code> has a new severity constant, <code>IStatus.CANCEL</code>, | ||
| 750 : | that can be used to indicate cancelation. Callers of <code>IStatus.getSeverity()</code> | ||
| 751 : | that rely on the set of possible severities being limited to <code>IStatus.OK</code>, | ||
| 752 : | <code>INFO</code>, <code>WARNING</code>, and <code>ERROR</code> are affected by this addition. Callers of | ||
| 753 : | <code>getSeverity</code> should update | ||
| 754 : | their code to include the new severity.</p> | ||
| 755 : | <h2><a name="Build-related resource change notifications"></a>21. Build-related resource change notifications</h2> | ||
| 756 : | <p>In Eclipse 3.0, workspace auto-builds now occur in a background thread. This | ||
| 757 : | required an API contract change to <code>org.eclipse.core.resources.IResourceChangeEvent</code>. The contract | ||
| 758 : | of <code>IResourceChangeEvent</code> previously guaranteed the following ordering of | ||
| 759 : | mcq | 1.9 | events for all workspace changes:</p> |
| 760 : | johna | 1.1 | <ol> |
| 761 : | <li><code>PRE_DELETE</code> or <code>PRE_CLOSE</code> event notification if applicable</li> | ||
| 762 : | <li>Perform the operation</li> | ||
| 763 : | <li><code>PRE_AUTO_BUILD</code> event notification</li> | ||
| 764 : | <li>If auto-build is on, perform incremental workspace build</li> | ||
| 765 : | <li><code>POST_AUTO_BUILD</code> event notification</li> | ||
| 766 : | <li><code>POST_CHANGE</code> event notification</li> | ||
| 767 : | </ol> | ||
| 768 : | <p>With auto-build now running in the background, there is no longer any | ||
| 769 : | guarantee about the temporal relationship between the <code>AUTO_BUILD</code> events | ||
| 770 : | and the <code>POST_CHANGE</code> event. In Eclipse 3.0, steps 3-5 in the above | ||
| 771 : | mcq | 1.9 | structure are removed from the operation. The resulting picture looks like this:</p> |
| 772 : | johna | 1.1 | <ol> |
| 773 : | <li><code>PRE_DELETE</code> or <code>PRE_CLOSE</code> event notification if applicable</li> | ||
| 774 : | <li>Perform the operation</li> | ||
| 775 : | <li><code>POST_CHANGE</code> event notification</li> | ||
| 776 : | </ol> | ||
| 777 : | <p>Periodically, the platform will perform a background workspace build | ||
| 778 : | operation. Note that this happens regardless of the whether auto-build is on or | ||
| 779 : | off. The exact timing of when this build occurs will not be specified. The | ||
| 780 : | mcq | 1.9 | structure of the build operation will look like this:</p> |
| 781 : | johna | 1.1 | <ol> |
| 782 : | <li><code>PRE_BUILD</code> event notification (<code>PRE_BUILD</code> is the | ||
| 783 : | new name for <code>PRE_AUTO_BUILD)</code></li> | ||
| 784 : | <li>If auto-build is on, perform incremental workspace build</li> | ||
| 785 : | <li><code>POST_BUILD</code> event notification (<code>POST_BUILD</code> is the | ||
| 786 : | new name for <code>POST_AUTO_BUILD)</code></li> | ||
| 787 : | <li><code>POST_CHANGE</code> event notification</li> | ||
| 788 : | </ol> | ||
| 789 : | mcq | 1.9 | <p>The reference point for the deltas received by auto-build listeners will be |
| 790 : | johna | 1.1 | different from post-change listeners. Build listeners will receive notification |
| 791 : | of all changes since the end of the last build operation. Post-change listeners | ||
| 792 : | will receive a delta describing all changes since the last post-change | ||
| 793 : | notification. This new structure retains three characteristics of resource | ||
| 794 : | mcq | 1.9 | change listeners that have been true since Eclipse 1.0:</p> |
| 795 : | johna | 1.1 | <ul> |
| 796 : | <li><code>POST_CHANGE</code> listeners receive notification of absolutely all | ||
| 797 : | resource changes that occur during the time they are registered. This | ||
| 798 : | includes changes made by builders, and changes made by other listeners.</li> | ||
| 799 : | <li><code>PRE_AUTO_BUILD</code> listeners receive notification of all resource | ||
| 800 : | changes <b>except</b> changes made by builders and resource change | ||
| 801 : | mcq | 1.9 | listeners.</li> |
| 802 : | johna | 1.1 | <li><code>POST_AUTO_BUILD</code> listeners receive notification of all resource |
| 803 : | changes <b>except</b> changes made by other <code>POST_AUTO_BUILD</code> | ||
| 804 : | mcq | 1.9 | listeners.</li> |
| 805 : | johna | 1.1 | </ul> |
| 806 : | mcq | 1.9 | <p>However, there are some important differences with this approach. Prior to |
| 807 : | johna | 1.1 | Eclipse 3.0, auto-build listeners were always called before <code>POST_CHANGE</code> |
| 808 : | listeners. For this reason, the delta received by auto-build listeners was | ||
| 809 : | always a subset of the delta received by the <code>POST_CHANGE</code> listeners. | ||
| 810 : | This relationship is now essentially reversed. Auto-build listeners will receive | ||
| 811 : | a delta that is a super-set of all deltas supplied to <code>POST_CHANGE</code> | ||
| 812 : | listeners since the end of the last background build. As before, auto-build | ||
| 813 : | listeners will be allowed to modify the workspace, and post-change listeners | ||
| 814 : | mcq | 1.9 | will not.</p> |
| 815 : | johna | 1.1 | <p>It will no longer be true that upon completion of a workspace changing |
| 816 : | operation, that <code>AUTO_BUILD</code> event listeners will have been notified. | ||
| 817 : | Client code that registers resource change listeners with <code>IWorkspace.addResourceChangeListener(IResourceChangeListener)</code> | ||
| 818 : | is unlikely to be affected by this change because <code>AUTO_BUILD</code> | ||
| 819 : | events were never reported to these listeners. However, clients that use <code>IWorkspace.addResourceChangeListener(IResourceChangeListener,int)</code> | ||
| 820 : | and specify an event mask that includes <code>AUTO_BUILD</code> events are likely to | ||
| 821 : | be broken by this change if they make assumptions about when auto-build | ||
| 822 : | listeners run or what thread they run in. For example, if an auto-build listener | ||
| 823 : | is updating a domain model to reflect changes to the workspace, then this update | ||
| 824 : | might not have happened when the workspace changing operation returns. It is | ||
| 825 : | worth noting that only UI-level code can be affected in this way. Core-level | ||
| 826 : | code that is called via API may be called within the scope of an <code>IWorkspaceRunnable</code>, | ||
| 827 : | so it can never be sure about when resource change listeners will be called. The | ||
| 828 : | suggested fix for this breakage is to use <code>POST_CHANGE</code> instead of build | ||
| 829 : | listeners if it is necessary to have notification occur before the operation | ||
| 830 : | completes.</p> | ||
| 831 : | <h2><a name="Intermediate notifications during workspace operations"></a>22. Intermediate notifications during workspace operations</h2> | ||
| 832 : | <p>It will no longer be guaranteed that all resource changes that occur during | ||
| 833 : | the dynamic scope of an <code>IWorkspaceRunnable</code> will be batched in a | ||
| 834 : | single notification. This mechanism can still be used for batching changes to | ||
| 835 : | avoid unnecessary builds and notifications, but the Platform may now decide to | ||
| 836 : | perform notifications during the operation. This API contract change is not | ||
| 837 : | likely to be a breaking change for existing clients. It is equivalent to the | ||
| 838 : | Platform deciding to call <code>IWorkspace.checkpoint</code> periodically during | ||
| 839 : | a long running operations. The reason for this change is that it is now possible | ||
| 840 : | for multiple threads to be modifying the workspace concurrently. When one thread | ||
| 841 : | finishes modifying the workspace, a notification is required to prevent | ||
| 842 : | responsiveness problems, even if the other operation has not yet completed. This | ||
| 843 : | change also allows users to begin working on a set of resources before the | ||
| 844 : | operation completes. For example, a user can now begin browsing files in a | ||
| 845 : | project that is still in the process of being checked out. The new method <code>IWorkspace.run(IWorkspaceRunnable, | ||
| 846 : | ISchedulingRule, int, IProgressMonitor)</code> has an optional flag, <code>AVOID_UPDATE</code>, | ||
| 847 : | which operations can use as a hint to the platform to specify whether periodic | ||
| 848 : | updates are desired.</p> | ||
| 849 : | <h2><a name="URL stream handler extensions"></a>23. URL stream handler extensions</h2> | ||
| 850 : | <p><strong>What is affected:</strong> Plug-ins that contribute extensions to the <code>org.eclipse.core.runtime.urlHandlers</code> | ||
| 851 : | extension point.</p> | ||
| 852 : | <p><strong>Description:</strong> The contract for the <code>org.eclipse.core.runtime.urlHandlers</code> | ||
| 853 : | extension point was changed to use the URL Stream Handler service provided by | ||
| 854 : | OSGi. The OSGi support is superior to the one in Eclipse 2.1, and correctly | ||
| 855 : | handles dynamic handlers. Because of various design issues with the base Java | ||
| 856 : | URL handler mechanism, URLStreamHandlers registered with the OSGi handler | ||
| 857 : | service must implement <code>org.osgi.service.url.URLStreamHandlerService</code>.</p> | ||
| 858 : | <p><strong>Action required:</strong> Formerly, the handler class had to | ||
| 859 : | implement <code>java.net.URLStreamHandler</code> and extend the urlHandlers | ||
| 860 : | extension point. The extension point is no longer supported and the handler must | ||
| 861 : | be updated to implement <code>org.osgi.service.url.URLStreamHandlerService</code> | ||
| 862 : | interface. The OSGi framework provides an abstract base class (<code>org.osgi.service.url.AbstractURLStreamHandlerService</code>) | ||
| 863 : | that can be trivially subclassed to fill this role.</p> | ||
| 864 : | <p>Instead of registering the handler using an extension point, plug-ins must | ||
| 865 : | now do so by registering their handler as a service. For example,</p> | ||
| 866 : | <pre> Hashtable properties = new Hashtable(1); | ||
| 867 : | properties.put(URLConstants.URL_HANDLER_PROTOCOL, new String[] {MyHandler.PROTOCOL}); | ||
| 868 : | String serviceClass = URLStreamHandlerService.class.getName(); | ||
| 869 : | context.registerService(serviceClass, new MyHandler(), properties); | ||
| 870 : | </pre> | ||
| 871 : | <h2><a name="Class load order"></a>24. Class load order</h2> | ||
| 872 : | <p><b>What is affected:</b> Plug-ins which supply packages provided which are | ||
| 873 : | also supplied by other plug-ins. A very limited number of plug-ins are affected | ||
| 874 : | by this change and some of those affected will actually benefit (see below).</p> | ||
| 875 : | <p><b>Description:</b> In Eclipse 2.x, class loaders search for classes in the | ||
| 876 : | following order: consult (1) parent class loader (in practice this is the Java boot | ||
| 877 : | class loader), then (2) its own classpath contents, and finally (3) all of its prerequisites | ||
| 878 : | in the order declared. OSGi offers an optimization over this model. In this approach a | ||
| 879 : | class loader will consult (1) | ||
| 880 : | parent class loader (again, effectively the Java boot classloader), then either | ||
| 881 : | (2a) a single | ||
| 882 : | prerequisite known to contribute classes in the package being queried or (2b) its | ||
| 883 : | own classpath entries for the desired class.</p> | ||
| 884 : | <p>The class loader determines whether to consult self or its prerequisites based | ||
| 885 : | on its imported and required packages. This information is inferred from the | ||
| 886 : | plug-in content in the case of traditional plug-ins and directly specified in the | ||
| 887 : | case of plug-ins with explicit OSGi bundle manifest. In either case, it is known <i>a priori</i> which class | ||
| 888 : | loaders will supply the classes for which packages. This offers performance | ||
| 889 : | improvements as well as a solution to the vexing problem of multiple | ||
| 890 : | prerequisites contributing the same classes.</p> | ||
| 891 : | <p>Take for example the case of Xerces and Xalan, both of which contain various classes | ||
| 892 : | from org.xml packages. Using the first approach, the Xerces plug-in would see its | ||
| 893 : | copy of these classes while the Xalan plug-in would see their copy. Since these | ||
| 894 : | plug-ins need to communicate, ClassCastExceptions occur. Using the second | ||
| 895 : | approach, | ||
| 896 : | only one of the two plug-ins contributes the duplicate classes and both plug-ins | ||
| 897 : | see the same copies.</p> | ||
| 898 : | <p><b>Action required:</b> The action required depends on the particulars of the | ||
| 899 : | usecase. Affected developers need to review their classpath and resolve any | ||
| 900 : | conflicts which may be happening.</p> | ||
| 901 : | <h2><a name="Class loader protection domain not set"></a>25. Class loader protection domain not set</h2> | ||
| 902 : | <p><b>What is affected:</b> Plug-ins that expect the protection domain of their | ||
| 903 : | class loader to be set at all times.</p> | ||
| 904 : | <p><b>Description:</b> In Eclipse 2.1 plug-in class loaders were | ||
| 905 : | java.security.SecureClassloaders and, as such, always had a protection domain set. In Eclipse | ||
| 906 : | 3.0, class loaders do not extend SecureClassloader and only set the protection | ||
| 907 : | domain if Java security is turned on (not the normal case).</p> | ||
| 908 : | <p><b>Action required:</b> The action required will depend on the scenario in | ||
| 909 : | which the plug-in is using the protection domain.</p> | ||
| 910 : | <h2><a name="PluginModel object casting"></a>26. PluginModel object casting</h2> | ||
| 911 : | <p><b>What is affected:</b> Plug-ins which cast objects of type | ||
| 912 : | org.eclipse.core.runtime.IPlugin* to org.eclipse.core.runtime.model.Plugin*Model. Even though the relationship between these interfaces and the | ||
| 913 : | model classes is not specified in the Eclipse 2.1 API, we are explicitly | ||
| 914 : | calling out this change as we have found instances of plug-ins relying on this | ||
| 915 : | relationship in the 2.1 implementation.</p> | ||
| 916 : | <p><b>Description:</b> The Eclipse API provides a series of interfaces (e.g., <code>IPluginDescriptor</code>) | ||
| 917 : | and so-called "model" classes (e.g., <code>PluginDescriptorModel</code>) | ||
| 918 : | related to plug-ins and the plug-in registry. In the Eclipse 2.1 implementation | ||
| 919 : | it happens that the model classes implement the relevant interfaces. In the new | ||
| 920 : | OSGi-based runtime, the plug-in registry has been significantly reworked to allow for a | ||
| 921 : | separation between the class loading and prerequisite aspects of plug-ins and the | ||
| 922 : | extension and extension-point aspects. As such the Eclipse 3.0 runtime is unable | ||
| 923 : | to maintain the implementation relationship present in 2.1.</p> | ||
| 924 : | <p><b>Action required:</b> Plug-ins relying on this non-API | ||
| 925 : | relationship need to be reworked code according to their usecase. More | ||
| 926 : | information on this is given in the recommended changes section of this document | ||
| 927 : | and in the Javadoc for the related classes and methods.</p> | ||
| 928 : | <h2><a name="ILibrary implementation incomplete"></a>27. ILibrary implementation incomplete</h2> | ||
| 929 : | <p><b>What is affected:</b> Plug-ins that use <code>org.eclipse.core.runtime.ILibrary</code>.</p> | ||
| 930 : | <p><b>Description:</b> The new runtime maintains the classpath entries in a | ||
| 931 : | different and incompatible form from Eclipse. As a result, the compatibility | ||
| 932 : | layer is unable to correctly model the underlying OSGi structures as ILibrary | ||
| 933 : | objects. The runtime's compatibility support creates ILibrary objects but must | ||
| 934 : | assume default values for everything except the library's path.</p> | ||
| 935 : | <p><b>Action required:</b> Users of ILibrary should consider accessing the | ||
| 936 : | desired header values (e.g., <code>Bundle-Classpath</code>) from the appropriate | ||
| 937 : | Bundle (see <code>Bundle.getHeaders()</code>) and using the <code>ManifestElement</code> | ||
| 938 : | helper class to interpret the entries. See the class Javadoc for more details.</p> | ||
| 939 : | <h2><a name="Invalid assumptions regarding form of URLs"></a>28 Invalid assumptions regarding form of URLs</h2> | ||
| 940 : | <p><b>What is affected:</b> Plug-ins that make assumptions regarding their | ||
| 941 : | installation structure, location and the local file system layout.</p> | ||
| 942 : | <p><b>Description:</b> Methods such as <code>IPluginDescriptor.getInstallURL()</code> | ||
| 943 : | return URLs of a particular form. Despite their form being unspecified, various | ||
| 944 : | plug-ins are making assumptions based on the current implementation. For example, they | ||
| 945 : | may expect to get a <code>file:</code> URL and use URL.getFile() and use <code>java.io.File</code> | ||
| 946 : | manipulation on the result. To date, this has been a workable but rather fragile | ||
| 947 : | approach. For example, if a plug-in is installed on a web server, it is possible | ||
| 948 : | that an <code>http:</code> URL would be returned. The new Eclipse 3.0 runtime is | ||
| 949 : | even more flexible and opens more possibilities for execution configurations | ||
| 950 : | (e.g., maintaining whole plug-ins in JARs rather than exploded in directories). | ||
| 951 : | That is, while the new OSGi-based runtime does not actually break 2.1 API, it exposes more | ||
| 952 : | cases where assumptions made in current plug-ins are invalid.</p> | ||
| 953 : | <p><b>Action required:</b> Plug-in writers should ensure that the information to | ||
| 954 : | which they need access is available via <code>getResource()</code> (and is on the | ||
| 955 : | classpath) or use the relevant API for accessing the contents of a plug-in | ||
| 956 : | (e.g., <code>Bundle.getEntry(String)</code>).</p> | ||
| 957 : | <h2><a name="BootLoader methods moved/deleted"></a>29. BootLoader methods moved/deleted</h2> | ||
| 958 : | <p><b>What is affected:</b> Non-plug-in code that calls certain methods from the class | ||
| 959 : | <code>org.eclipse.core.boot.BootLoader</code>.</p> | ||
| 960 : | <p><b>Description:</b> The static methods BootLoader.startup(), shutdown() and run() were | ||
| 961 : | moved to org.eclipse.core.runtime.adaptor.EclipseStarter, which is part of the OSGi framework. | ||
| 962 : | This API is the interface between the main() in startup.jar and the OSGi | ||
| 963 : | framework/Eclipse runtime. The restructuring of the runtime did not permit these methods | ||
| 964 : | to remain on BootLoader. The old BootLoader class is now located in the runtime compatibility | ||
| 965 : | layer and is deprecated, and the moved methods are stubbed to do nothing.</p> | ||
| 966 : | <p>There is no replacement for the old BootLoader.getRunnable() as the runtime can no | ||
| 967 : | longer support the acquisition of individual applications. Rather, users must indicate the application of interest when they start the platform.</p> | ||
| 968 : | <p><b>Action required:</b> In general this API is used by very few people (it | ||
| 969 : | cannot be used from within an Eclipse plug-in). In | ||
| 970 : | the rare case that it is, the code must be adapted to use the corresponding methods on | ||
| 971 : | EclipseStarter.</p> | ||
| 972 : | |||
| 973 : | <h2><a name="Plug-in export does not include the plug-in's JARs automatically"></a>30. Plug-in export does not include the | ||
| 974 : | plug-in's JARs automatically</h2> | ||
| 975 : | <p><b>What </b><strong> is affected:</strong> All plug-ins.</p> | ||
| 976 : | <p><strong>Description:</strong> In Eclipse 2.1, a plug-in's bin.includes line | ||
| 977 : | from their build.properties did not have to contain the list of JARs from their | ||
| 978 : | library declaration in the plugin.xml file; these JARs were added for free. | ||
| 979 : | In Eclipse 3.0 the list of files in the bin.includes section of the build.properties | ||
| 980 : | is an exhaustive list and must include all files which plug-in developers intend | ||
| 981 : | to be included in their plug-in when building or exporting.</p> | ||
| 982 : | <p><strong>Action required:</strong> Ensure that the bin.includes line from the | ||
| 983 : | build.properties file includes all of the JARs listed in your plugin.xml file.</p> | ||
| 984 : | |||
| 985 : | |||
| 986 : | <h2><a name="Re-exporting runtime API"></a>31. Re-exporting runtime API</h2> | ||
| 987 : | <p><b>What is affected:</b> Plug-ins that expose API that includes elements from | ||
| 988 : | changed runtime API.</p> | ||
| 989 : | <p><b>Description:</b> Various plug-ins expose API that includes elements from | ||
| 990 : | the runtime API. With the changes to the Eclipse 3.0 runtime outlined here, | ||
| 991 : | client plug-ins must re-evaluate their use of runtime API in their API.</p> | ||
| 992 : | <p><b>Action required:</b> This scenario is quite rare as very little of | ||
| 993 : | the Eclipse runtime API is changing. Depending on the scenario, clients may have | ||
| 994 : | to change their API or continue to rely on the the compatibility layer.</p> | ||
| 995 : | <h2><a name="Plug-in parsing methods on Platform"></a>32. Plug-in parsing methods on Platform</h2> | ||
| 996 : | <p><b>What is affected:</b> Plug-ins that use <code>org.eclipse.core.runtime.Platform.parsePlugins(..., | ||
| 997 : | Factory).</code></p> | ||
| 998 : | <p><b>Description:</b> The method <code>org.eclipse.core.runtime.Platform.parsePlugins(..., | ||
| 999 : | Factory)</code> has been moved. The API associated with the Factory argument has | ||
| 1000 : | been moved from the org.eclipse.core.runtime plug-in up to the | ||
| 1001 : | org.eclipse.core.runtime.compatibility plug-in (which depends on the runtime | ||
| 1002 : | plug-in). As a result, the parsing method has been moved as well.</p> | ||
| 1003 : | <p><b>Action required:</b> Users of this method should use the same method on | ||
| 1004 : | the class <code>org.eclipse.core.runtime.model.PluginRegistryModel</code>.</p> | ||
| 1005 : | <h2><a name="Plug-in libraries supplied by fragments"></a>33. Plug-in libraries supplied by fragments</h2> | ||
| 1006 : | <p><b>What </b><strong> is affected:</strong> Plug-ins that specify code on their | ||
| 1007 : | classpath but do not supply that code (i.e., the JAR is supplied by a fragment; | ||
| 1008 : | for example, the org.eclipse.swt plug-in).</p> | ||
| 1009 : | <p><strong>Description:</strong> The new runtime must convert plug.xml files to | ||
| 1010 : | manifest.mf files behind the scenes. This is done through a straight mechanical transformation and | ||
| 1011 : | an analysis of the jars listed and supplied by the plug-in. In the case where a | ||
| 1012 : | plug-in specifies a jar on its classpath but does not supply the jar, there is | ||
| 1013 : | no code to analyze and the plug-in convertor cannot generate a correct | ||
| 1014 : | manifest.mf.</p> | ||
| 1015 : | <p><strong>Action required:</strong> Providers of such plug-ins must either | ||
| 1016 : | change to supply the appropriate jar in the plug-in itself or hand | ||
| 1017 : | craft/maintain a META-INF/MANIFEST.MF file for their plug-in. Typically this can | ||
| 1018 : | be done using PDE to get the initial manifest and then adding in the appropriate | ||
| 1019 : | Provide-Package header.</p> | ||
| 1020 : | <h2><a name="Changes to build scripts"></a>34. Changes to build scripts</h2> | ||
| 1021 : | <p><b>What is affected:</b> Scripts (e.g., Ant build.xml | ||
| 1022 : | files) which define classpaths containing runtime-related jars and class | ||
| 1023 : | directories.</p> | ||
| 1024 : | <p><b>Description:</b> The new runtime contains a number of new plug-ins and | ||
| 1025 : | jars. Their introduction was mandated by the refactoring of the runtime into | ||
| 1026 : | configurable pieces. For most runtime situations these changes are transparent. | ||
| 1027 : | However, if you have custom build.xml (or similar) scripts which currently | ||
| 1028 : | compile code against <code>org.eclipse.core.runtime</code>, you will need to update | ||
| 1029 : | them before they will function correctly. A typical script contains a classpath | ||
| 1030 : | entry in a <javac> task that references the <code>org.eclipse.core.runtime</code> | ||
| 1031 : | plug-in as follows:</p> | ||
| 1032 : | <pre> ../org.eclipse.core.runtime/bin;../org.eclipse.core.runtime/runtime.jar</pre> | ||
| 1033 : | <p>The runtime plug-in continues to contain much of the original runtime code. | ||
| 1034 : | However, various parts of the runtime which are there only for compatibility | ||
| 1035 : | johna | 1.11 | purposes are contained in a compatibility plug-in (<code>org.eclipse.core.runtime.compatibility</code>). |
| 1036 : | johna | 1.1 | Most of the new runtime code is contained in a collection of plug-ins (<code>org.eclipse.osgi.*</code>).</p> |
| 1037 : | <p><b>Action required:</b> Developers should add the entries below as needed to | ||
| 1038 : | eliminate compilation errors. While the complete set of jars supplied is listed | ||
| 1039 : | below, typical uses require only a subset on the classpath at compile time. As | ||
| 1040 : | usual, the inclusion of the /bin directories is discretionary. The entries are | ||
| 1041 : | given here in logical groupings by supplying plug-in:</p> | ||
| 1042 : | <ul> | ||
| 1043 : | <li>../org.eclipse.core.runtime.compatibility/bin;../org.eclipse.core.runtime.compatibility/compatibility.jar;</li> | ||
| 1044 : | <li>../org.eclipse.osgi/bin;../org.eclipse.osgi/osgi.jar;</li> | ||
| 1045 : | <li>../org.eclipse.update.configurator/bin;../org.eclipse.update.configurator/configurator.jar;</li> | ||
| 1046 : | <li>../org.eclipse.osgi.util/util.jar;</li> | ||
| 1047 : | </ul> | ||
| 1048 : | <p>In addition the following jars may be required in special cases:</p> | ||
| 1049 : | <ul> | ||
| 1050 : | <li>../org.eclipse.osgi/core.jar; ../org.eclipse.osgi/resolver.jar; ../org.eclipse.osgi/defaultAdaptor.jar; | ||
| 1051 : | ../org.eclipse.osgi/eclipseAdaptor.jar; ../org.eclipse.osgi/console.jar</li> | ||
| 1052 : | </ul> | ||
| 1053 : | <p>While updating such scripts, you should also take the opportunity to clean up | ||
| 1054 : | (i.e., remove) references to <code>org.eclipse.core.boot</code>. This plug-in is | ||
| 1055 : | obsolete and longer contains any code. The entries can be left on the classpath | ||
| 1056 : | but they serve no purpose and should be removed. Look to remove: | ||
| 1057 : | </p> | ||
| 1058 : | <pre> ../org.eclipse.core.boot/bin;../org.eclipse.core.boot/boot.jar</pre> | ||
| 1059 : | <h2><a name="Changes to PDE build Ant task"></a>35. Changes to PDE build Ant task</h2> | ||
| 1060 : | <p><b>What is affected:</b> Scripts (e.g., Ant build.xml | ||
| 1061 : | files) using the eclipse.buildScript task.</p> | ||
| 1062 : | <p><b>Description:</b> PDE Build introduced a new property to the eclipse.buildScript task to control the generation of plug-ins build | ||
| 1063 : | mcq | 1.9 | scripts. This was mandated by the introduction of the new OSGi-based runtime. |
| 1064 : | </p><p><b>Action required:</b> If you want to use Eclipse 3.0 to build a 2.1 based product, | ||
| 1065 : | johna | 1.1 | then introduce in eclipse.buildScript the property "buildingOSGi" and set it to false. |
| 1066 : | mcq | 1.9 | For example: </p><pre><eclipse.buildScript ... buildingOSGi="false"/></pre> |
| 1067 : | johna | 1.1 | |
| 1068 : | <h2><a name="Changes to eclipse.buildScript Ant task"></a>36. Changes to | ||
| 1069 : | eclipse.build Ant task</h2> | ||
| 1070 : | <p><b>What is affected:</b> Scripts (e.g., Ant build.xml files) using the | ||
| 1071 : | eclipse.buildScript task.</p> | ||
| 1072 : | <p><b>Description:</b> PDE Build introduced a new property to the | ||
| 1073 : | eclipse.buildScript task to control the generation of plug-ins build scripts. | ||
| 1074 : | mcq | 1.10 | This was mandated by the introduction of the new OSGi-based runtime.</p> |
| 1075 : | johna | 1.1 | <p><b>Action required:</b> If you want to use Eclipse 3.0 to build a 2.1 based |
| 1076 : | product, then introduce in eclipse.buildScript the property "buildingOSGi" | ||
| 1077 : | and set it to false. For example: | ||
| 1078 : | mcq | 1.10 | <pre><eclipse.buildScript ... buildingOSGi="false"/></pre></p> |
| 1079 : | johna | 1.1 | <h2><a name="Changes to eclipse.fetch Ant task"></a>37. Changes to eclipse.fetch |
| 1080 : | Ant task</h2> | ||
| 1081 : | <p><b>What is affected:</b> Scripts (e.g., Ant build.xml files) using the | ||
| 1082 : | eclipse.buildScript task.</p> | ||
| 1083 : | dmegert | 1.8 | <p><b>Description:</b> PDE Build changed the behavior of the eclipse.fetch task |
| 1084 : | johna | 1.1 | to ease building eclipse in an automated build style. The elements style now |
| 1085 : | mcq | 1.10 | only support one entry at a time and the scriptName is always ignored.</p> |
| 1086 : | johna | 1.1 | <p><b>Action required:</b> If you had a list of entries in the |
| 1087 : | "elements" tag of an eclipse.fetch call, spread them out over several | ||
| 1088 : | call to eclipse.fetch. If you use to set the scriptName, note that now the | ||
| 1089 : | generated fetch script is always called "fetch_{elementId}". For | ||
| 1090 : | mcq | 1.9 | example:</p> |
| 1091 : | johna | 1.1 | <pre><eclipse.fetch elements="plugin@org.eclipse.core.runtime, feature@org.eclipse.platform" .../></pre> |
| 1092 : | mcq | 1.9 | <p>becomes</p> |
| 1093 : | johna | 1.1 | <pre><eclipse.fetch elements="plugin@org.eclipse.core.runtime" .../> |
| 1094 : | <eclipse.fetch elements="feature@org.eclipse.platform" .../></pre> | ||
| 1095 : | |||
| 1096 : | <h2><a name="Replacement of install.ini"></a>38. Replacement of install.ini</h2> | ||
| 1097 : | <p>The install.ini file is no longer included. In its place is the new | ||
| 1098 : | config.ini file in the configuration sub-directory. Products that used the | ||
| 1099 : | install.ini file to specify a primary feature (e.g., to provide branding | ||
| 1100 : | information) need to make changes to the config.ini file instead. In addition to | ||
| 1101 : | the new filename, the names of the keys have changed.</p> | ||
| 1102 : | <p>The value of the feature.default.id key in 2.1 should be set as the value of | ||
| 1103 : | the new eclipse.product key. The value of the eclipse.application should be set | ||
| 1104 : | to "org.eclipse.ui.ide.workbench".</p> | ||
| 1105 : | <p>Finally, in 2.1 the image for the splash image was always splash.bmp in the | ||
| 1106 : | branding plug-in's directory. In 3.0 the location of the splash image is | ||
| 1107 : | provided explicitly by the osgi.splashPath key in the config.ini file.</p> | ||
| 1108 : | |||
| 1109 : | |||
| 1110 : | tod | 1.3 | |
| 1111 : | johna | 1.1 | |
| 1112 : | </body> | ||
| 1113 : | |||
| 1114 : | </html> |
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |