org.eclipse.platform.doc.isv/porting/3.0/recommended.html

Parent Directory Parent Directory | Revision Log 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.6
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.7 <link rel="STYLESHEET" href="../../book.css" charset="ISO-8859-1" type="text/css">
11 : tod 1.11 <title>Changes required when adopting 3.0 mechanisms and APIs</title>
12 : johna 1.1 </head>
13 :    
14 :     <body>
15 :    
16 : dmegert 1.8 <h2>Changes required when adopting 3.0 mechanisms and APIs</h2>
17 :     <p>This section describes changes that are required if you are trying to change
18 : johna 1.1 your 2.1 plug-ing to adopt the 3.0 mechanisms and APIs.</p>
19 :     <h3>Getting off of org.eclipse.core.runtime.compatibility</h3>
20 :     <p>The Eclipse 3.0 runtime is significantly different. The underlying implementation
21 :     is based on the OSGi framework specification. Eclipse 3.0 runtime includes
22 :     a compatibilty layer
23 :     (in the org.eclipse.core.runtime.compatibility plug-in) which maintains the
24 :     2.1 APIs. Plug-in
25 :     developers interested in additional performance and function should consider
26 :     adopting the 3.0 APIs and removing their dependence on the compatibility layer.
27 :     Compatibility code shows up in three places:</p>
28 :     <ul>
29 :     <li>org.eclipse.core.boot - entire plug-in is legacy</li>
30 :     <li>org.eclipse.core.runtime.compatibility - entire plug-in is legacy</li>
31 :     <li>org.eclipse.core.runtime - various classes and methods are legacy</li>
32 :     </ul>
33 :     <p>The text below gives more detail on the which classes and methods are present
34 :     for compatibility purposes as well as guidance on how to update your plug-in.</p>
35 :     <h4>Plug-ins and bundles</h4>
36 :     <p>The Eclipse runtime has been refactored into two parts; classloading and prerequisite
37 :     management, and extension/extension-point management. This split allows for
38 :     natural/seamless adoption of the OSGi framework specification for classloading
39 :     and prerequisite management. This in turn enables a range of new capabilities
40 :     in the runtime from dynamic plug-in install/update/uninstall to security and
41 :     increased configurability.</p>
42 :     <p>While we continue to talk about <i>plug-ins</i>, in the new runtime a plug-in
43 :     is really a <i>bundle</i> plus some extensions and extension-points. The term <i>bundle</i> is
44 :     defined by the OSGi framework specification and refers to a collection of types
45 :     and resources and associated inter-bundle prerequisite information. The <i>extension
46 :     registry</i> is the new form of the plug-in registry and details only extension
47 :     and extension-point information. By-in-large the extension registry API is
48 :     the same as the relevant plug-in
49 :     registry API (for more information see <a href="#registries">Registries</a>).</p>
50 :     <p>In the Eclipse 2.x runtime, the plug-in object has a number of roles and responsibilities:</p>
51 :     <ul>
52 :     <li>Lifecycle - The <tt>Plugin</tt> class implements method such as startup()
53 :     and shutdown(). The runtime uses these methods to signal the plug-in that
54 :     someone is interested in the function it provides. In response, plug-ins
55 :     typically do a combination of:
56 :     <ul>
57 :     <li>Registration - Hook various event mechanisms (e.g., register listeners)
58 :     and otherwise make their presence known in the system (e.g., start
59 :     needed threads). </li>
60 :     <li>Initialization - Initialize or prime their data structures and load
61 :     models so they are ready for use.</li>
62 :     </ul>
63 :     </li>
64 :     <li>Plug-in global data/function - While never explicitly put forth for this
65 :     role, in common practice plug-in classes have become a place to hang data
66 :     and function which is effectively global to the plug-in itself. In some cases
67 :     this data/function is API in others it is internal. For example, the UI plug-in
68 :     exposes as API methods such as <tt>getDialogSettings()</tt> and <tt>getWorkbench()</tt>.</li>
69 :     <li>Context - The standard <tt>Plugin</tt> class provides access to various
70 :     runtime-provided function such as preferences and logging.</li>
71 :     </ul>
72 :     <p>In the Eclipse 3.0 runtime picture, these roles and responsibilities are factored
73 :     into distinct objects.</p>
74 :     <dl>
75 :     <dt><b>Bundle</b></dt>
76 :     <dd>Bundles are the OSGi unit of modularity. There is one classloader per
77 :     bundle and Eclipse-like inter-bundle class loading dependency graphs can
78 :     be constructed. Bundles have lifecycle for start and stop and the OSGi
79 :     framework broadcasts bundle related events (e.g., install, resolve, start,
80 :     stop, uninstall, ...) to interested parties. Unlike the Eclipse <tt>Plugin</tt> class,
81 :     the OSGi <tt>Bundle</tt> class is not extensible. That is, developers do
82 :     not have the opportunity to define their own bundle class.</dd>
83 :     <dt><b>BundleActivator</b></dt>
84 :     <dd>BundleActivator is an interface defined by the OSGi framework. Each bundle
85 :     can define a bundle activator class much like a plug-in can define its <tt>Plugin</tt> class.
86 :     The specified class is instantiated by the framework and used to implement
87 :     the <tt>start()</tt> and <tt>stop()</tt> lifecycle
88 :     processing. There is a major difference however in the nature of this lifecycle
89 :     processing. In Eclipse it is common (though not recommended) to have the <tt>Plugin</tt> classes
90 :     do both initialization and registration. In OSGi activators must only do
91 :     registration. Doing large amounts of initialization (or any other work)
92 :     in <tt>BundleActivator.start()</tt> threatens the liveness of the system.</dd>
93 :     <dt><b>BundleContext</b></dt>
94 :     <dd>BundleContexts are the OSGi mechanism for exposing general system function
95 :     to individual bundles. Each bundle has a unique and <strong>private</strong> instance of
96 :     BundleContext which they can use to access system function (e.g., getBundles()
97 :     to discover all bundles in the system).</dd>
98 :     <dt><b>Plugin</b></dt>
99 :     <dd>The new <tt>Plugin</tt> is very much like the original Eclipse <tt>Plugin</tt> class
100 :     with the following exceptions: <tt>Plugin</tt> objects are no longer required
101 :     or managed by the runtime and various methods have been deprecated. It
102 :     is essentially a convenience mechanism providing a host of useful function
103 :     and mechanisms but is no longer absolutely required. Much of the function
104 :     provided there is also available on the <tt>Platform</tt> class in the
105 :     runtime.
106 :     <p><tt>Plugin</tt> also implements <tt>BundleActivator</tt>. This
107 :     recognizes the convenience of having one central object representing
108 :     the lifecycle and semantic of a plug-in. Note that this does not
109 :     however sanction the eager initialization of data structures that
110 :     is common in plug-ins today. We cannot stress enough that plug-ins
111 :     can be activated because a somewhat peripheral class was referenced
112 :     during verification of a class in some other plug-in. That is,
113 :     just because your plug-in has been activated does not necessarily
114 :     mean that its function is needed. Note also that you are free to
115 :     define a different <tt>BundleActivator</tt> class or not have a
116 :     bundle activator at all.</p>
117 :     </dd>
118 :     </dl>
119 :     <p>The steps required to port a 2.x <tt>Plugin</tt> class to Eclipse 3.0 depends
120 :     on what the class is doing. As outlined above, most startup lifecycle work
121 :     falls into one of the following categories:</p>
122 :     <dl>
123 :     <dt><b>Initialization</b></dt>
124 :     <dd>Datastructure and model initialization is quite often done in <tt>Plugin.startup()</tt>.
125 :     The natural/obvious mapping would be to do this work in a <tt>BundleActivator.start()</tt>,
126 :     that is to leave the function on <tt>Plugin</tt>. <b> This is strongly
127 :     discouraged.</b> As with 2.x plug-ins, 3.0 plug-ins/bundles may be started
128 :     for many different reasons in many different circumstances. <br>
129 :     An actual example from Eclipse 2.0 days illuminates this case. There was
130 :     a plug-in which initialized a large model requiring the loading of some
131 :     11MB of <i>code</i> and many megabytes of data. There were quite common
132 :     usecases where this plug-in was activated to discover if the project icon
133 :     presented in the navigator should be decorated with a particular markup.
134 :     This test did not require any of the initialization done in <tt>startup()</tt> but
135 :     yet all users, in all usecases had to pay the memory and time penalty for
136 :     this eager initialization.<br>
137 :     The alternative approach is to do such initialization in a classic lazy
138 :     style. For example, rather than having models initialized when the plug-in/bundle
139 :     is activated, do it when they are actually needed (e.g., in a centralized
140 :     model accessor method). For many usecases this will amount to nearly the
141 :     same point in time but for other scenarios this approach will defer initialization
142 :     (perhaps indefinitely). We recommend taking time while porting 2.1 plug-ins
143 :     to reconsider the initialization strategy used. </dd>
144 :     <dt><b>Registration</b></dt>
145 :     <dd>Plug-in startup is a convenient time to register listeners, services
146 :     etc. and start background processing threads (e.g., listening on a socket). <tt>Plugin.start()</tt> may
147 :     be a reasonable place to do this work. It may also make sense to defer
148 :     until some other trigger (e.g., the use of a particular function or data
149 :     element).</dd>
150 :     <dt><b>Plug-in global data</b></dt>
151 :     <dd>Your <tt>Plugin</tt> class can continue to play this role. The main issue
152 :     is that <tt>Plugin</tt> objects are no longer globally accessible via a
153 :     system-managed list. In Eclipse 2.x you could discover any plug-in's <tt>Plugin</tt> object
154 :     via the plug-in registry. This is no longer possible. In most circumstances
155 :     this type of access is not required. <tt>Plugins</tt> accessed via the
156 :     registry are more typically used as generic <tt>Plugins</tt> rather than
157 :     calling domain-specific methods. The equivalent level of capability can
158 :     be had by accessing and manipulating the corresponding Bundle objects.</dd>
159 :     </dl>
160 :     <h4><a name="registries"></a>Registries and the plug-in model</h4>
161 :     <p>In the new runtime there is a separation between the information and structures
162 :     needed to execute a plug-in and that related to a plug-in's extensions and
163 :     extension points. The former is defined and managed by the OSGi framework specification.
164 :     The latter are Eclipse-specific concepts and are added by they Eclipse runtime
165 :     code. Accordingly, the original plug-in registy and related objects have been
166 :     split into OSGi <i>bundles</i> and the Eclipse <i>extension registry</i>. </p>
167 :     <p>The parts of <tt>IPluginRegistry</tt> dealing with execution specification
168 :     (e.g., <tt>IPluginDescriptor, ILibrary</tt>, <tt>IPrequisite</tt>) have been
169 :     deprecated and the remaining parts related to extensions and extension point
170 :     have been moved to <tt>IExtensionRegistry</tt>. Further, the so-called model
171 :     objects related to the plug-in registry as a whole are now deprecated. These
172 :     types were presented and instantiated by the runtime primarily to support tooling
173 :     such as PDE. Unfortunately, it was frequently the case that the level of information
174 :     needed exceeded the runtime's capabilities or interests (e.g., remembering
175 :     line numbers for plugin.xml elements) and in the end, the potential consumers
176 :     of the runtime's information had to maintain their own structures anyway.</p>
177 :     <p>In the new runtime we have re-evaluated the facilities provided by the runtime
178 :     and now provide only those which are either essential for runtime execution
179 :     or are extraordinarily difficult for others to do. As mentioned above, the
180 :     plug-in registry model objects have been deprecated as has the plug-in parsing
181 :     API. The new extensions registry maintains the essential extension-related
182 :     information. A new <i>state</i> (see <tt>org.eclipse.osgi.service.resolver.State</tt> and
183 :     friends) structure represents and allows the manipulation of the essential
184 :     execution-related information. </p>
185 :     <h3>NL fragment structure</h3>
186 :     <p>In Eclipse 3.0 the NL fragment structure has been updated to be more consistent.
187 :     Previously the translations for files like plugin.properties were assumed to
188 :     be inside of JARs supplied by fragments. Since the original files are found
189 :     in the root of the relevant host plug-in, a more consistent location would
190 :     have the translated files located in the root of the NL fragments. For example, </p>
191 : mcq 1.4 <pre> org.eclipse.ui.workbench.nl/
192 : johna 1.1 fragment.xml
193 :     plugin_fr.properties
194 :     plugin_pt_BR.properties
195 :     ...
196 : mcq 1.4 nl1.jar</pre>
197 : johna 1.1 <p>Note here that the file nl1.jar previously would have contained the translations
198 :     for plugin.properties. These files are now at the root of the fragment and
199 :     the JAR contains translations of any translatable resources (i.e., files loaded
200 :     via the classloader) in the host plug-in. </p>
201 :     <p>Of course, the Eclipse 2.1 NL fragment structure is still supported for 2.1
202 :     host plug-ins running in Eclipse 3.0. You cannot however use a 2.1 NL fragment
203 :     on a 3.0 plug-in. The fragment must be updated to the new structure.</p>
204 :     <h3>API changes overview</h3>
205 :     <h4>org.eclipse.core.boot (package org.eclipse.core.boot)</h4>
206 :     <p>The entire org.eclipse.core.boot package has been deprecated. BootLoader has
207 :     been merged with <tt>org.eclipse.core.runtime.Platform</tt> since
208 :     it no longer made sense to have a split between boot and runtime. Note that
209 :     in fact, the org.eclipse.core.boot plug-in has been broken up and all its code
210 :     moved to either the new runtime or the compatibility layer. </p>
211 :     <p><tt>IPlatformConfiguration</tt> has
212 :     always been a type defined by and for the Eclipse Install/Update component.
213 :     With the reorganization of the runtime
214 :     we are able to repatriate this type to its rightful home. This class remains
215 :     largely unchanged and has been repackaged as <tt>org.eclipse.update.configurator.IPlatformConfiguration</tt>.
216 :     </p>
217 :     <p>IPlatformRunnable has been moved to org.eclipse.core.runtime.IPlatformRunnable. </p>
218 :     <h4>IExtension and IExtensionPoint (package org.eclipse.core.runtime)<br>
219 :     </h4>
220 :     <p>The <code>getDeclaringPlugin()</code> method (on both classes) gives an upward link
221 :     to the plug-in which declares the extension or extension-point (respectively).
222 :     The
223 :     new registry model separates the execution aspects of plug-ins from
224 :     the extension/extension-point aspects and no longer contains <tt>IPluginDescriptors</tt>.
225 :     Users of this API should consider the new method <tt>getParentIdentifier()</tt> found
226 :     on both <tt>IExtension</tt> and <tt>IExtensionPoint</tt>. </p>
227 :     <h4>ILibrary, IPluginDescriptor, IPluginRegistry and IPrerequisite (package org.eclipse.core.runtime)</h4>
228 :     <p> In the original runtime, the plug-in registry maintained a complete picture
229 :     of the runtime configuration. In Eclipse 3.0 this picture is split over the
230 :     OSGi framework and the extension registry. As such, these classes have been
231 :     deprecated. The deprecation notices contain details of how you should update
232 :     your code.</p>
233 :     <h4>Platform and Plugin (package org.eclipse.core.runtime)</h4>
234 :     <p>In the new runtime, <tt>Plugin</tt> objects are no longer managed
235 :     by the runtime and so cannot be accessed generically via the Platform. Similarly,
236 :     the plug-in registry no longer exists or gives access to plug-in descriptors.
237 :     There are however suitable replacement methods available and detailed in the
238 :     Javadoc of the deprecated methods in these classes.</p>
239 :     <h4>org.eclipse.core.runtime.model (package org.eclipse.core.runtime.model)</h4>
240 :     <p>All types in this package are now deprecated. See the discussion on <a href="#registries">registries</a> for
241 :     more information.</p>
242 :     <h4>IWorkspaceRunnable and IWorkspace.run (package org.eclipse.core.resources)</h4>
243 :     <p>Clients of the <tt>IWorkspace.run(IWorkspaceRunnable,IProgressMonitor)</tt>
244 :     method should revisit their uses of this method and consider using the richer
245 :     method <tt>IWorkspace.run(IWorkspaceRunnable,ISchedulingRule,int,IProgressMonitor)</tt>.
246 :     The old <tt>IWorkspace.run</tt> method acquires a lock on the entire workspace
247 :     for the duration of the <tt>IWorkspaceRunnable</tt>. This means that an
248 :     operation done with this method will never be able to run concurrently with
249 :     other operations that are changing the workspace. In Eclipse 3.0, many
250 :     long-running operations have been moved into background threads, so the
251 :     likelihood of conflicts between operations is greatly increased. If a modal
252 :     foreground operation is blocked by a long running background operation, the UI
253 :     becomes blocked until the background operation completes, or until one of the
254 :     operations is canceled.</p>
255 :     <p>The suggested solution is to switch all references to old <tt>IWorkspace.run</tt>
256 :     to use the new method with a scheduling rule parameter. The scheduling rule
257 :     should be the most fine-grained rule that encompasses the rules for all changes by that
258 :     operation. If the operation tries to modify resources outside of the scope
259 :     of the scheduling rule, a runtime exception will occur. The precise scheduling rule
260 :     required by a given workspace operation is not specified, and may change depending
261 :     on the installed repository provider on a given project. The factory
262 :     <code>IResourceRuleFactory</code> should be used to obtain the scheduling
263 :     rule for a resource-changing operation. If desired, a <tt>MultiRule</tt> can be used
264 :     to specify multiple resource rules, and the <tt>MultiRule.combine</tt> convenience
265 : mcq 1.10 method can be used to combine rules from various resource-changing operations.</p>
266 : johna 1.1 <p>
267 :     If no locking is required, a scheduling rule of <tt>null</tt> can be used. This will
268 :     allow the runnable to modify all resources in the workspace, but will not prevent other
269 :     threads from also modifying the workspace concurrently. For simple changes to
270 :     the workspace this is often the easiest and most concurrency-friendly solution.
271 :     </p>
272 :     <h4>IWorkbenchPage (package org.eclipse.ui)</h4>
273 :     <ul>
274 :     <li>The constant EDITOR_ID_ATTR is now deprecated. This is an IMarker
275 :     attribute name that specifies the preferred editor id to open the IMarker
276 :     resource with. This constant in now on org.eclipse.ui.ide.IDE class.</li>
277 :     </ul>
278 :     <h4>IEditorDescriptor (package org.eclipse.ui)</h4>
279 :     <ul>
280 :     <li>There are new API methods to determine whether the editor will open
281 :     internally to the workbench page (isInternal), in-place to the workbench
282 :     window (isOpenInPlace), or externally to the workbench (isExternal). While
283 :     this is not a breaking change, it is a good opportunity for clients that are
284 :     illegally down-casting IEditorDescriptor to
285 :     org.eclipse.ui.internal.model.EditorDescriptor to call isInternal to bring
286 :     there code back into line.</li>
287 :     </ul>
288 :     <h4>ISharedImages (package org.eclipse.ui)</h4>
289 :     <ul>
290 :     <li>The following fields were removed (deprecated) from this interface because
291 :     they were IDE-specific:
292 :     <ul>
293 :     <li>String IMG_OBJ_PROJECT</li>
294 :     <li>String IMG_OBJ_PROJECT_CLOSED</li>
295 :     <li>String IMG_OPEN_MARKER</li>
296 :     <li>String IMG_OBJS_TASK_TSK</li>
297 :     <li>String IMG_OBJS_BKMRK_TSK</li>
298 :     </ul>
299 :     </li>
300 :     <li>Existing clients should instead use the fields of the same names declared
301 :     on IDE.SharedImages in the org.eclipse.ui.ide package of the
302 :     org.eclipse.ui.ide plug-in.</li>
303 :     </ul>
304 :     <h4>IWorkbenchActionConstants (package org.eclipse.ui)</h4>
305 :     <ul>
306 :     <li>The following fields were removed (deprecated) from this interface; they
307 :     are subsumed by the new ActionFactory class:
308 :     <ul>
309 :     <li>String ABOUT</li>
310 :     <li>String BACK</li>
311 :     <li>String CLOSE</li>
312 :     <li>String CLOSE_ALL</li>
313 :     <li>String COPY</li>
314 :     <li>String CUT</li>
315 :     <li>String DELETE</li>
316 :     <li>String EXPORT</li>
317 :     <li>String FIND</li>
318 :     <li>String FORWARD</li>
319 :     <li>String IMPORT</li>
320 :     <li>String MOVE</li>
321 :     <li>String NEW</li>
322 :     <li>String NEXT</li>
323 :     <li>String PASTE</li>
324 :     <li>String PREVIOUS</li>
325 :     <li>String PRINT</li>
326 :     <li>String PROPERTIES</li>
327 :     <li>String QUIT</li>
328 :     <li>String REDO</li>
329 :     <li>String REFRESH</li>
330 :     <li>String RENAME</li>
331 :     <li>String REVERT</li>
332 :     <li>String SAVE</li>
333 :     <li>String SAVE_ALL</li>
334 :     <li>String SAVE_AS</li>
335 :     <li>String SELECT_ALL</li>
336 :     <li>String UNDO</li>
337 :     <li>String UP</li>
338 :     </ul>
339 :     </li>
340 :     <li>Clients should instead call getID() on the fields of the same names
341 :     declared on ActionFactory in the org.eclipse.ui.actions package (org.eclipse.ui
342 :     plug-in). For example, change IWorkbenchActionConstants.CUT to
343 :     ActionFactory.CUT.getId().</li>
344 :     <li>The following fields were removed (deprecated) from this interface because
345 :     they were IDE-specific.
346 :     <ul>
347 :     <li>String ADD_TASK</li>
348 :     <li>String BOOKMARK</li>
349 :     <li>String BUILD</li>
350 :     <li>String BUILD_PROJECT</li>
351 :     <li>String CLOSE_PROJECT</li>
352 :     <li>String FIND</li>
353 :     <li>String OPEN_PROJECT</li>
354 :     <li>String REBUILD_ALL</li>
355 :     <li>String REBUILD_PROJECT</li>
356 :     </ul>
357 :     </li>
358 :     <li>Clients should instead call getID() on the fields of the same names
359 :     declared on IDEActionFactory in the org.eclipse.ui.ide package (org.eclipse.ui.ide
360 :     plug-in). For example, change IWorkbenchActionConstants.BUILD to
361 :     IDEActionFactory.BUILD.getId().</li>
362 :     </ul>
363 :     <h4>IWorkbenchPreferenceConstants (package org.eclipse.ui)</h4>
364 :     <ul>
365 :     <li>The following fields were removed (deprecated) from this interface because
366 :     they were IDE-specific:
367 :     <ul>
368 :     <li>String PROJECT_OPEN_NEW_PERSPECTIVE</li>
369 :     </ul>
370 :     </li>
371 :     <li>Clients should instead use the fields of the same names declared on
372 :     IDE.Preferences in the org.eclipse.ui.ide package.</li>
373 :     </ul>
374 :     <h4>IExportWizard (package org.eclipse.ui)</h4>
375 :     <ul>
376 :     <li>Prior to 3.0, the selection passed to IWorkbenchWizard.init(IWorkbench,
377 :     IStructuredSelection) for an export wizard was preprocessed. If any of the
378 :     selections were IResources, or adaptable to IResource, then the selection
379 :     consisted only of these resources. In 3.0, the generic export wizard does
380 :     not do any preprocessing.&nbsp;</li>
381 :     <li>The selection passed to the wizard is generally used to prime the
382 :     particular wizard page with contextually appropriate values.</li>
383 :     <li>Client that implement IExportWizard and requires this resource-specific
384 :     selection transformation should add the following to their init(IWorkbench,
385 :     IStructuredSelection selection) method to computer <code>filteredSelection</code>
386 :     from <code>selection</code>:
387 :     <ul>
388 :     <li><code>IStructuredSelection filteredSelection = selection;<br>
389 :     List selectedResources = IDE.computeSelectedResources(currentSelection);<br>
390 :     if (!selectedResources.isEmpty()) {<br>
391 :     &nbsp;&nbsp;&nbsp; filteredSelection = new
392 :     StructuredSelection(selectedResources);<br>
393 :     }</code></li>
394 :     </ul>
395 :     </li>
396 :     </ul>
397 :     <h4>IImportWizard (package org.eclipse.ui)</h4>
398 :     <ul>
399 :     <li>Prior to 3.0, the selection passed to IWorkbenchWizard.init(IWorkbench,
400 :     IStructuredSelection) for an import wizard was preprocessed. If any of the
401 :     selections were IResources, or adaptable to IResource, then the selection
402 :     consisted only of these resources. In 3.0, the generic import wizard does
403 :     not do any preprocessing.&nbsp;</li>
404 :     <li>The selection passed to the wizard is generally used to prime the
405 :     particular wizard page with contextually appropriate values.</li>
406 :     <li>Client that implement IImportWizard and requires this resource-specific
407 :     selection transformation should add the following to their init(IWorkbench,
408 :     IStructuredSelection selection) method to compute a filtered selection from
409 :     the selection passed in:
410 :     <ul>
411 :     <li><code>IStructuredSelection filteredSelection = selection;<br>
412 :     List selectedResources = IDE.computeSelectedResources(currentSelection);<br>
413 :     if (!selectedResources.isEmpty()) {<br>
414 :     &nbsp;&nbsp;&nbsp; filteredSelection = new
415 :     StructuredSelection(selectedResources);<br>
416 :     }</code></li>
417 :     </ul>
418 :     </li>
419 :     </ul>
420 :     <h4>INewWizard (package org.eclipse.ui)</h4>
421 :     <ul>
422 :     <li>Prior to 3.0, the selection passed to IWorkbenchWizard.init(IWorkbench,
423 :     IStructuredSelection) for a new wizard was preprocessed. If there was no
424 :     structured selection at the time the wizard was invoked, but the active
425 :     workbench window had an active editor open on an IFile, then the selection
426 :     passed in would consist of that IFile. In 3.0, the generic new wizard does
427 :     not do any preprocessing, and an empty selection will be passed when there
428 :     is no structured selection.</li>
429 :     <li>The selection passed to the wizard is generally used to prime the
430 :     particular wizard page with contextually appropriate values.</li>
431 :     <li>Client that implement INewWizard and requires this capability should add
432 :     the following to their init(IWorkbench, IStructuredSelection selection)
433 :     method to compute a selection from the active editor's input:
434 :     <pre>if (selection.isEmpty()) {
435 :     IWorkbenchWindow window = PlatformUI.getWorkbench().getActiveWorkbenchWindow();
436 :     if (window != null) {
437 :     IWorkbenchPart part = window.getPartService().getActivePart();
438 :     if (part instanceof IEditorPart) {
439 :     IEditorInput input = ((IEditorPart) part).getEditorInput();
440 :     if (input instanceof IFileEditorInput) {
441 :     selection = new StructuredSelection(((IFileEditorInput) input).getFile());
442 :     }
443 :     }
444 :     }
445 :     }</pre>
446 :     </li>
447 :     </ul>
448 :     <h4>WorkbenchHelp (package org.eclipse.ui.help)</h4>
449 :     <ul>
450 :     <li>The following WorkbenchHelp method was removed (deprecated) from this
451 :     class because its result (IHelp) was removed (deprecated):
452 :     <ul>
453 :     <li>public static IHelp getHelpSupport()</li>
454 :     </ul>
455 :     </li>
456 :     <li>Clients that called this method to obtain an IHelp should instead call the
457 :     static methods on HelpSystem or WorkbenchHelp.</li>
458 :     </ul>
459 :     <h4>IHelp (package org.eclipse.help)</h4>
460 :     <ul>
461 :     <li>This interface has been removed (deprecated). WorkbenchHelp.getHelpsupport()
462 :     was the only way to get hold of an IHelp object. This method has also been
463 :     removed (deprecated).</li>
464 :     <li>The following IHelp methods now appear as static methods on a new
465 :     HelpSystem class in the same package:
466 :     <ul>
467 :     <li>public IToc[] getTocs()</li>
468 :     <li>public IContext getContext(String contextId)</li>
469 :     </ul>
470 :     </li>
471 :     <li>The rest of the IHelp methods now appear as static method on WorkbenchHelp.</li>
472 :     <li>This interface was formerly mentioned in the contract for the
473 :     org.eclipse.help.support extension point. This extension point has been
474 :     renamed &quot;org.eclipse.ui.helpSupport&quot;, and the contract simplified
475 :     so that the implementer only needs supply the display methods. For these
476 :     purposes, IHelp has been replaced by AbstractHelpUI (in the
477 :     org.eclipse.ui.help package).</li>
478 :     <li>There should be no clients implementing this interface beyond the Platform
479 :     which supplied the sole implementation of this interface.</li>
480 :     </ul>
481 :     <h4>ITextEditorActionConstants (package org.eclipse.ui.texteditor)</h4>
482 :     <ul>
483 :     <li>This interface additionally includes newly defined constants that redefine
484 :     deprecated constants inherited from org.eclipse.ui.IWorkbenchActionConstants.
485 :     This change allows clients to free their code from deprecation warnings. The
486 :     constants ADD_TASK and BOOKMARK have not been redefined as they are IDE
487 :     specific. When using these two constants in your code, please follow the
488 :     instructions given in the deprecation message.</li>
489 :     </ul>
490 :     <h4>IAbstractTextEditorHelpContextIds (package org.eclipse.ui.texteditor)</h4>
491 :     <ul>
492 :     <li>BOOKMARK_ACTION and ADD_TASK_ACTION have been deprecated because they are
493 :     IDE specific. Use the constants defined in
494 :     org.eclipse.ui.editors.text.ITextEditorHelpContextIds instead.</li>
495 :     </ul>
496 :     <h4>BasicTextEditorActionContributor (package org.eclipse.ui.texteditor)</h4>
497 :     <ul>
498 :     <li>BasicTextEditorActionContributor no longer assigns any editor action as
499 :     global action for org.eclipse.ui.IWorkbenchActionConstants.ADD_TASK and
500 :     org.eclipse.ui.IWorkbenchActionConstants.BOOKMARK because these actions are
501 :     IDE specific. This is now done by the
502 :     org.eclipse.ui.editors.text.TextEditorActionContributor. If your editors are
503 :     not configured to used TextEditorActionContributor but uses a contributor
504 :     that is a subclass of BasicTextEditorActionContributor, this contributor has
505 :     to be extended to also assign global action handlers for ADD_TASK and
506 :     BOOKMARK. This can be done by adding the following lines to the
507 :     setActiveEditor method of the editor action contributor:</li>
508 :     <li>
509 :     <pre> IActionBars actionBars= getActionBars();
510 :     if (actionBars != null) {
511 :     actionBars.setGlobalActionHandler(IDEActionFactory.ADD_TASK.getId(), getAction(textEditor, IDEActionFactory.ADD_TASK.getId()));
512 :     actionBars.setGlobalActionHandler(IDEActionFactory.BOOKMARK.getId(), getAction(textEditor, IDEActionFactory.BOOKMARK.getId()));
513 :     }</pre>
514 :     </li>
515 :     </ul>
516 :     <h4>TextEditorActionContributor (package org.eclipse.ui.editors.text)</h4>
517 :     <ul>
518 :     <li>TextEditorActionContributor assigns global action handlers for
519 :     IWorkbenchActionConstants.ADD_TASK (now IDEActionFactory.ADD_TASK.getId())
520 :     and IWorkbenchActionConstants.BOOKMARK (now IDEActionFactory.BOOKMARK.getId()).
521 :     These action handlers have previously been registered by
522 :     BasicTextEditorActionContributor. See migration notes for
523 :     BasicTextEditorActionContributor.</li>
524 :     </ul>
525 :     <h4>annotationTypes extension point (plug-in org.eclipse.ui.editors)</h4>
526 :     <p>
527 :     There is now the explicit notion of an annotation type. See Annotation.getType() and Annotation.setType().
528 :     The type of an annotation can change over it's lifetime. A new extension point has been added for the declaration
529 :     of annotation types: "org.eclipse.ui.editors.annotationTypes". An annotation type has a name and can be declared
530 :     as being a subtype of another declared annotation type. An annotation type declaration may also use the attributes
531 :     "markerType" and "markerSeverity" in order to specify that markers of a given type and a given severity should be
532 :     represented in text editors as annotations of a particular annotation type. The attributes "markerType" and
533 :     "markerSeverity" in the "org.eclipse.ui.editors.markerAnnotationSpecification" should no longer be used. Marker
534 :     annotation specifications are thus becoming independent from markers and the name thus misleading. However, the
535 :     name is kept in order to ensure backward compatibility.
536 :     </p><p>
537 :     Instances of subclasses of AbstractMarkerAnnotationModel automatically detect and set the correct annotation
538 :     types for annotations they create from markers. In order to programmatically retrieve the annotation type for
539 :     a given marker or a given pair of markerType and markerSeverity use org.eclipse.ui.texteditor.AnnotationTypeLookup.
540 :     </p><p>
541 :     Access to the hierarchy of annotation types is provided by IAnnotationAccessExtension. For a given annotation type
542 :     you can get the chain of super types and check whether an annotation type is a subtype of another annotation type.
543 :     DefaultMarkerAnnotationAccess implements this interface.
544 :     </p>
545 :     <h4>markerAnnotationSpecification extension point (plug-in org.eclipse.ui.editors)</h4>
546 :     <p>
547 :     The annotation type is the key with which to find the associated marker annotation specification. As annotation
548 :     types can extend other annotation types, there is an implicit relation between marker annotation specifications
549 :     as well. Therefore a marker annotation specification for a given annotation type is completed by the marker
550 :     annotation specifications given for the super types of the given annotation type. Therefore, marker annotation
551 :     specification do not have to be complete as this was required before. Marker annotation specifications are
552 :     retrieved by AnnotationPreferences. By using org.eclipse.ui.texteditor.AnnotationPreferenceLookup, you can retrieve
553 :     an annotation preference for a given annotation type that transparently performs the completion of the preference
554 :     along the annotation super type chain.
555 :     </p><p>
556 :     Marker annotation specification has been extended with three additional attributes in order to allow the definition
557 :     of custom appearances of a given annotation type in the vertical ruler. These attributes are: "icon", "symbolicIcon",
558 :     and "annotationImageProvider". The value for "icon" is the path to a file containing the icon image. The value of
559 :     "symbolicIcon" can be one of "error", "warning", "info", "task", "bookmark". The attribute "symbolicIcon" is used
560 :     to tell the platform that annotation should be depicted with the same images that are used by the platform to
561 :     present errors, warnings, infos, tasks, and bookmarks respectively. The value of "annotationImageProvider" is a
562 :     class implementing org.eclipse.ui.texteditor.IAnnotationImageProvider that allows for a full custom annotation
563 :     presentation.
564 :     </p><p>
565 :     The vertical ruler uses it's associated IAnnotationAccess/IAnnotationAccessExtension to draw annotations.
566 :     The vertical ruler does not call Annotation.paint any longer. In general, Annotations are no longer supposed
567 :     to draw themselves. The "paint" and "getLayer" methods have been deprecated in order to make annotation eventually
568 :     UI independent. DefaultMarkerAnnotationAccess serves as default implementation of IAnnotationAccess/IAnnotationAccessExtension.
569 :     DefaultMarkerAnnotationAccess implements the following strategy for painting annotations: If an annotation implements
570 :     IAnnotationPresentation, IAnnotationPresentation.paint is called. If not, the annotation image provider is looked up
571 :     in the annotation preference. The annotation image provider is only available if specified and if the plug-in defining
572 :     the enclosing marker annotation specification has already been loaded. If there is an annotation image provider, the
573 :     call is forwarded to it. If not, the specified "icon" is looked up. "symbolicIcon" is used as the final fallback. For
574 :     drawing annotations, the annotation presentation layer is relevant. DefaultMarkerAnnotationAccess looks up the presentation
575 :     layer using the following strategy: If the annotation preference specifies a presentation layer, the specified layer is
576 :     used. If there is no layer and the annotation implements IAnnotationPresentation, IAnnotationPresentation.getLayer is used
577 :     otherwise the default presentation layer (which is 0) is returned.
578 :     </p>
579 :     <h4>Migration to annotationTypes extension point (plug-in org.eclipse.ui.editors)</h4>
580 :     <p>
581 :     The following annotation types are declared by the org.eclipse.ui.editors plug-in:
582 :     </p>
583 :     <pre>
584 :     &lt;extension point="org.eclipse.ui.editors.annotationTypes"&gt;
585 :     &lt;type
586 :     name="org.eclipse.ui.workbench.texteditor.error"
587 :     markerType="org.eclipse.core.resources.problemmarker"
588 :     markerSeverity="2"&gt;
589 :     &lt;/type&gt;
590 :     &lt;type
591 :     name="org.eclipse.ui.workbench.texteditor.warning"
592 :     markerType="org.eclipse.core.resources.problemmarker"
593 :     markerSeverity="1"&gt;
594 :     &lt;/type&gt;
595 :     &lt;type
596 :     name="org.eclipse.ui.workbench.texteditor.info"
597 :     markerType="org.eclipse.core.resources.problemmarker"
598 :     markerSeverity="0"&gt;
599 :     &lt;/type&gt;
600 :     &lt;type
601 :     name="org.eclipse.ui.workbench.texteditor.task"
602 :     markerType="org.eclipse.core.resources.taskmarker"&gt;
603 :     &lt;/type&gt;
604 :     &lt;type
605 :     name="org.eclipse.ui.workbench.texteditor.bookmark"
606 :     markerType="org.eclipse.core.resources.bookmark"&gt;
607 :     &lt;/type&gt;
608 :     &lt;/extension&gt;
609 :     </pre>
610 :     <p>
611 :     The defined markerAnnotationSpecification extension no longer provide "markerType" and "markerSeverity"
612 :     attributes. They define the "symbolicIcon" attribute with the according value. Thus, MarkerAnnotation.paint
613 :     and MarkerAnnotation.getLayer are not called any longer, i.e. overriding these methods does not have
614 :     any effect. Affected clients should implement IAnnotationPresentation.
615 :     </p>
616 :     <h4>ILaunchConfigurationType (package org.eclipse.debug.core)</h4>
617 :     <p>With the introduction of extensible launch modes in 3.0, more than one launch
618 :     delegate can exist for a launch configuration type. Releases prior to 3.0 only
619 :     supported one launch delegate per launch configuration type. The method <code>ILaunchConfigurationType.getDelegate()</code>
620 :     is now deprecated. The method <code>getDelegate(String mode)</code> should be
621 :     used in its place to retrieve the launch delegate for a specific launch mode.
622 :     The deprecated method has been changed to return the launch delegate for the <code>run</code>
623 :     mode.</p>
624 :     <h4>ILaunchConfigurationTab and ILaunchConfigurationTabGroup (package
625 :     org.eclipse.debug.ui)</h4>
626 :     <p>Launch tab groups and launch tabs are no longer notified when a launch
627 :     completes. The method <code>launched(ILaunch)</code> in the interfaces <code>ILaunchConfigurationTab</code>
628 :     and <code>ILaunchConfigurationTabGroup</code> has been deprecated and is no
629 :     longer called. Relying on this method for launch function was always
630 :     problematic, since tabs only exist when launching is performed from the launch
631 :     dialog. Also, with the introduction of background launching, this method can no
632 :     longer be called, as the launch dialog is be closed before the resulting launch
633 :     object exists.</p>
634 :     <h4>ILaunchConfigurationTab and AbstractLaunchConfigurationTab (package
635 :     org.eclipse.debug.ui)</h4>
636 :     <p>Two methods have been added to the <code>ILaunchConfigurationTab</code>
637 :     interface - activated and deactivated. These new life cycle methods are called
638 :     when a tab is entered and exited respectively. Existing implementations of <code>ILaunchConfigurationTab</code>
639 :     that subclass the abstract class provided by the debug plug-in (<code>AbstractLaunchConfigurationTab</code>)
640 :     are binary compatible since the methods are implemented in the abstract class.</p>
641 :     <p>In prior releases, a tab was sent the message <code>initializeFrom</code>
642 :     when it was activated, and <code>performApply</code> when it was deactivated. In
643 :     this way, the launch configuration tab framework provided inter-tab
644 :     communication via a launch configuration (by updating the configuration with
645 :     current attribute values when a tab is exited, and updating the newly entered
646 :     tab). However, since many tabs do not perform inter-tab communication, this can
647 :     be inefficient. As well, there was no way to distinguish between a tab being
648 :     activated, and a tab displaying a selected launch configuration for the first
649 :     time. The newly added methods allow tabs to distinguish between activation and
650 :     initialization, and deactivation and saving current values.</p>
651 :     <p>The default implementation of <code>activated</code>, provided by the
652 :     abstract tab, calls <code>initializeFrom</code>. And, the default implementation
653 :     of <code>deactivated</code> calls <code>performApply</code>. Tabs wishing to
654 :     take advantage of the new API should override these methods as required.
655 :     Generally, for tabs that do not perform inter-tab communication, the recommended
656 :     approach is to re-implement these methods to do nothing.</p>
657 :     <h4>launchConfigurationTabGroup extension point Type (package
658 :     org.eclipse.debug.ui)</h4>
659 :     <p>In prior releases, perspective switching was specified on a launch
660 :     configuration, via the launch configuration attributes <code>ATTR_TARGET_DEBUG_PERSPECTIVE</code>
661 :     and <code>ATTR_TARGET_RUN_PERSPECTIVE</code>. With the addition of extensible
662 :     launch modes in 3.0, this approach no longer scales. Perspective switching is
663 :     now specified on launch configuration type basis, per launch mode that a launch
664 :     configuration type supports. API has been added to <code>DebugUITools</code> to
665 :     set and get the perspective associated with a launch configuration type for a
666 :     specific launch mode.</p>
667 :     <p>An additional, optional, <code>launchMode</code> element has been added to
668 :     the <code>launchConfigurationTabGroup</code> extension point, allowing a
669 :     contributed tab group to specify a default perspective for a launch
670 :     configuration type and mode.</p>
671 :     <p>From the Eclipse user interface, users can edit the perspective associated
672 :     with a launch configuration type by opening the launch configuration dialog, and
673 :     selecting a launch configuration type node in the tree (rather than an
674 :     individual configuration). A tab is displayed allowing the user to set a
675 :     perspective with each supported launch mode.</p>
676 :     <h4>[JDT only] IVMRunner (package org.eclipse.jdt.launching)</h4>
677 :     <p>Two methods have been added to the <code>VMRunnerConfiguration</code> class
678 :     to support the setting and retrieving of environment variables. Implementors of <code>IVMRunner</code>
679 :     should call <code>VMRunnerConfiguration.getEnvironment()</code> and pass that
680 :     environment into the executed JVM. Clients who use <code>DebugPlugin.exec(String[]
681 :     cmdLine, File workingDirectory)</code> can do this by calling <code>DebugPlugin.exec(String[]
682 :     cmdLine, File workingDirectory, String[] envp)</code> instead. Simply passing in
683 :     the result from <code>getEnvironment()</code> is sufficient.</p>
684 :     <h4>[JDT only] VMRunnerConfiguration and Bootstrap Classes (package
685 :     org.eclipse.jdt.launching)</h4>
686 :     <p>In prior releases, the <code>VMRunnerConfiguration</code> had one attribute
687 :     to describe a boot path. The attribute is a collection of <code>Strings</code>
688 :     to be specified in the -<code>Xbootclasspath</code> argument. Three new
689 :     attributes have been added to the VMRunnerConfiguration to support JVMs that
690 :     allow for prepending and appending to the boot path. The new methods/attributes
691 :     added are:</p>
692 :     <ul>
693 :     <li><code>getPrependBootClassPath()</code> - returns a collection of entries
694 :     to be prepended to the boot path (the <code>-Xbootclasspath/p</code>
695 : mcq 1.10 argument)</li>
696 : johna 1.1 <li><code>getMainBootClassPath()</code> - returns a collection of entries to
697 : mcq 1.10 be placed on the boot path (the <code>-Xbootclasspath</code> argument)</li>
698 : johna 1.1 <li><code>getAppendBootClassPath()</code> - returns a collection of entries to
699 :     be appended to the boot path (the <code>-Xbootclasspath/a</code> argument)</li>
700 :     </ul>
701 :     <p>The old attribute,<code> getBootClassPath()</code>, still exists and contains
702 :     a complete path equivalent to that of the three new attributes. However, <code>VMRunners</code>
703 :     that support the new boot path options should take advantage of the new
704 :     attributes.</p>
705 :     <h4>[JDT only] Improved support for working copies (package org.eclipse.jdt.core)</h4>
706 :     <p>The Java model working copy facility has been reworked in 3.0 to provide
707 :     greatly increased functionality. Prior to 3.0, the Java model allowed creation
708 :     of individual working copies of compilation units. Changes could be made to the
709 :     working copy and later committed. There was support for limited analysis of a
710 :     working copy in the context of the rest of the Java model. However, there was no
711 :     way these these analyses could ever take into account more than one of the
712 :     working copies at a time.</p>
713 :     <p>The changes in 3.0 make it possible to create and manage sets of working
714 :     copies of compilation units, and to perform analyses in the presence of all
715 :     working copies in a set. For example, it is now possible for a client like JDT
716 :     refactoring to create working copies for one or more compilation units that it
717 :     is considering modifying and then to resolve type references between the working
718 :     copies. Formerly this was only possible after the changes to the compilation
719 :     unit working copies had been committed.</p>
720 :     <p>The Java model API changes in 2 ways to add this improved support:</p>
721 :     <p>(1) The functionality formerly found on <code>IWorkingCopy</code> and
722 :     inherited by <code>ICompilationUnit</code> has been consolidated into <code>ICompilationUnit</code>.
723 :     The <code>IWorkingCopy</code> interface was only used in this one place, and was
724 :     gratuitously more general that in needed to be. This change simplifies the API. <code>IWorkingCopy</code>
725 :     has been deprecated. Other places in the API where <code>IWorkingCopy</code> is
726 :     used as a parameter or result type have been deprecated as well; the replacement
727 :     API methods mention <code>ICompilationUnit</code> instead of <code>IWorkingCopy</code>.</p>
728 :     <p>(2) The interface <code>IBufferFactory</code> has been replaced by <code>WorkingCopyOwner</code>.
729 :     The improved support for working copies requires that there be an object to own
730 :     the working copies. Although <code>IBufferFactory</code> is in the right place,
731 :     the name does not adequately convey how the new working copy mechanism works. <code>WorkingCopyOwner</code>
732 :     is much more suggestive. In addition, <code>WorkingCopyOwner</code> is declared
733 :     as an abstract class, rather than as an interface, to allow the notion of
734 :     working copy owner to evolve in the future. The one method on <code>IBufferFactory</code>
735 :     moves to <code>WorkingCopyOwner</code> unaffected. <code>WorkingCopyOwner</code>
736 :     does not implement <code>IBufferFactory</code> to make it clear that <code>IBufferFactory</code>
737 :     is a thing of the past. <code>IBufferFactory</code> has been deprecated. Other
738 :     places in the API where <code>IBufferFactory</code> appears as a parameter or
739 :     result type have been deprecated as well; the replacement API methods mention <code>WorkingCopyOwner</code>
740 :     instead of <code>IBufferFactory</code>.</p>
741 :     <p>These changes do not break binary compatibility.</p>
742 :     <p>When migrating, all references to the type <code>IWorkingCopy</code> should
743 :     instead reference <code>ICompilationUnit</code>. The sole implementation of <code>IWorkingCopy</code>
744 :     implements <code>ICompilationUnit</code> as well, meaning objects of type <code>IWorkingCopy</code>
745 :     can be safely cast to <code>ICompilationUnit</code>.</p>
746 :     <p>A class that implements <code>IBufferFactory</code> will need to replaced by
747 :     a subclass of <code>WorkingCopyOwner</code>. Although <code>WorkingCopyOwner</code>
748 :     does not implement <code>IBufferFactory</code> itself, it would be possible to
749 :     declare the subclass of <code>WorkingCopyOwner</code> that implements <code>IBufferFactory</code>
750 :     thereby creating a bridge between old and new (<code>IBufferFactory</code>
751 :     declares <code>createBuffer(IOpenable)</code> whereas <code>WorkingCopyOwner</code>
752 :     declares <code>createBuffer(ICompilationUnit)</code>; <code>ICompilationUnit</code>
753 :     extends <code>IOpenable</code>).</p>
754 :     <p>Because the changes involving <code>IWorkingCopy</code> and <code>IBufferFactory</code>
755 :     are interwined, we recommend dealing with both at the same time. The details of
756 :     the deprecations are as follows:</p>
757 :     <ul>
758 :     <li><code>IWorkingCopy</code> (package <code>org.eclipse.jdt.core</code>)
759 :     <ul>
760 :     <li><code>public void commit(boolean, IProgressMonitor)</code> has been
761 :     deprecated.
762 :     <ul>
763 :     <li>The equivalent functionality is now provided on <code>ICompilationUnit</code>
764 :     directly:
765 :     <ul>
766 :     <li><code>public void commitWorkingCopy(boolean, IProgressMonitor)</code></li>
767 :     </ul>
768 :     </li>
769 :     <li>Rewrite <code>wc.commit(b,monitor)</code> as <code>((ICompilationUnit)
770 :     wc).commitWorkingCopy(b,monitor)</code></li>
771 :     </ul>
772 :     </li>
773 :     <li><code>public void destroy()</code> has been deprecated.
774 :     <ul>
775 :     <li>The equivalent functionality is now provided on <code>ICompilationUnit</code>
776 :     directly:
777 :     <ul>
778 :     <li><code>public void discardWorkingCopy(boolean, IProgressMonitor)</code></li>
779 :     </ul>
780 :     </li>
781 :     <li>Rewrite <code>wc.destroy()</code> as <code>((ICompilationUnit)
782 :     wc).discardWorkingCopy()</code></li>
783 :     </ul>
784 :     </li>
785 :     <li><code>public IJavaElement findSharedWorkingCopy(IBufferFactory)</code>
786 :     has been deprecated.
787 :     <ul>
788 :     <li>The equivalent functionality is now provided on <code>ICompilationUnit</code>
789 :     directly:
790 :     <ul>
791 :     <li><code>public ICompilationUnit findWorkingCopy(WorkingCopyOwner)</code></li>
792 :     </ul>
793 :     </li>
794 :     <li>Note: <code>WorkingCopyOwner</code> substitutes for <code>IBufferFactory.</code></li>
795 :     </ul>
796 :     </li>
797 :     <li><code>public IJavaElement getOriginal(IJavaElement)</code> has been
798 :     deprecated.
799 :     <ul>
800 :     <li>The equivalent functionality is now provided on <code>IJavaElement</code>:
801 :     <ul>
802 :     <li><code>public IJavaElement getPrimaryElement()</code></li>
803 :     </ul>
804 :     </li>
805 :     </ul>
806 :     <ul>
807 :     <li>Rewrite <code>wc.getOriginal(elt)</code> as <code>elt.getPrimaryElement()</code></li>
808 :     <li>Note: Unlike <code>IWorkingCopy.getOriginal</code>, <code>IJavaElement.getPrimaryElement</code>
809 :     does not return <code>null</code> if the receiver is not a working
810 :     copy.</li>
811 :     </ul>
812 :     </li>
813 :     <li><code>public IJavaElement getOriginalElement()</code> has been
814 :     deprecated.
815 :     <ul>
816 :     <li>The equivalent functionality is now provided on <code>ICompilationUnit</code>
817 :     directly:
818 :     <ul>
819 :     <li><code>public ICompilationUnit getPrimary()</code></li>
820 :     </ul>
821 :     </li>
822 :     <li>Rewrite <code>wc.getOriginalElement()</code> as <code>((ICompilationUnit)
823 :     wc).getPrimary()</code></li>
824 :     <li>Note: Unlike <code>IWorkingCopy.getOriginalElement</code>, <code>IWorkingCopy.getPrimary</code>
825 :     does not return <code>null</code> if the receiver is not a working
826 :     copy.</li>
827 :     </ul>
828 :     </li>
829 :     <li><code>public IJavaElement[] findElements(IJavaElement)</code> has been
830 :     deprecated.
831 :     <ul>
832 :     <li>The method is now declared on <code>ICompilationUnit</code>
833 :     directly.</li>
834 :     <li>Rewrite <code>wc.findElements(elts)</code> as <code>((ICompilationUnit)
835 :     wc).findElements(elts)</code></li>
836 :     </ul>
837 :     </li>
838 :     <li><code>public IType findPrimaryType()</code> has been deprecated.
839 :     <ul>
840 :     <li>The method is now declared on <code>ICompilationUnit</code>
841 :     directly.</li>
842 :     <li>Rewrite <code>wc.findPrimaryType()</code> as <code>((ICompilationUnit)
843 :     wc).findPrimaryType()</code></li>
844 :     </ul>
845 :     </li>
846 :     <li><code>public IJavaElement getSharedWorkingCopy(IProgressMonitor,
847 :     IBufferFactory, IProblemRequestor)</code> has been deprecated.
848 :     <ul>
849 :     <li>The equivalent functionality is now provided on <code>ICompilationUnit</code>
850 :     directly:
851 :     <ul>
852 :     <li><code>public ICompilationUnit getWorkingCopy(WorkingCopyOwner,
853 :     IProblemRequestor, IProgressMonitor)</code></li>
854 :     </ul>
855 :     </li>
856 :     <li>Note: the parameter order has changed, and <code>WorkingCopyOwner</code>
857 :     substitutes for <code>IBufferFactory.</code></li>
858 :     </ul>
859 :     </li>
860 :     <li><code>public IJavaElement getWorkingCopy()</code> has been deprecated.
861 :     <ul>
862 :     <li>The equivalent functionality is now provided on <code>ICompilationUnit</code>
863 :     directly:
864 :     <ul>
865 :     <li><code>public ICompilationUnit getWorkingCopy(IProgressMonitor)</code></li>
866 :     </ul>
867 :     </li>
868 :     <li>Rewrite <code>wc.getWorkingCopy() </code>as <code>((ICompilationUnit)
869 :     wc).getWorkingCopy(null)</code></li>
870 :     </ul>
871 :     </li>
872 :     <li><code>public IJavaElement getWorkingCopy(IProgressMonitor,
873 :     IBufferFactory, IProblemRequestor)</code> has been deprecated.
874 :     <ul>
875 :     <li>The equivalent functionality is now provided on <code>ICompilationUnit</code>
876 :     directly:
877 :     <ul>
878 :     <li><code>public ICompilationUnit getWorkingCopy(WorkingCopyOwner,
879 :     IProblemRequestor, IProgressMonitor)</code></li>
880 :     </ul>
881 :     </li>
882 :     <li>Note: the parameter order has changed, and <code>WorkingCopyOwner</code>
883 :     substitutes for <code>IBufferFactory.</code></li>
884 :     </ul>
885 :     </li>
886 :     <li><code>public boolean isBasedOn(IResource)</code> has been deprecated.
887 :     <ul>
888 :     <li>The equivalent functionality is now provided on <code>ICompilationUnit</code>
889 :     directly:
890 :     <ul>
891 :     <li><code>public boolean hasResourceChanged()</code></li>
892 :     </ul>
893 :     </li>
894 :     <li>Rewrite <code>wc.isBasesOn(res)</code> as <code>((ICompilationUnit)
895 :     wc).hasResourceChanged()</code></li>
896 :     </ul>
897 :     </li>
898 :     <li><code>public boolean isWorkingCopy()</code> has been deprecated.
899 :     <ul>
900 :     <li>The method is now declared on <code>ICompilationUnit</code>
901 :     directly.</li>
902 :     <li>Rewrite <code>wc.isWorkingCopy()</code> as <code>((ICompilationUnit)
903 :     wc).isWorkingCopy()</code></li>
904 :     </ul>
905 :     </li>
906 :     <li><code>public IMarker[]&nbsp; reconcile()</code> has been deprecated.
907 :     <ul>
908 :     <li>The equivalent functionality is now provided on <code>ICompilationUnit</code>
909 :     directly:
910 :     <ul>
911 :     <li><code>public void reconcile(boolean,IProgressMonitor)</code></li>
912 :     </ul>
913 :     </li>
914 :     <li>Rewrite <code>wc.reconcile()</code> as <code>((ICompilationUnit)
915 :     wc).reconcile(false, null)</code></li>
916 :     <li>Note: The former method always returned <code>null</code>; the
917 :     replacement method does not return a result.</li>
918 :     </ul>
919 :     </li>
920 :     <li><code>public void reconcile(boolean, IProgressMonitor)</code> has been
921 :     deprecated.
922 :     <ul>
923 :     <li>The method is now declared on <code>ICompilationUnit</code>
924 :     directly.</li>
925 :     <li>Rewrite <code>wc.reconcile(b,monitor)</code> as <code>((ICompilationUnit)
926 :     wc).reconcile(b.monitor)</code></li>
927 :     </ul>
928 :     </li>
929 :     <li><code>public void restore()</code> has been deprecated.
930 :     <ul>
931 :     <li>The method is now declared on <code>ICompilationUnit</code>
932 :     directly.</li>
933 :     <li>Rewrite <code>wc.restore()</code> as <code>((ICompilationUnit)
934 :     wc).restore()</code></li>
935 :     </ul>
936 :     </li>
937 :     </ul>
938 :     </li>
939 :     <li><code>IType</code> (package <code>org.eclipse.jdt.core</code>)
940 :     <ul>
941 :     <li><code>public ITypeHierarchy newSupertypeHierarchy(IWorkingCopy[],
942 :     IProgressMonitor)</code> has been deprecated.
943 :     <ul>
944 :     <li>The replacement method is provided on the same class:
945 :     <ul>
946 :     <li><code>public ITypeHierarchy newSupertypeHierarchy(c,
947 :     IProgressMonitor)</code></li>
948 :     </ul>
949 :     </li>
950 :     <li>Note: The Java language rules for array types preclude casting <code>IWorkingCopy[]</code>
951 :     to <code>ICompilationUnit[]</code>.</li>
952 :     </ul>
953 :     </li>
954 :     <li><code>public ITypeHierarchy newTypeHierarchy(IWorkingCopy[],
955 :     IProgressMonitor)</code> has been deprecated.
956 :     <ul>
957 :     <li>The replacement method is provided on the same class:
958 :     <ul>
959 :     <li><code>public ITypeHierarchy newTypeHierarchy(ICompilationUnit[],
960 :     IProgressMonitor)</code></li>
961 :     </ul>
962 :     </li>
963 :     <li>Note: The Java language rules for array types preclude casting <code>IWorkingCopy[]</code>
964 :     to <code>ICompilationUnit[]</code>.</li>
965 :     </ul>
966 :     </li>
967 :     </ul>
968 :     </li>
969 :     <li><code>IClassFile</code> (package <code>org.eclipse.jdt.core</code>)
970 :     <ul>
971 :     <li><code>public IJavaElement getWorkingCopy(IProgressMonitor,
972 :     IBufferFactory)</code> has been deprecated.
973 :     <ul>
974 :     <li>The replacement method is provided on the same class:
975 :     <ul>
976 :     <li><code>public ICompilationUnit getWorkingCopy(WorkingCopyOwner,
977 :     IProgressMonitor)</code></li>
978 :     </ul>
979 :     </li>
980 :     <li>Note: the parameter order has changed, and <code>WorkingCopyOwner</code>
981 :     substitutes for <code>IBufferFactory.</code></li>
982 :     </ul>
983 :     </li>
984 :     </ul>
985 :     </li>
986 :     <li><code>JavaCore</code> (package <code>org.eclipse.jdt.core</code>)
987 :     <ul>
988 :     <li><code>public IWorkingCopy[] getSharedWorkingCopies(IBufferFactory)</code>
989 :     has been deprecated.
990 :     <ul>
991 :     <li>The replacement method is provided on the same class:
992 :     <ul>
993 :     <li><code>public ICompilationUnit[]
994 :     getWorkingCopies(WorkingCopyOwner)</code></li>
995 :     </ul>
996 :     </li>
997 :     <li>Note: <code>WorkingCopyOwner</code> substitutes for <code>IBufferFactory.</code></li>
998 :     <li>Note: The Java language rules for array types preclude casting <code>ICompilationUnit[]</code>
999 :     to <code>IWorkingCopy[]</code>.</li>
1000 :     </ul>
1001 :     </li>
1002 :     </ul>
1003 :     </li>
1004 :     <li><code>SearchEngine</code> (package <code>org.eclipse.jdt.core.search</code>)
1005 :     <ul>
1006 :     <li><code>public SearchEngine(IWorkingCopy[])</code> has been deprecated.
1007 :     <ul>
1008 :     <li>The replacement constructor is provided on the same class:
1009 :     <ul>
1010 :     <li><code>public SearchEngine(ICompilationUnit[])</code></li>
1011 :     </ul>
1012 :     </li>
1013 :     <li>Note: The Java language rules for array types preclude casting <code>IWorkingCopy[]</code>
1014 :     to <code>ICompilationUnit[]</code>.</li>
1015 :     </ul>
1016 :     </li>
1017 :     </ul>
1018 :     </li>
1019 :     </ul>
1020 :     <h4>Restructuring of org.eclipse.help plug-in</h4>
1021 :     <p>The org.eclipse.help plug-in, which used to hold APIs and extension points
1022 :     for contributing to and extending help system, as well as displaying help, now
1023 :     contains just APIs and extension points for contributing and accessing help
1024 :     resources. A portion of default help UI implementation contained in that plug-in
1025 :     has been moved to a new plug-in org.eclipse.help.base together with APIs for
1026 :     extending the implementation. The APIs and extension point for contributing Help
1027 :     UI and displaying help have been moved to org.eclipse.ui plug-in. This
1028 :     restructuring allows applications greater flexibility with regard to the help
1029 :     system; the new structure allows applications based on the generic workbench to
1030 :     provide their own Help UI and/or Help implementation, or to omit the help system
1031 :     entirely.</p>
1032 :     <p>Because the extension points and API packages affected are intended only for
1033 :     use by the help system itself, it is unlikely that existing plug-ins are
1034 :     affected by this change. They are included here only for the sake of
1035 :     completeness:</p>
1036 :     <ul>
1037 :     <li>API packages org.eclipse.ui.help.browser and
1038 :     org.eclipse.ui.help.standalone, formerly provided by the org.eclipse.help
1039 :     plug-in, have been moved to the org.eclipse.help.base plug-in.</li>
1040 :     <li>Extension points org.eclipse.help.browser, org.eclipse.help.luceneAnalyzer,
1041 :     and org.eclipse.help.webapp, formerly defined by the org.eclipse.help
1042 :     plug-in, have been moved to the org.eclipse.help.base plug-in, with a
1043 :     corresponding change in extension point id.</li>
1044 :     <li>Extension point org.eclipse.help.support has been replaced by the
1045 :     org.eclipse.ui.helpSupport extension point. The contract for this extension
1046 :     point changed as well (see entry for IHelp).</li>
1047 :     </ul>
1048 :     <h4>New Search UI API</h4>
1049 :     <P>A new API for implmenting custom searches has been added in 3.0. The original API is deprecated in 3.0 and we recommend that cllients port to the new API in the packages org.eclipse.search.ui and org.eclipse.search.ui.text.
1050 :     </P>
1051 :     <P>Clients will have to create implementations of <CODE>ISearchQuery</CODE>, <CODE>ISearchResult</CODE> and <CODE>ISearchResultPage</CODE>. The <CODE>ISearchResultPage</CODE> implementation must then be contributed into the new <CODE>org.eclipse.search.searchResultViewPages</CODE> extension point. </P>
1052 :     <P>Default implementations for <CODE>ISearchResult</CODE> and <CODE>ISearchResultPage</CODE> are provided in the package<CODE>
1053 :     org.eclipse.search.ui.text</CODE>.</P>
1054 :    
1055 :     <h4>null messages in MessageBox and DirectoryDialog (package
1056 :     org.eclipse.swt.widgets)</h4>
1057 :     <p>Prior to 3.0, calling SWT's DirectoryDialog.setMessage(String string) or
1058 :     MessageBox.setMessage(String string) with a null value for string would result
1059 :     in a dialog with no text in the title. This behavior was unspecified (passing
1060 :     null has never been permitted) and creates problems with getMessage which is not
1061 :     permitted to return null. In 3.0, passing null now results in an
1062 :     IllegalArgumentException exception being thrown, and the specifications have
1063 :     been changed to state this, bringing it into line with the method on their
1064 :     superclass Dialog.setMessage. If you use Dialog.setMessage, ensure that that the
1065 :     string passed in is never null. Simply pass an empty string if you want a dialog
1066 :     with no text in the title.</p>
1067 :     <h4>Improving modal progress feedback</h4>
1068 :     <p>Supporting concurrent operations requires more sophisticated ways to show
1069 :     modal progress. As part of the responsiveness effort additional progress support
1070 :     was implemented in the class IProgressService. The existing way to show progress
1071 :     with the ProgressMonitorDialog is still working. However, to improve the user
1072 :     experience we recommend migrating to the new IProgressService.</p>
1073 :     <p>The document <a href="http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/platform-core-home/documents/plan_concurrency_modal_progress.html">Showing
1074 :     Modal Progress in Eclipse 3.0</a> describes how to migrate to the new
1075 :     IProgressService.</p>
1076 :     <h4>Debug Action Groups removed</h4>
1077 :     <p>The Debug Action Groups extension point
1078 :     (org.eclipse.debug.ui.debugActionGroups) has been removed. In Eclipse 3.0, the
1079 :     workbench introduced support for Activities via the
1080 :     org.eclipse.platform.ui.activities extension point. This support provides
1081 :     everything that Debug Action Groups provided and is also easier to use (it
1082 :     supports patterns instead of specifying all actions exhaustively) and has a
1083 :     programmatic API to support it. Failing to remove references to the old
1084 :     extension point won't cause any failures. References to the extension point will
1085 :     simply be ignored. Product vendors are encouraged to use the workbench
1086 :     Activities support to associate language-specific debugger actions with
1087 :     language-specific activities (for example, C++ debugging actions might be
1088 :     associated with an activity called &quot;Developing C++&quot;).</p>
1089 :     <h4>BreakpointManager can be disabled</h4>
1090 :     <p>IBreakpointManager now defines the methods setEnabled(boolean) and
1091 :     isEnabled(). When the breakpoint manager is disabled, debuggers should ignore
1092 :     all registered breakpoints. The debug platform also provides a new listener
1093 :     mechanism, IBreakpointManagerListener which allows clients to register with the
1094 :     breakpoint manager to be notified when its enablement changes. The Breakpoints
1095 :     view calls this API from a new toggle action that allows the user to &quot;Skip
1096 :     All Breakpoints.&quot; Debuggers which do not honor the breakpoint manager's
1097 :     enablement will thus appear somewhat broken if the user tries to use this
1098 :     feature.</p>
1099 :     <h4>[JDT only] Java search participants (package org.eclipse.jdt.core.search)</h4>
1100 :     <p>Languages close to Java (such as JSP, SQLJ, JWS, etc.) should be able to
1101 :     participate in Java searching. In particular, implementors of such languages
1102 : mcq 1.10 should be able to:</p>
1103 : johna 1.1 <ul>
1104 :     <li>index their source by converting it into Java equivalent source, and
1105 : mcq 1.10 feeding it to the Java indexer</li>
1106 :     <li>index their source by parsing it themselves, but record Java index entries</li>
1107 : johna 1.1 <li>locate matches in their source by converting it into Java equivalent
1108 : mcq 1.10 source, and feeding it to the Java match locator</li>
1109 : johna 1.1 <li>locate matches in their source by matching themselves, and return Java
1110 :     matches</li>
1111 :     </ul>
1112 :     <p>Such an implementor is called a search participant. It extends the
1113 :     SearchParticipant class. Search participants are passed to search queries (see
1114 :     SearchEngine.search(SearchPattern, SearchParticipant[], IJavaSearchScope,
1115 :     SearchRequestor, IProgressMonitor)).</p>
1116 :     <p>For either indexing or locating matches, a search participant needs to define
1117 :     a subclass of SearchDocument that can retrieve the contents of the document by
1118 :     overriding either getByteContents() or getCharContents(). An instance of this
1119 :     subclass is returned in getDocument(String).</p>
1120 :     <p>A search participant wishing to index some document will use
1121 :     SearchParticipant.scheduleDocumentIndexing(SearchDocument, IPath) to schedule
1122 :     the indexing of the given document in the given index. Once the document is
1123 :     ready to be indexed, the underlying framework calls
1124 :     SearchParticipant.indexDocument(SearchDocument, IPath). The search participant
1125 :     then gets the document's content, parses it and adds index entries using
1126 :     SearchDocument.addIndexEntry(char[], char[]).</p>
1127 :     <p>Once indexing is done, one can then query the indexes and locate matches
1128 :     using SearchEngine.search(SearchPattern, SearchParticipant[], IJavaSearchScope,
1129 :     SearchRequestor, IProgressMonitor). This first asks each search participant for
1130 :     the indexes needed by this query using
1131 :     SearchParticipant.selectIndexes(SearchPattern, IJavaSearchScope). For each index
1132 :     entry that matches the given pattern, a search document is created by asking the
1133 :     search participant (see getDocument(String)). All these documents are passed to
1134 :     the search participant so that it can locate matches using
1135 :     locateMatches(SearchDocument[], SearchPattern, IJavaSearchScope, SearchRequestor,
1136 :     IProgressMonitor). The search participant notifies the SearchRequestor of search
1137 :     matches using acceptSearchMatch(SearchMatch) and passing an instance of a
1138 :     subclass of SearchMatch.</p>
1139 :     <p>A search participant can delegate part of its work to the default Java search
1140 :     participant. An instance of this default participant is obtained using
1141 :     SearchEngine.getDefaultSearchParticipant(). For example when asked to locate
1142 :     matches, an SQLJ participant can create documents .java documents from its .sqlj
1143 :     documents and delegate the work to the default participant passing it the .java
1144 :     documents.</p>
1145 : tod 1.3
1146 : johna 1.1
1147 :     </body>
1148 :    
1149 :     </html>