org.eclipse.platform.doc.isv/porting/3.0/recommended.html
Parent Directory
| 
Revision Log
Revision 1.12 -
(download)
(as text)
(annotate)
Wed Jul 19 21:20:55 2006 UTC (3 years, 4 months ago) by johna
Branch: MAIN
CVS Tags: HEAD
Changes since 1.11: +0 -0 lines
FILE REMOVED
Wed Jul 19 21:20:55 2006 UTC (3 years, 4 months ago) by johna
Branch: MAIN
CVS Tags: HEAD
Changes since 1.11: +0 -0 lines
FILE REMOVED
removed 3.0 porting guide (n-2 is the main migration range of interest)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<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." >
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="STYLESHEET" href="../../book.css" charset="ISO-8859-1" type="text/css">
<title>Changes required when adopting 3.0 mechanisms and APIs</title>
</head>
<body>
<h2>Changes required when adopting 3.0 mechanisms and APIs</h2>
<p>This section describes changes that are required if you are trying to change
your 2.1 plug-ing to adopt the 3.0 mechanisms and APIs.</p>
<h3>Getting off of org.eclipse.core.runtime.compatibility</h3>
<p>The Eclipse 3.0 runtime is significantly different. The underlying implementation
is based on the OSGi framework specification. Eclipse 3.0 runtime includes
a compatibilty layer
(in the org.eclipse.core.runtime.compatibility plug-in) which maintains the
2.1 APIs. Plug-in
developers interested in additional performance and function should consider
adopting the 3.0 APIs and removing their dependence on the compatibility layer.
Compatibility code shows up in three places:</p>
<ul>
<li>org.eclipse.core.boot - entire plug-in is legacy</li>
<li>org.eclipse.core.runtime.compatibility - entire plug-in is legacy</li>
<li>org.eclipse.core.runtime - various classes and methods are legacy</li>
</ul>
<p>The text below gives more detail on the which classes and methods are present
for compatibility purposes as well as guidance on how to update your plug-in.</p>
<h4>Plug-ins and bundles</h4>
<p>The Eclipse runtime has been refactored into two parts; classloading and prerequisite
management, and extension/extension-point management. This split allows for
natural/seamless adoption of the OSGi framework specification for classloading
and prerequisite management. This in turn enables a range of new capabilities
in the runtime from dynamic plug-in install/update/uninstall to security and
increased configurability.</p>
<p>While we continue to talk about <i>plug-ins</i>, in the new runtime a plug-in
is really a <i>bundle</i> plus some extensions and extension-points. The term <i>bundle</i> is
defined by the OSGi framework specification and refers to a collection of types
and resources and associated inter-bundle prerequisite information. The <i>extension
registry</i> is the new form of the plug-in registry and details only extension
and extension-point information. By-in-large the extension registry API is
the same as the relevant plug-in
registry API (for more information see <a href="#registries">Registries</a>).</p>
<p>In the Eclipse 2.x runtime, the plug-in object has a number of roles and responsibilities:</p>
<ul>
<li>Lifecycle - The <tt>Plugin</tt> class implements method such as startup()
and shutdown(). The runtime uses these methods to signal the plug-in that
someone is interested in the function it provides. In response, plug-ins
typically do a combination of:
<ul>
<li>Registration - Hook various event mechanisms (e.g., register listeners)
and otherwise make their presence known in the system (e.g., start
needed threads). </li>
<li>Initialization - Initialize or prime their data structures and load
models so they are ready for use.</li>
</ul>
</li>
<li>Plug-in global data/function - While never explicitly put forth for this
role, in common practice plug-in classes have become a place to hang data
and function which is effectively global to the plug-in itself. In some cases
this data/function is API in others it is internal. For example, the UI plug-in
exposes as API methods such as <tt>getDialogSettings()</tt> and <tt>getWorkbench()</tt>.</li>
<li>Context - The standard <tt>Plugin</tt> class provides access to various
runtime-provided function such as preferences and logging.</li>
</ul>
<p>In the Eclipse 3.0 runtime picture, these roles and responsibilities are factored
into distinct objects.</p>
<dl>
<dt><b>Bundle</b></dt>
<dd>Bundles are the OSGi unit of modularity. There is one classloader per
bundle and Eclipse-like inter-bundle class loading dependency graphs can
be constructed. Bundles have lifecycle for start and stop and the OSGi
framework broadcasts bundle related events (e.g., install, resolve, start,
stop, uninstall, ...) to interested parties. Unlike the Eclipse <tt>Plugin</tt> class,
the OSGi <tt>Bundle</tt> class is not extensible. That is, developers do
not have the opportunity to define their own bundle class.</dd>
<dt><b>BundleActivator</b></dt>
<dd>BundleActivator is an interface defined by the OSGi framework. Each bundle
can define a bundle activator class much like a plug-in can define its <tt>Plugin</tt> class.
The specified class is instantiated by the framework and used to implement
the <tt>start()</tt> and <tt>stop()</tt> lifecycle
processing. There is a major difference however in the nature of this lifecycle
processing. In Eclipse it is common (though not recommended) to have the <tt>Plugin</tt> classes
do both initialization and registration. In OSGi activators must only do
registration. Doing large amounts of initialization (or any other work)
in <tt>BundleActivator.start()</tt> threatens the liveness of the system.</dd>
<dt><b>BundleContext</b></dt>
<dd>BundleContexts are the OSGi mechanism for exposing general system function
to individual bundles. Each bundle has a unique and <strong>private</strong> instance of
BundleContext which they can use to access system function (e.g., getBundles()
to discover all bundles in the system).</dd>
<dt><b>Plugin</b></dt>
<dd>The new <tt>Plugin</tt> is very much like the original Eclipse <tt>Plugin</tt> class
with the following exceptions: <tt>Plugin</tt> objects are no longer required
or managed by the runtime and various methods have been deprecated. It
is essentially a convenience mechanism providing a host of useful function
and mechanisms but is no longer absolutely required. Much of the function
provided there is also available on the <tt>Platform</tt> class in the
runtime.
<p><tt>Plugin</tt> also implements <tt>BundleActivator</tt>. This
recognizes the convenience of having one central object representing
the lifecycle and semantic of a plug-in. Note that this does not
however sanction the eager initialization of data structures that
is common in plug-ins today. We cannot stress enough that plug-ins
can be activated because a somewhat peripheral class was referenced
during verification of a class in some other plug-in. That is,
just because your plug-in has been activated does not necessarily
mean that its function is needed. Note also that you are free to
define a different <tt>BundleActivator</tt> class or not have a
bundle activator at all.</p>
</dd>
</dl>
<p>The steps required to port a 2.x <tt>Plugin</tt> class to Eclipse 3.0 depends
on what the class is doing. As outlined above, most startup lifecycle work
falls into one of the following categories:</p>
<dl>
<dt><b>Initialization</b></dt>
<dd>Datastructure and model initialization is quite often done in <tt>Plugin.startup()</tt>.
The natural/obvious mapping would be to do this work in a <tt>BundleActivator.start()</tt>,
that is to leave the function on <tt>Plugin</tt>. <b> This is strongly
discouraged.</b> As with 2.x plug-ins, 3.0 plug-ins/bundles may be started
for many different reasons in many different circumstances. <br>
An actual example from Eclipse 2.0 days illuminates this case. There was
a plug-in which initialized a large model requiring the loading of some
11MB of <i>code</i> and many megabytes of data. There were quite common
usecases where this plug-in was activated to discover if the project icon
presented in the navigator should be decorated with a particular markup.
This test did not require any of the initialization done in <tt>startup()</tt> but
yet all users, in all usecases had to pay the memory and time penalty for
this eager initialization.<br>
The alternative approach is to do such initialization in a classic lazy
style. For example, rather than having models initialized when the plug-in/bundle
is activated, do it when they are actually needed (e.g., in a centralized
model accessor method). For many usecases this will amount to nearly the
same point in time but for other scenarios this approach will defer initialization
(perhaps indefinitely). We recommend taking time while porting 2.1 plug-ins
to reconsider the initialization strategy used. </dd>
<dt><b>Registration</b></dt>
<dd>Plug-in startup is a convenient time to register listeners, services
etc. and start background processing threads (e.g., listening on a socket). <tt>Plugin.start()</tt> may
be a reasonable place to do this work. It may also make sense to defer
until some other trigger (e.g., the use of a particular function or data
element).</dd>
<dt><b>Plug-in global data</b></dt>
<dd>Your <tt>Plugin</tt> class can continue to play this role. The main issue
is that <tt>Plugin</tt> objects are no longer globally accessible via a
system-managed list. In Eclipse 2.x you could discover any plug-in's <tt>Plugin</tt> object
via the plug-in registry. This is no longer possible. In most circumstances
this type of access is not required. <tt>Plugins</tt> accessed via the
registry are more typically used as generic <tt>Plugins</tt> rather than
calling domain-specific methods. The equivalent level of capability can
be had by accessing and manipulating the corresponding Bundle objects.</dd>
</dl>
<h4><a name="registries"></a>Registries and the plug-in model</h4>
<p>In the new runtime there is a separation between the information and structures
needed to execute a plug-in and that related to a plug-in's extensions and
extension points. The former is defined and managed by the OSGi framework specification.
The latter are Eclipse-specific concepts and are added by they Eclipse runtime
code. Accordingly, the original plug-in registy and related objects have been
split into OSGi <i>bundles</i> and the Eclipse <i>extension registry</i>. </p>
<p>The parts of <tt>IPluginRegistry</tt> dealing with execution specification
(e.g., <tt>IPluginDescriptor, ILibrary</tt>, <tt>IPrequisite</tt>) have been
deprecated and the remaining parts related to extensions and extension point
have been moved to <tt>IExtensionRegistry</tt>. Further, the so-called model
objects related to the plug-in registry as a whole are now deprecated. These
types were presented and instantiated by the runtime primarily to support tooling
such as PDE. Unfortunately, it was frequently the case that the level of information
needed exceeded the runtime's capabilities or interests (e.g., remembering
line numbers for plugin.xml elements) and in the end, the potential consumers
of the runtime's information had to maintain their own structures anyway.</p>
<p>In the new runtime we have re-evaluated the facilities provided by the runtime
and now provide only those which are either essential for runtime execution
or are extraordinarily difficult for others to do. As mentioned above, the
plug-in registry model objects have been deprecated as has the plug-in parsing
API. The new extensions registry maintains the essential extension-related
information. A new <i>state</i> (see <tt>org.eclipse.osgi.service.resolver.State</tt> and
friends) structure represents and allows the manipulation of the essential
execution-related information. </p>
<h3>NL fragment structure</h3>
<p>In Eclipse 3.0 the NL fragment structure has been updated to be more consistent.
Previously the translations for files like plugin.properties were assumed to
be inside of JARs supplied by fragments. Since the original files are found
in the root of the relevant host plug-in, a more consistent location would
have the translated files located in the root of the NL fragments. For example, </p>
<pre> org.eclipse.ui.workbench.nl/
fragment.xml
plugin_fr.properties
plugin_pt_BR.properties
...
nl1.jar</pre>
<p>Note here that the file nl1.jar previously would have contained the translations
for plugin.properties. These files are now at the root of the fragment and
the JAR contains translations of any translatable resources (i.e., files loaded
via the classloader) in the host plug-in. </p>
<p>Of course, the Eclipse 2.1 NL fragment structure is still supported for 2.1
host plug-ins running in Eclipse 3.0. You cannot however use a 2.1 NL fragment
on a 3.0 plug-in. The fragment must be updated to the new structure.</p>
<h3>API changes overview</h3>
<h4>org.eclipse.core.boot (package org.eclipse.core.boot)</h4>
<p>The entire org.eclipse.core.boot package has been deprecated. BootLoader has
been merged with <tt>org.eclipse.core.runtime.Platform</tt> since
it no longer made sense to have a split between boot and runtime. Note that
in fact, the org.eclipse.core.boot plug-in has been broken up and all its code
moved to either the new runtime or the compatibility layer. </p>
<p><tt>IPlatformConfiguration</tt> has
always been a type defined by and for the Eclipse Install/Update component.
With the reorganization of the runtime
we are able to repatriate this type to its rightful home. This class remains
largely unchanged and has been repackaged as <tt>org.eclipse.update.configurator.IPlatformConfiguration</tt>.
</p>
<p>IPlatformRunnable has been moved to org.eclipse.core.runtime.IPlatformRunnable. </p>
<h4>IExtension and IExtensionPoint (package org.eclipse.core.runtime)<br>
</h4>
<p>The <code>getDeclaringPlugin()</code> method (on both classes) gives an upward link
to the plug-in which declares the extension or extension-point (respectively).
The
new registry model separates the execution aspects of plug-ins from
the extension/extension-point aspects and no longer contains <tt>IPluginDescriptors</tt>.
Users of this API should consider the new method <tt>getParentIdentifier()</tt> found
on both <tt>IExtension</tt> and <tt>IExtensionPoint</tt>. </p>
<h4>ILibrary, IPluginDescriptor, IPluginRegistry and IPrerequisite (package org.eclipse.core.runtime)</h4>
<p> In the original runtime, the plug-in registry maintained a complete picture
of the runtime configuration. In Eclipse 3.0 this picture is split over the
OSGi framework and the extension registry. As such, these classes have been
deprecated. The deprecation notices contain details of how you should update
your code.</p>
<h4>Platform and Plugin (package org.eclipse.core.runtime)</h4>
<p>In the new runtime, <tt>Plugin</tt> objects are no longer managed
by the runtime and so cannot be accessed generically via the Platform. Similarly,
the plug-in registry no longer exists or gives access to plug-in descriptors.
There are however suitable replacement methods available and detailed in the
Javadoc of the deprecated methods in these classes.</p>
<h4>org.eclipse.core.runtime.model (package org.eclipse.core.runtime.model)</h4>
<p>All types in this package are now deprecated. See the discussion on <a href="#registries">registries</a> for
more information.</p>
<h4>IWorkspaceRunnable and IWorkspace.run (package org.eclipse.core.resources)</h4>
<p>Clients of the <tt>IWorkspace.run(IWorkspaceRunnable,IProgressMonitor)</tt>
method should revisit their uses of this method and consider using the richer
method <tt>IWorkspace.run(IWorkspaceRunnable,ISchedulingRule,int,IProgressMonitor)</tt>.
The old <tt>IWorkspace.run</tt> method acquires a lock on the entire workspace
for the duration of the <tt>IWorkspaceRunnable</tt>. This means that an
operation done with this method will never be able to run concurrently with
other operations that are changing the workspace. In Eclipse 3.0, many
long-running operations have been moved into background threads, so the
likelihood of conflicts between operations is greatly increased. If a modal
foreground operation is blocked by a long running background operation, the UI
becomes blocked until the background operation completes, or until one of the
operations is canceled.</p>
<p>The suggested solution is to switch all references to old <tt>IWorkspace.run</tt>
to use the new method with a scheduling rule parameter. The scheduling rule
should be the most fine-grained rule that encompasses the rules for all changes by that
operation. If the operation tries to modify resources outside of the scope
of the scheduling rule, a runtime exception will occur. The precise scheduling rule
required by a given workspace operation is not specified, and may change depending
on the installed repository provider on a given project. The factory
<code>IResourceRuleFactory</code> should be used to obtain the scheduling
rule for a resource-changing operation. If desired, a <tt>MultiRule</tt> can be used
to specify multiple resource rules, and the <tt>MultiRule.combine</tt> convenience
method can be used to combine rules from various resource-changing operations.</p>
<p>
If no locking is required, a scheduling rule of <tt>null</tt> can be used. This will
allow the runnable to modify all resources in the workspace, but will not prevent other
threads from also modifying the workspace concurrently. For simple changes to
the workspace this is often the easiest and most concurrency-friendly solution.
</p>
<h4>IWorkbenchPage (package org.eclipse.ui)</h4>
<ul>
<li>The constant EDITOR_ID_ATTR is now deprecated. This is an IMarker
attribute name that specifies the preferred editor id to open the IMarker
resource with. This constant in now on org.eclipse.ui.ide.IDE class.</li>
</ul>
<h4>IEditorDescriptor (package org.eclipse.ui)</h4>
<ul>
<li>There are new API methods to determine whether the editor will open
internally to the workbench page (isInternal), in-place to the workbench
window (isOpenInPlace), or externally to the workbench (isExternal). While
this is not a breaking change, it is a good opportunity for clients that are
illegally down-casting IEditorDescriptor to
org.eclipse.ui.internal.model.EditorDescriptor to call isInternal to bring
there code back into line.</li>
</ul>
<h4>ISharedImages (package org.eclipse.ui)</h4>
<ul>
<li>The following fields were removed (deprecated) from this interface because
they were IDE-specific:
<ul>
<li>String IMG_OBJ_PROJECT</li>
<li>String IMG_OBJ_PROJECT_CLOSED</li>
<li>String IMG_OPEN_MARKER</li>
<li>String IMG_OBJS_TASK_TSK</li>
<li>String IMG_OBJS_BKMRK_TSK</li>
</ul>
</li>
<li>Existing clients should instead use the fields of the same names declared
on IDE.SharedImages in the org.eclipse.ui.ide package of the
org.eclipse.ui.ide plug-in.</li>
</ul>
<h4>IWorkbenchActionConstants (package org.eclipse.ui)</h4>
<ul>
<li>The following fields were removed (deprecated) from this interface; they
are subsumed by the new ActionFactory class:
<ul>
<li>String ABOUT</li>
<li>String BACK</li>
<li>String CLOSE</li>
<li>String CLOSE_ALL</li>
<li>String COPY</li>
<li>String CUT</li>
<li>String DELETE</li>
<li>String EXPORT</li>
<li>String FIND</li>
<li>String FORWARD</li>
<li>String IMPORT</li>
<li>String MOVE</li>
<li>String NEW</li>
<li>String NEXT</li>
<li>String PASTE</li>
<li>String PREVIOUS</li>
<li>String PRINT</li>
<li>String PROPERTIES</li>
<li>String QUIT</li>
<li>String REDO</li>
<li>String REFRESH</li>
<li>String RENAME</li>
<li>String REVERT</li>
<li>String SAVE</li>
<li>String SAVE_ALL</li>
<li>String SAVE_AS</li>
<li>String SELECT_ALL</li>
<li>String UNDO</li>
<li>String UP</li>
</ul>
</li>
<li>Clients should instead call getID() on the fields of the same names
declared on ActionFactory in the org.eclipse.ui.actions package (org.eclipse.ui
plug-in). For example, change IWorkbenchActionConstants.CUT to
ActionFactory.CUT.getId().</li>
<li>The following fields were removed (deprecated) from this interface because
they were IDE-specific.
<ul>
<li>String ADD_TASK</li>
<li>String BOOKMARK</li>
<li>String BUILD</li>
<li>String BUILD_PROJECT</li>
<li>String CLOSE_PROJECT</li>
<li>String FIND</li>
<li>String OPEN_PROJECT</li>
<li>String REBUILD_ALL</li>
<li>String REBUILD_PROJECT</li>
</ul>
</li>
<li>Clients should instead call getID() on the fields of the same names
declared on IDEActionFactory in the org.eclipse.ui.ide package (org.eclipse.ui.ide
plug-in). For example, change IWorkbenchActionConstants.BUILD to
IDEActionFactory.BUILD.getId().</li>
</ul>
<h4>IWorkbenchPreferenceConstants (package org.eclipse.ui)</h4>
<ul>
<li>The following fields were removed (deprecated) from this interface because
they were IDE-specific:
<ul>
<li>String PROJECT_OPEN_NEW_PERSPECTIVE</li>
</ul>
</li>
<li>Clients should instead use the fields of the same names declared on
IDE.Preferences in the org.eclipse.ui.ide package.</li>
</ul>
<h4>IExportWizard (package org.eclipse.ui)</h4>
<ul>
<li>Prior to 3.0, the selection passed to IWorkbenchWizard.init(IWorkbench,
IStructuredSelection) for an export wizard was preprocessed. If any of the
selections were IResources, or adaptable to IResource, then the selection
consisted only of these resources. In 3.0, the generic export wizard does
not do any preprocessing. </li>
<li>The selection passed to the wizard is generally used to prime the
particular wizard page with contextually appropriate values.</li>
<li>Client that implement IExportWizard and requires this resource-specific
selection transformation should add the following to their init(IWorkbench,
IStructuredSelection selection) method to computer <code>filteredSelection</code>
from <code>selection</code>:
<ul>
<li><code>IStructuredSelection filteredSelection = selection;<br>
List selectedResources = IDE.computeSelectedResources(currentSelection);<br>
if (!selectedResources.isEmpty()) {<br>
filteredSelection = new
StructuredSelection(selectedResources);<br>
}</code></li>
</ul>
</li>
</ul>
<h4>IImportWizard (package org.eclipse.ui)</h4>
<ul>
<li>Prior to 3.0, the selection passed to IWorkbenchWizard.init(IWorkbench,
IStructuredSelection) for an import wizard was preprocessed. If any of the
selections were IResources, or adaptable to IResource, then the selection
consisted only of these resources. In 3.0, the generic import wizard does
not do any preprocessing. </li>
<li>The selection passed to the wizard is generally used to prime the
particular wizard page with contextually appropriate values.</li>
<li>Client that implement IImportWizard and requires this resource-specific
selection transformation should add the following to their init(IWorkbench,
IStructuredSelection selection) method to compute a filtered selection from
the selection passed in:
<ul>
<li><code>IStructuredSelection filteredSelection = selection;<br>
List selectedResources = IDE.computeSelectedResources(currentSelection);<br>
if (!selectedResources.isEmpty()) {<br>
filteredSelection = new
StructuredSelection(selectedResources);<br>
}</code></li>
</ul>
</li>
</ul>
<h4>INewWizard (package org.eclipse.ui)</h4>
<ul>
<li>Prior to 3.0, the selection passed to IWorkbenchWizard.init(IWorkbench,
IStructuredSelection) for a new wizard was preprocessed. If there was no
structured selection at the time the wizard was invoked, but the active
workbench window had an active editor open on an IFile, then the selection
passed in would consist of that IFile. In 3.0, the generic new wizard does
not do any preprocessing, and an empty selection will be passed when there
is no structured selection.</li>
<li>The selection passed to the wizard is generally used to prime the
particular wizard page with contextually appropriate values.</li>
<li>Client that implement INewWizard and requires this capability should add
the following to their init(IWorkbench, IStructuredSelection selection)
method to compute a selection from the active editor's input:
<pre>if (selection.isEmpty()) {
IWorkbenchWindow window = PlatformUI.getWorkbench().getActiveWorkbenchWindow();
if (window != null) {
IWorkbenchPart part = window.getPartService().getActivePart();
if (part instanceof IEditorPart) {
IEditorInput input = ((IEditorPart) part).getEditorInput();
if (input instanceof IFileEditorInput) {
selection = new StructuredSelection(((IFileEditorInput) input).getFile());
}
}
}
}</pre>
</li>
</ul>
<h4>WorkbenchHelp (package org.eclipse.ui.help)</h4>
<ul>
<li>The following WorkbenchHelp method was removed (deprecated) from this
class because its result (IHelp) was removed (deprecated):
<ul>
<li>public static IHelp getHelpSupport()</li>
</ul>
</li>
<li>Clients that called this method to obtain an IHelp should instead call the
static methods on HelpSystem or WorkbenchHelp.</li>
</ul>
<h4>IHelp (package org.eclipse.help)</h4>
<ul>
<li>This interface has been removed (deprecated). WorkbenchHelp.getHelpsupport()
was the only way to get hold of an IHelp object. This method has also been
removed (deprecated).</li>
<li>The following IHelp methods now appear as static methods on a new
HelpSystem class in the same package:
<ul>
<li>public IToc[] getTocs()</li>
<li>public IContext getContext(String contextId)</li>
</ul>
</li>
<li>The rest of the IHelp methods now appear as static method on WorkbenchHelp.</li>
<li>This interface was formerly mentioned in the contract for the
org.eclipse.help.support extension point. This extension point has been
renamed "org.eclipse.ui.helpSupport", and the contract simplified
so that the implementer only needs supply the display methods. For these
purposes, IHelp has been replaced by AbstractHelpUI (in the
org.eclipse.ui.help package).</li>
<li>There should be no clients implementing this interface beyond the Platform
which supplied the sole implementation of this interface.</li>
</ul>
<h4>ITextEditorActionConstants (package org.eclipse.ui.texteditor)</h4>
<ul>
<li>This interface additionally includes newly defined constants that redefine
deprecated constants inherited from org.eclipse.ui.IWorkbenchActionConstants.
This change allows clients to free their code from deprecation warnings. The
constants ADD_TASK and BOOKMARK have not been redefined as they are IDE
specific. When using these two constants in your code, please follow the
instructions given in the deprecation message.</li>
</ul>
<h4>IAbstractTextEditorHelpContextIds (package org.eclipse.ui.texteditor)</h4>
<ul>
<li>BOOKMARK_ACTION and ADD_TASK_ACTION have been deprecated because they are
IDE specific. Use the constants defined in
org.eclipse.ui.editors.text.ITextEditorHelpContextIds instead.</li>
</ul>
<h4>BasicTextEditorActionContributor (package org.eclipse.ui.texteditor)</h4>
<ul>
<li>BasicTextEditorActionContributor no longer assigns any editor action as
global action for org.eclipse.ui.IWorkbenchActionConstants.ADD_TASK and
org.eclipse.ui.IWorkbenchActionConstants.BOOKMARK because these actions are
IDE specific. This is now done by the
org.eclipse.ui.editors.text.TextEditorActionContributor. If your editors are
not configured to used TextEditorActionContributor but uses a contributor
that is a subclass of BasicTextEditorActionContributor, this contributor has
to be extended to also assign global action handlers for ADD_TASK and
BOOKMARK. This can be done by adding the following lines to the
setActiveEditor method of the editor action contributor:</li>
<li>
<pre> IActionBars actionBars= getActionBars();
if (actionBars != null) {
actionBars.setGlobalActionHandler(IDEActionFactory.ADD_TASK.getId(), getAction(textEditor, IDEActionFactory.ADD_TASK.getId()));
actionBars.setGlobalActionHandler(IDEActionFactory.BOOKMARK.getId(), getAction(textEditor, IDEActionFactory.BOOKMARK.getId()));
}</pre>
</li>
</ul>
<h4>TextEditorActionContributor (package org.eclipse.ui.editors.text)</h4>
<ul>
<li>TextEditorActionContributor assigns global action handlers for
IWorkbenchActionConstants.ADD_TASK (now IDEActionFactory.ADD_TASK.getId())
and IWorkbenchActionConstants.BOOKMARK (now IDEActionFactory.BOOKMARK.getId()).
These action handlers have previously been registered by
BasicTextEditorActionContributor. See migration notes for
BasicTextEditorActionContributor.</li>
</ul>
<h4>annotationTypes extension point (plug-in org.eclipse.ui.editors)</h4>
<p>
There is now the explicit notion of an annotation type. See Annotation.getType() and Annotation.setType().
The type of an annotation can change over it's lifetime. A new extension point has been added for the declaration
of annotation types: "org.eclipse.ui.editors.annotationTypes". An annotation type has a name and can be declared
as being a subtype of another declared annotation type. An annotation type declaration may also use the attributes
"markerType" and "markerSeverity" in order to specify that markers of a given type and a given severity should be
represented in text editors as annotations of a particular annotation type. The attributes "markerType" and
"markerSeverity" in the "org.eclipse.ui.editors.markerAnnotationSpecification" should no longer be used. Marker
annotation specifications are thus becoming independent from markers and the name thus misleading. However, the
name is kept in order to ensure backward compatibility.
</p><p>
Instances of subclasses of AbstractMarkerAnnotationModel automatically detect and set the correct annotation
types for annotations they create from markers. In order to programmatically retrieve the annotation type for
a given marker or a given pair of markerType and markerSeverity use org.eclipse.ui.texteditor.AnnotationTypeLookup.
</p><p>
Access to the hierarchy of annotation types is provided by IAnnotationAccessExtension. For a given annotation type
you can get the chain of super types and check whether an annotation type is a subtype of another annotation type.
DefaultMarkerAnnotationAccess implements this interface.
</p>
<h4>markerAnnotationSpecification extension point (plug-in org.eclipse.ui.editors)</h4>
<p>
The annotation type is the key with which to find the associated marker annotation specification. As annotation
types can extend other annotation types, there is an implicit relation between marker annotation specifications
as well. Therefore a marker annotation specification for a given annotation type is completed by the marker
annotation specifications given for the super types of the given annotation type. Therefore, marker annotation
specification do not have to be complete as this was required before. Marker annotation specifications are
retrieved by AnnotationPreferences. By using org.eclipse.ui.texteditor.AnnotationPreferenceLookup, you can retrieve
an annotation preference for a given annotation type that transparently performs the completion of the preference
along the annotation super type chain.
</p><p>
Marker annotation specification has been extended with three additional attributes in order to allow the definition
of custom appearances of a given annotation type in the vertical ruler. These attributes are: "icon", "symbolicIcon",
and "annotationImageProvider". The value for "icon" is the path to a file containing the icon image. The value of
"symbolicIcon" can be one of "error", "warning", "info", "task", "bookmark". The attribute "symbolicIcon" is used
to tell the platform that annotation should be depicted with the same images that are used by the platform to
present errors, warnings, infos, tasks, and bookmarks respectively. The value of "annotationImageProvider" is a
class implementing org.eclipse.ui.texteditor.IAnnotationImageProvider that allows for a full custom annotation
presentation.
</p><p>
The vertical ruler uses it's associated IAnnotationAccess/IAnnotationAccessExtension to draw annotations.
The vertical ruler does not call Annotation.paint any longer. In general, Annotations are no longer supposed
to draw themselves. The "paint" and "getLayer" methods have been deprecated in order to make annotation eventually
UI independent. DefaultMarkerAnnotationAccess serves as default implementation of IAnnotationAccess/IAnnotationAccessExtension.
DefaultMarkerAnnotationAccess implements the following strategy for painting annotations: If an annotation implements
IAnnotationPresentation, IAnnotationPresentation.paint is called. If not, the annotation image provider is looked up
in the annotation preference. The annotation image provider is only available if specified and if the plug-in defining
the enclosing marker annotation specification has already been loaded. If there is an annotation image provider, the
call is forwarded to it. If not, the specified "icon" is looked up. "symbolicIcon" is used as the final fallback. For
drawing annotations, the annotation presentation layer is relevant. DefaultMarkerAnnotationAccess looks up the presentation
layer using the following strategy: If the annotation preference specifies a presentation layer, the specified layer is
used. If there is no layer and the annotation implements IAnnotationPresentation, IAnnotationPresentation.getLayer is used
otherwise the default presentation layer (which is 0) is returned.
</p>
<h4>Migration to annotationTypes extension point (plug-in org.eclipse.ui.editors)</h4>
<p>
The following annotation types are declared by the org.eclipse.ui.editors plug-in:
</p>
<pre>
<extension point="org.eclipse.ui.editors.annotationTypes">
<type
name="org.eclipse.ui.workbench.texteditor.error"
markerType="org.eclipse.core.resources.problemmarker"
markerSeverity="2">
</type>
<type
name="org.eclipse.ui.workbench.texteditor.warning"
markerType="org.eclipse.core.resources.problemmarker"
markerSeverity="1">
</type>
<type
name="org.eclipse.ui.workbench.texteditor.info"
markerType="org.eclipse.core.resources.problemmarker"
markerSeverity="0">
</type>
<type
name="org.eclipse.ui.workbench.texteditor.task"
markerType="org.eclipse.core.resources.taskmarker">
</type>
<type
name="org.eclipse.ui.workbench.texteditor.bookmark"
markerType="org.eclipse.core.resources.bookmark">
</type>
</extension>
</pre>
<p>
The defined markerAnnotationSpecification extension no longer provide "markerType" and "markerSeverity"
attributes. They define the "symbolicIcon" attribute with the according value. Thus, MarkerAnnotation.paint
and MarkerAnnotation.getLayer are not called any longer, i.e. overriding these methods does not have
any effect. Affected clients should implement IAnnotationPresentation.
</p>
<h4>ILaunchConfigurationType (package org.eclipse.debug.core)</h4>
<p>With the introduction of extensible launch modes in 3.0, more than one launch
delegate can exist for a launch configuration type. Releases prior to 3.0 only
supported one launch delegate per launch configuration type. The method <code>ILaunchConfigurationType.getDelegate()</code>
is now deprecated. The method <code>getDelegate(String mode)</code> should be
used in its place to retrieve the launch delegate for a specific launch mode.
The deprecated method has been changed to return the launch delegate for the <code>run</code>
mode.</p>
<h4>ILaunchConfigurationTab and ILaunchConfigurationTabGroup (package
org.eclipse.debug.ui)</h4>
<p>Launch tab groups and launch tabs are no longer notified when a launch
completes. The method <code>launched(ILaunch)</code> in the interfaces <code>ILaunchConfigurationTab</code>
and <code>ILaunchConfigurationTabGroup</code> has been deprecated and is no
longer called. Relying on this method for launch function was always
problematic, since tabs only exist when launching is performed from the launch
dialog. Also, with the introduction of background launching, this method can no
longer be called, as the launch dialog is be closed before the resulting launch
object exists.</p>
<h4>ILaunchConfigurationTab and AbstractLaunchConfigurationTab (package
org.eclipse.debug.ui)</h4>
<p>Two methods have been added to the <code>ILaunchConfigurationTab</code>
interface - activated and deactivated. These new life cycle methods are called
when a tab is entered and exited respectively. Existing implementations of <code>ILaunchConfigurationTab</code>
that subclass the abstract class provided by the debug plug-in (<code>AbstractLaunchConfigurationTab</code>)
are binary compatible since the methods are implemented in the abstract class.</p>
<p>In prior releases, a tab was sent the message <code>initializeFrom</code>
when it was activated, and <code>performApply</code> when it was deactivated. In
this way, the launch configuration tab framework provided inter-tab
communication via a launch configuration (by updating the configuration with
current attribute values when a tab is exited, and updating the newly entered
tab). However, since many tabs do not perform inter-tab communication, this can
be inefficient. As well, there was no way to distinguish between a tab being
activated, and a tab displaying a selected launch configuration for the first
time. The newly added methods allow tabs to distinguish between activation and
initialization, and deactivation and saving current values.</p>
<p>The default implementation of <code>activated</code>, provided by the
abstract tab, calls <code>initializeFrom</code>. And, the default implementation
of <code>deactivated</code> calls <code>performApply</code>. Tabs wishing to
take advantage of the new API should override these methods as required.
Generally, for tabs that do not perform inter-tab communication, the recommended
approach is to re-implement these methods to do nothing.</p>
<h4>launchConfigurationTabGroup extension point Type (package
org.eclipse.debug.ui)</h4>
<p>In prior releases, perspective switching was specified on a launch
configuration, via the launch configuration attributes <code>ATTR_TARGET_DEBUG_PERSPECTIVE</code>
and <code>ATTR_TARGET_RUN_PERSPECTIVE</code>. With the addition of extensible
launch modes in 3.0, this approach no longer scales. Perspective switching is
now specified on launch configuration type basis, per launch mode that a launch
configuration type supports. API has been added to <code>DebugUITools</code> to
set and get the perspective associated with a launch configuration type for a
specific launch mode.</p>
<p>An additional, optional, <code>launchMode</code> element has been added to
the <code>launchConfigurationTabGroup</code> extension point, allowing a
contributed tab group to specify a default perspective for a launch
configuration type and mode.</p>
<p>From the Eclipse user interface, users can edit the perspective associated
with a launch configuration type by opening the launch configuration dialog, and
selecting a launch configuration type node in the tree (rather than an
individual configuration). A tab is displayed allowing the user to set a
perspective with each supported launch mode.</p>
<h4>[JDT only] IVMRunner (package org.eclipse.jdt.launching)</h4>
<p>Two methods have been added to the <code>VMRunnerConfiguration</code> class
to support the setting and retrieving of environment variables. Implementors of <code>IVMRunner</code>
should call <code>VMRunnerConfiguration.getEnvironment()</code> and pass that
environment into the executed JVM. Clients who use <code>DebugPlugin.exec(String[]
cmdLine, File workingDirectory)</code> can do this by calling <code>DebugPlugin.exec(String[]
cmdLine, File workingDirectory, String[] envp)</code> instead. Simply passing in
the result from <code>getEnvironment()</code> is sufficient.</p>
<h4>[JDT only] VMRunnerConfiguration and Bootstrap Classes (package
org.eclipse.jdt.launching)</h4>
<p>In prior releases, the <code>VMRunnerConfiguration</code> had one attribute
to describe a boot path. The attribute is a collection of <code>Strings</code>
to be specified in the -<code>Xbootclasspath</code> argument. Three new
attributes have been added to the VMRunnerConfiguration to support JVMs that
allow for prepending and appending to the boot path. The new methods/attributes
added are:</p>
<ul>
<li><code>getPrependBootClassPath()</code> - returns a collection of entries
to be prepended to the boot path (the <code>-Xbootclasspath/p</code>
argument)</li>
<li><code>getMainBootClassPath()</code> - returns a collection of entries to
be placed on the boot path (the <code>-Xbootclasspath</code> argument)</li>
<li><code>getAppendBootClassPath()</code> - returns a collection of entries to
be appended to the boot path (the <code>-Xbootclasspath/a</code> argument)</li>
</ul>
<p>The old attribute,<code> getBootClassPath()</code>, still exists and contains
a complete path equivalent to that of the three new attributes. However, <code>VMRunners</code>
that support the new boot path options should take advantage of the new
attributes.</p>
<h4>[JDT only] Improved support for working copies (package org.eclipse.jdt.core)</h4>
<p>The Java model working copy facility has been reworked in 3.0 to provide
greatly increased functionality. Prior to 3.0, the Java model allowed creation
of individual working copies of compilation units. Changes could be made to the
working copy and later committed. There was support for limited analysis of a
working copy in the context of the rest of the Java model. However, there was no
way these these analyses could ever take into account more than one of the
working copies at a time.</p>
<p>The changes in 3.0 make it possible to create and manage sets of working
copies of compilation units, and to perform analyses in the presence of all
working copies in a set. For example, it is now possible for a client like JDT
refactoring to create working copies for one or more compilation units that it
is considering modifying and then to resolve type references between the working
copies. Formerly this was only possible after the changes to the compilation
unit working copies had been committed.</p>
<p>The Java model API changes in 2 ways to add this improved support:</p>
<p>(1) The functionality formerly found on <code>IWorkingCopy</code> and
inherited by <code>ICompilationUnit</code> has been consolidated into <code>ICompilationUnit</code>.
The <code>IWorkingCopy</code> interface was only used in this one place, and was
gratuitously more general that in needed to be. This change simplifies the API. <code>IWorkingCopy</code>
has been deprecated. Other places in the API where <code>IWorkingCopy</code> is
used as a parameter or result type have been deprecated as well; the replacement
API methods mention <code>ICompilationUnit</code> instead of <code>IWorkingCopy</code>.</p>
<p>(2) The interface <code>IBufferFactory</code> has been replaced by <code>WorkingCopyOwner</code>.
The improved support for working copies requires that there be an object to own
the working copies. Although <code>IBufferFactory</code> is in the right place,
the name does not adequately convey how the new working copy mechanism works. <code>WorkingCopyOwner</code>
is much more suggestive. In addition, <code>WorkingCopyOwner</code> is declared
as an abstract class, rather than as an interface, to allow the notion of
working copy owner to evolve in the future. The one method on <code>IBufferFactory</code>
moves to <code>WorkingCopyOwner</code> unaffected. <code>WorkingCopyOwner</code>
does not implement <code>IBufferFactory</code> to make it clear that <code>IBufferFactory</code>
is a thing of the past. <code>IBufferFactory</code> has been deprecated. Other
places in the API where <code>IBufferFactory</code> appears as a parameter or
result type have been deprecated as well; the replacement API methods mention <code>WorkingCopyOwner</code>
instead of <code>IBufferFactory</code>.</p>
<p>These changes do not break binary compatibility.</p>
<p>When migrating, all references to the type <code>IWorkingCopy</code> should
instead reference <code>ICompilationUnit</code>. The sole implementation of <code>IWorkingCopy</code>
implements <code>ICompilationUnit</code> as well, meaning objects of type <code>IWorkingCopy</code>
can be safely cast to <code>ICompilationUnit</code>.</p>
<p>A class that implements <code>IBufferFactory</code> will need to replaced by
a subclass of <code>WorkingCopyOwner</code>. Although <code>WorkingCopyOwner</code>
does not implement <code>IBufferFactory</code> itself, it would be possible to
declare the subclass of <code>WorkingCopyOwner</code> that implements <code>IBufferFactory</code>
thereby creating a bridge between old and new (<code>IBufferFactory</code>
declares <code>createBuffer(IOpenable)</code> whereas <code>WorkingCopyOwner</code>
declares <code>createBuffer(ICompilationUnit)</code>; <code>ICompilationUnit</code>
extends <code>IOpenable</code>).</p>
<p>Because the changes involving <code>IWorkingCopy</code> and <code>IBufferFactory</code>
are interwined, we recommend dealing with both at the same time. The details of
the deprecations are as follows:</p>
<ul>
<li><code>IWorkingCopy</code> (package <code>org.eclipse.jdt.core</code>)
<ul>
<li><code>public void commit(boolean, IProgressMonitor)</code> has been
deprecated.
<ul>
<li>The equivalent functionality is now provided on <code>ICompilationUnit</code>
directly:
<ul>
<li><code>public void commitWorkingCopy(boolean, IProgressMonitor)</code></li>
</ul>
</li>
<li>Rewrite <code>wc.commit(b,monitor)</code> as <code>((ICompilationUnit)
wc).commitWorkingCopy(b,monitor)</code></li>
</ul>
</li>
<li><code>public void destroy()</code> has been deprecated.
<ul>
<li>The equivalent functionality is now provided on <code>ICompilationUnit</code>
directly:
<ul>
<li><code>public void discardWorkingCopy(boolean, IProgressMonitor)</code></li>
</ul>
</li>
<li>Rewrite <code>wc.destroy()</code> as <code>((ICompilationUnit)
wc).discardWorkingCopy()</code></li>
</ul>
</li>
<li><code>public IJavaElement findSharedWorkingCopy(IBufferFactory)</code>
has been deprecated.
<ul>
<li>The equivalent functionality is now provided on <code>ICompilationUnit</code>
directly:
<ul>
<li><code>public ICompilationUnit findWorkingCopy(WorkingCopyOwner)</code></li>
</ul>
</li>
<li>Note: <code>WorkingCopyOwner</code> substitutes for <code>IBufferFactory.</code></li>
</ul>
</li>
<li><code>public IJavaElement getOriginal(IJavaElement)</code> has been
deprecated.
<ul>
<li>The equivalent functionality is now provided on <code>IJavaElement</code>:
<ul>
<li><code>public IJavaElement getPrimaryElement()</code></li>
</ul>
</li>
</ul>
<ul>
<li>Rewrite <code>wc.getOriginal(elt)</code> as <code>elt.getPrimaryElement()</code></li>
<li>Note: Unlike <code>IWorkingCopy.getOriginal</code>, <code>IJavaElement.getPrimaryElement</code>
does not return <code>null</code> if the receiver is not a working
copy.</li>
</ul>
</li>
<li><code>public IJavaElement getOriginalElement()</code> has been
deprecated.
<ul>
<li>The equivalent functionality is now provided on <code>ICompilationUnit</code>
directly:
<ul>
<li><code>public ICompilationUnit getPrimary()</code></li>
</ul>
</li>
<li>Rewrite <code>wc.getOriginalElement()</code> as <code>((ICompilationUnit)
wc).getPrimary()</code></li>
<li>Note: Unlike <code>IWorkingCopy.getOriginalElement</code>, <code>IWorkingCopy.getPrimary</code>
does not return <code>null</code> if the receiver is not a working
copy.</li>
</ul>
</li>
<li><code>public IJavaElement[] findElements(IJavaElement)</code> has been
deprecated.
<ul>
<li>The method is now declared on <code>ICompilationUnit</code>
directly.</li>
<li>Rewrite <code>wc.findElements(elts)</code> as <code>((ICompilationUnit)
wc).findElements(elts)</code></li>
</ul>
</li>
<li><code>public IType findPrimaryType()</code> has been deprecated.
<ul>
<li>The method is now declared on <code>ICompilationUnit</code>
directly.</li>
<li>Rewrite <code>wc.findPrimaryType()</code> as <code>((ICompilationUnit)
wc).findPrimaryType()</code></li>
</ul>
</li>
<li><code>public IJavaElement getSharedWorkingCopy(IProgressMonitor,
IBufferFactory, IProblemRequestor)</code> has been deprecated.
<ul>
<li>The equivalent functionality is now provided on <code>ICompilationUnit</code>
directly:
<ul>
<li><code>public ICompilationUnit getWorkingCopy(WorkingCopyOwner,
IProblemRequestor, IProgressMonitor)</code></li>
</ul>
</li>
<li>Note: the parameter order has changed, and <code>WorkingCopyOwner</code>
substitutes for <code>IBufferFactory.</code></li>
</ul>
</li>
<li><code>public IJavaElement getWorkingCopy()</code> has been deprecated.
<ul>
<li>The equivalent functionality is now provided on <code>ICompilationUnit</code>
directly:
<ul>
<li><code>public ICompilationUnit getWorkingCopy(IProgressMonitor)</code></li>
</ul>
</li>
<li>Rewrite <code>wc.getWorkingCopy() </code>as <code>((ICompilationUnit)
wc).getWorkingCopy(null)</code></li>
</ul>
</li>
<li><code>public IJavaElement getWorkingCopy(IProgressMonitor,
IBufferFactory, IProblemRequestor)</code> has been deprecated.
<ul>
<li>The equivalent functionality is now provided on <code>ICompilationUnit</code>
directly:
<ul>
<li><code>public ICompilationUnit getWorkingCopy(WorkingCopyOwner,
IProblemRequestor, IProgressMonitor)</code></li>
</ul>
</li>
<li>Note: the parameter order has changed, and <code>WorkingCopyOwner</code>
substitutes for <code>IBufferFactory.</code></li>
</ul>
</li>
<li><code>public boolean isBasedOn(IResource)</code> has been deprecated.
<ul>
<li>The equivalent functionality is now provided on <code>ICompilationUnit</code>
directly:
<ul>
<li><code>public boolean hasResourceChanged()</code></li>
</ul>
</li>
<li>Rewrite <code>wc.isBasesOn(res)</code> as <code>((ICompilationUnit)
wc).hasResourceChanged()</code></li>
</ul>
</li>
<li><code>public boolean isWorkingCopy()</code> has been deprecated.
<ul>
<li>The method is now declared on <code>ICompilationUnit</code>
directly.</li>
<li>Rewrite <code>wc.isWorkingCopy()</code> as <code>((ICompilationUnit)
wc).isWorkingCopy()</code></li>
</ul>
</li>
<li><code>public IMarker[] reconcile()</code> has been deprecated.
<ul>
<li>The equivalent functionality is now provided on <code>ICompilationUnit</code>
directly:
<ul>
<li><code>public void reconcile(boolean,IProgressMonitor)</code></li>
</ul>
</li>
<li>Rewrite <code>wc.reconcile()</code> as <code>((ICompilationUnit)
wc).reconcile(false, null)</code></li>
<li>Note: The former method always returned <code>null</code>; the
replacement method does not return a result.</li>
</ul>
</li>
<li><code>public void reconcile(boolean, IProgressMonitor)</code> has been
deprecated.
<ul>
<li>The method is now declared on <code>ICompilationUnit</code>
directly.</li>
<li>Rewrite <code>wc.reconcile(b,monitor)</code> as <code>((ICompilationUnit)
wc).reconcile(b.monitor)</code></li>
</ul>
</li>
<li><code>public void restore()</code> has been deprecated.
<ul>
<li>The method is now declared on <code>ICompilationUnit</code>
directly.</li>
<li>Rewrite <code>wc.restore()</code> as <code>((ICompilationUnit)
wc).restore()</code></li>
</ul>
</li>
</ul>
</li>
<li><code>IType</code> (package <code>org.eclipse.jdt.core</code>)
<ul>
<li><code>public ITypeHierarchy newSupertypeHierarchy(IWorkingCopy[],
IProgressMonitor)</code> has been deprecated.
<ul>
<li>The replacement method is provided on the same class:
<ul>
<li><code>public ITypeHierarchy newSupertypeHierarchy(c,
IProgressMonitor)</code></li>
</ul>
</li>
<li>Note: The Java language rules for array types preclude casting <code>IWorkingCopy[]</code>
to <code>ICompilationUnit[]</code>.</li>
</ul>
</li>
<li><code>public ITypeHierarchy newTypeHierarchy(IWorkingCopy[],
IProgressMonitor)</code> has been deprecated.
<ul>
<li>The replacement method is provided on the same class:
<ul>
<li><code>public ITypeHierarchy newTypeHierarchy(ICompilationUnit[],
IProgressMonitor)</code></li>
</ul>
</li>
<li>Note: The Java language rules for array types preclude casting <code>IWorkingCopy[]</code>
to <code>ICompilationUnit[]</code>.</li>
</ul>
</li>
</ul>
</li>
<li><code>IClassFile</code> (package <code>org.eclipse.jdt.core</code>)
<ul>
<li><code>public IJavaElement getWorkingCopy(IProgressMonitor,
IBufferFactory)</code> has been deprecated.
<ul>
<li>The replacement method is provided on the same class:
<ul>
<li><code>public ICompilationUnit getWorkingCopy(WorkingCopyOwner,
IProgressMonitor)</code></li>
</ul>
</li>
<li>Note: the parameter order has changed, and <code>WorkingCopyOwner</code>
substitutes for <code>IBufferFactory.</code></li>
</ul>
</li>
</ul>
</li>
<li><code>JavaCore</code> (package <code>org.eclipse.jdt.core</code>)
<ul>
<li><code>public IWorkingCopy[] getSharedWorkingCopies(IBufferFactory)</code>
has been deprecated.
<ul>
<li>The replacement method is provided on the same class:
<ul>
<li><code>public ICompilationUnit[]
getWorkingCopies(WorkingCopyOwner)</code></li>
</ul>
</li>
<li>Note: <code>WorkingCopyOwner</code> substitutes for <code>IBufferFactory.</code></li>
<li>Note: The Java language rules for array types preclude casting <code>ICompilationUnit[]</code>
to <code>IWorkingCopy[]</code>.</li>
</ul>
</li>
</ul>
</li>
<li><code>SearchEngine</code> (package <code>org.eclipse.jdt.core.search</code>)
<ul>
<li><code>public SearchEngine(IWorkingCopy[])</code> has been deprecated.
<ul>
<li>The replacement constructor is provided on the same class:
<ul>
<li><code>public SearchEngine(ICompilationUnit[])</code></li>
</ul>
</li>
<li>Note: The Java language rules for array types preclude casting <code>IWorkingCopy[]</code>
to <code>ICompilationUnit[]</code>.</li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Restructuring of org.eclipse.help plug-in</h4>
<p>The org.eclipse.help plug-in, which used to hold APIs and extension points
for contributing to and extending help system, as well as displaying help, now
contains just APIs and extension points for contributing and accessing help
resources. A portion of default help UI implementation contained in that plug-in
has been moved to a new plug-in org.eclipse.help.base together with APIs for
extending the implementation. The APIs and extension point for contributing Help
UI and displaying help have been moved to org.eclipse.ui plug-in. This
restructuring allows applications greater flexibility with regard to the help
system; the new structure allows applications based on the generic workbench to
provide their own Help UI and/or Help implementation, or to omit the help system
entirely.</p>
<p>Because the extension points and API packages affected are intended only for
use by the help system itself, it is unlikely that existing plug-ins are
affected by this change. They are included here only for the sake of
completeness:</p>
<ul>
<li>API packages org.eclipse.ui.help.browser and
org.eclipse.ui.help.standalone, formerly provided by the org.eclipse.help
plug-in, have been moved to the org.eclipse.help.base plug-in.</li>
<li>Extension points org.eclipse.help.browser, org.eclipse.help.luceneAnalyzer,
and org.eclipse.help.webapp, formerly defined by the org.eclipse.help
plug-in, have been moved to the org.eclipse.help.base plug-in, with a
corresponding change in extension point id.</li>
<li>Extension point org.eclipse.help.support has been replaced by the
org.eclipse.ui.helpSupport extension point. The contract for this extension
point changed as well (see entry for IHelp).</li>
</ul>
<h4>New Search UI API</h4>
<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.
</P>
<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>
<P>Default implementations for <CODE>ISearchResult</CODE> and <CODE>ISearchResultPage</CODE> are provided in the package<CODE>
org.eclipse.search.ui.text</CODE>.</P>
<h4>null messages in MessageBox and DirectoryDialog (package
org.eclipse.swt.widgets)</h4>
<p>Prior to 3.0, calling SWT's DirectoryDialog.setMessage(String string) or
MessageBox.setMessage(String string) with a null value for string would result
in a dialog with no text in the title. This behavior was unspecified (passing
null has never been permitted) and creates problems with getMessage which is not
permitted to return null. In 3.0, passing null now results in an
IllegalArgumentException exception being thrown, and the specifications have
been changed to state this, bringing it into line with the method on their
superclass Dialog.setMessage. If you use Dialog.setMessage, ensure that that the
string passed in is never null. Simply pass an empty string if you want a dialog
with no text in the title.</p>
<h4>Improving modal progress feedback</h4>
<p>Supporting concurrent operations requires more sophisticated ways to show
modal progress. As part of the responsiveness effort additional progress support
was implemented in the class IProgressService. The existing way to show progress
with the ProgressMonitorDialog is still working. However, to improve the user
experience we recommend migrating to the new IProgressService.</p>
<p>The document <a href="http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/platform-core-home/documents/plan_concurrency_modal_progress.html">Showing
Modal Progress in Eclipse 3.0</a> describes how to migrate to the new
IProgressService.</p>
<h4>Debug Action Groups removed</h4>
<p>The Debug Action Groups extension point
(org.eclipse.debug.ui.debugActionGroups) has been removed. In Eclipse 3.0, the
workbench introduced support for Activities via the
org.eclipse.platform.ui.activities extension point. This support provides
everything that Debug Action Groups provided and is also easier to use (it
supports patterns instead of specifying all actions exhaustively) and has a
programmatic API to support it. Failing to remove references to the old
extension point won't cause any failures. References to the extension point will
simply be ignored. Product vendors are encouraged to use the workbench
Activities support to associate language-specific debugger actions with
language-specific activities (for example, C++ debugging actions might be
associated with an activity called "Developing C++").</p>
<h4>BreakpointManager can be disabled</h4>
<p>IBreakpointManager now defines the methods setEnabled(boolean) and
isEnabled(). When the breakpoint manager is disabled, debuggers should ignore
all registered breakpoints. The debug platform also provides a new listener
mechanism, IBreakpointManagerListener which allows clients to register with the
breakpoint manager to be notified when its enablement changes. The Breakpoints
view calls this API from a new toggle action that allows the user to "Skip
All Breakpoints." Debuggers which do not honor the breakpoint manager's
enablement will thus appear somewhat broken if the user tries to use this
feature.</p>
<h4>[JDT only] Java search participants (package org.eclipse.jdt.core.search)</h4>
<p>Languages close to Java (such as JSP, SQLJ, JWS, etc.) should be able to
participate in Java searching. In particular, implementors of such languages
should be able to:</p>
<ul>
<li>index their source by converting it into Java equivalent source, and
feeding it to the Java indexer</li>
<li>index their source by parsing it themselves, but record Java index entries</li>
<li>locate matches in their source by converting it into Java equivalent
source, and feeding it to the Java match locator</li>
<li>locate matches in their source by matching themselves, and return Java
matches</li>
</ul>
<p>Such an implementor is called a search participant. It extends the
SearchParticipant class. Search participants are passed to search queries (see
SearchEngine.search(SearchPattern, SearchParticipant[], IJavaSearchScope,
SearchRequestor, IProgressMonitor)).</p>
<p>For either indexing or locating matches, a search participant needs to define
a subclass of SearchDocument that can retrieve the contents of the document by
overriding either getByteContents() or getCharContents(). An instance of this
subclass is returned in getDocument(String).</p>
<p>A search participant wishing to index some document will use
SearchParticipant.scheduleDocumentIndexing(SearchDocument, IPath) to schedule
the indexing of the given document in the given index. Once the document is
ready to be indexed, the underlying framework calls
SearchParticipant.indexDocument(SearchDocument, IPath). The search participant
then gets the document's content, parses it and adds index entries using
SearchDocument.addIndexEntry(char[], char[]).</p>
<p>Once indexing is done, one can then query the indexes and locate matches
using SearchEngine.search(SearchPattern, SearchParticipant[], IJavaSearchScope,
SearchRequestor, IProgressMonitor). This first asks each search participant for
the indexes needed by this query using
SearchParticipant.selectIndexes(SearchPattern, IJavaSearchScope). For each index
entry that matches the given pattern, a search document is created by asking the
search participant (see getDocument(String)). All these documents are passed to
the search participant so that it can locate matches using
locateMatches(SearchDocument[], SearchPattern, IJavaSearchScope, SearchRequestor,
IProgressMonitor). The search participant notifies the SearchRequestor of search
matches using acceptSearchMatch(SearchMatch) and passing an instance of a
subclass of SearchMatch.</p>
<p>A search participant can delegate part of its work to the default Java search
participant. An instance of this default participant is obtained using
SearchEngine.getDefaultSearchParticipant(). For example when asked to locate
matches, an SQLJ participant can create documents .java documents from its .sqlj
documents and delegate the work to the default participant passing it the .java
documents.</p>
</body>
</html>
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |