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.
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:
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.
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.
While we continue to talk about plug-ins, in the new runtime a plug-in is really a bundle plus some extensions and extension-points. The term bundle is defined by the OSGi framework specification and refers to a collection of types and resources and associated inter-bundle prerequisite information. The extension registry 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 Registries).
In the Eclipse 2.x runtime, the plug-in object has a number of roles and responsibilities:
In the Eclipse 3.0 runtime picture, these roles and responsibilities are factored into distinct objects.
Plugin also implements BundleActivator. 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 BundleActivator class or not have a bundle activator at all.
The steps required to port a 2.x Plugin 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:
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 bundles and the Eclipse extension registry.
The parts of IPluginRegistry dealing with execution specification (e.g., IPluginDescriptor, ILibrary, IPrequisite) have been deprecated and the remaining parts related to extensions and extension point have been moved to IExtensionRegistry. 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.
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 state (see org.eclipse.osgi.service.resolver.State and friends) structure represents and allows the manipulation of the essential execution-related information.
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,
org.eclipse.ui.workbench.nl/ fragment.xml plugin_fr.properties plugin_pt_BR.properties ... nl1.jar
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.
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.
The entire org.eclipse.core.boot package has been deprecated. BootLoader has been merged with org.eclipse.core.runtime.Platform 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.
IPlatformConfiguration 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 org.eclipse.update.configurator.IPlatformConfiguration.
IPlatformRunnable has been moved to org.eclipse.core.runtime.IPlatformRunnable.
The getDeclaringPlugin()
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 IPluginDescriptors.
Users of this API should consider the new method getParentIdentifier() found
on both IExtension and IExtensionPoint.
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.
In the new runtime, Plugin 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.
All types in this package are now deprecated. See the discussion on registries for more information.
Clients of the IWorkspace.run(IWorkspaceRunnable,IProgressMonitor) method should revisit their uses of this method and consider using the richer method IWorkspace.run(IWorkspaceRunnable,ISchedulingRule,int,IProgressMonitor). The old IWorkspace.run method acquires a lock on the entire workspace for the duration of the IWorkspaceRunnable. 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.
The suggested solution is to switch all references to old IWorkspace.run
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
IResourceRuleFactory
should be used to obtain the scheduling
rule for a resource-changing operation. If desired, a MultiRule can be used
to specify multiple resource rules, and the MultiRule.combine convenience
method can be used to combine rules from various resource-changing operations.
If no locking is required, a scheduling rule of null 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.
filteredSelection
from selection
:
IStructuredSelection filteredSelection = selection;
List selectedResources = IDE.computeSelectedResources(currentSelection);
if (!selectedResources.isEmpty()) {
filteredSelection = new
StructuredSelection(selectedResources);
}
IStructuredSelection filteredSelection = selection;
List selectedResources = IDE.computeSelectedResources(currentSelection);
if (!selectedResources.isEmpty()) {
filteredSelection = new
StructuredSelection(selectedResources);
}
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()); } } } }
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())); }
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.
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.
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.
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.
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.
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.
The following annotation types are declared by the org.eclipse.ui.editors plug-in:
<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>
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.
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 ILaunchConfigurationType.getDelegate()
is now deprecated. The method getDelegate(String mode)
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 run
mode.
Launch tab groups and launch tabs are no longer notified when a launch
completes. The method launched(ILaunch)
in the interfaces ILaunchConfigurationTab
and ILaunchConfigurationTabGroup
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.
Two methods have been added to the ILaunchConfigurationTab
interface - activated and deactivated. These new life cycle methods are called
when a tab is entered and exited respectively. Existing implementations of ILaunchConfigurationTab
that subclass the abstract class provided by the debug plug-in (AbstractLaunchConfigurationTab
)
are binary compatible since the methods are implemented in the abstract class.
In prior releases, a tab was sent the message initializeFrom
when it was activated, and performApply
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.
The default implementation of activated
, provided by the
abstract tab, calls initializeFrom
. And, the default implementation
of deactivated
calls performApply
. 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.
In prior releases, perspective switching was specified on a launch
configuration, via the launch configuration attributes ATTR_TARGET_DEBUG_PERSPECTIVE
and ATTR_TARGET_RUN_PERSPECTIVE
. 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 DebugUITools
to
set and get the perspective associated with a launch configuration type for a
specific launch mode.
An additional, optional, launchMode
element has been added to
the launchConfigurationTabGroup
extension point, allowing a
contributed tab group to specify a default perspective for a launch
configuration type and mode.
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.
Two methods have been added to the VMRunnerConfiguration
class
to support the setting and retrieving of environment variables. Implementors of IVMRunner
should call VMRunnerConfiguration.getEnvironment()
and pass that
environment into the executed JVM. Clients who use DebugPlugin.exec(String[]
cmdLine, File workingDirectory)
can do this by calling DebugPlugin.exec(String[]
cmdLine, File workingDirectory, String[] envp)
instead. Simply passing in
the result from getEnvironment()
is sufficient.
In prior releases, the VMRunnerConfiguration
had one attribute
to describe a boot path. The attribute is a collection of Strings
to be specified in the -Xbootclasspath
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:
getPrependBootClassPath()
- returns a collection of entries
to be prepended to the boot path (the -Xbootclasspath/p
argument)getMainBootClassPath()
- returns a collection of entries to
be placed on the boot path (the -Xbootclasspath
argument)getAppendBootClassPath()
- returns a collection of entries to
be appended to the boot path (the -Xbootclasspath/a
argument)The old attribute, getBootClassPath()
, still exists and contains
a complete path equivalent to that of the three new attributes. However, VMRunners
that support the new boot path options should take advantage of the new
attributes.
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.
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.
The Java model API changes in 2 ways to add this improved support:
(1) The functionality formerly found on IWorkingCopy
and
inherited by ICompilationUnit
has been consolidated into ICompilationUnit
.
The IWorkingCopy
interface was only used in this one place, and was
gratuitously more general that in needed to be. This change simplifies the API. IWorkingCopy
has been deprecated. Other places in the API where IWorkingCopy
is
used as a parameter or result type have been deprecated as well; the replacement
API methods mention ICompilationUnit
instead of IWorkingCopy
.
(2) The interface IBufferFactory
has been replaced by WorkingCopyOwner
.
The improved support for working copies requires that there be an object to own
the working copies. Although IBufferFactory
is in the right place,
the name does not adequately convey how the new working copy mechanism works. WorkingCopyOwner
is much more suggestive. In addition, WorkingCopyOwner
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 IBufferFactory
moves to WorkingCopyOwner
unaffected. WorkingCopyOwner
does not implement IBufferFactory
to make it clear that IBufferFactory
is a thing of the past. IBufferFactory
has been deprecated. Other
places in the API where IBufferFactory
appears as a parameter or
result type have been deprecated as well; the replacement API methods mention WorkingCopyOwner
instead of IBufferFactory
.
These changes do not break binary compatibility.
When migrating, all references to the type IWorkingCopy
should
instead reference ICompilationUnit
. The sole implementation of IWorkingCopy
implements ICompilationUnit
as well, meaning objects of type IWorkingCopy
can be safely cast to ICompilationUnit
.
A class that implements IBufferFactory
will need to replaced by
a subclass of WorkingCopyOwner
. Although WorkingCopyOwner
does not implement IBufferFactory
itself, it would be possible to
declare the subclass of WorkingCopyOwner
that implements IBufferFactory
thereby creating a bridge between old and new (IBufferFactory
declares createBuffer(IOpenable)
whereas WorkingCopyOwner
declares createBuffer(ICompilationUnit)
; ICompilationUnit
extends IOpenable
).
Because the changes involving IWorkingCopy
and IBufferFactory
are interwined, we recommend dealing with both at the same time. The details of
the deprecations are as follows:
IWorkingCopy
(package org.eclipse.jdt.core
)
public void commit(boolean, IProgressMonitor)
has been
deprecated.
ICompilationUnit
directly:
public void commitWorkingCopy(boolean, IProgressMonitor)
wc.commit(b,monitor)
as ((ICompilationUnit)
wc).commitWorkingCopy(b,monitor)
public void destroy()
has been deprecated.
ICompilationUnit
directly:
public void discardWorkingCopy(boolean, IProgressMonitor)
wc.destroy()
as ((ICompilationUnit)
wc).discardWorkingCopy()
public IJavaElement findSharedWorkingCopy(IBufferFactory)
has been deprecated.
ICompilationUnit
directly:
public ICompilationUnit findWorkingCopy(WorkingCopyOwner)
WorkingCopyOwner
substitutes for IBufferFactory.
public IJavaElement getOriginal(IJavaElement)
has been
deprecated.
IJavaElement
:
public IJavaElement getPrimaryElement()
wc.getOriginal(elt)
as elt.getPrimaryElement()
IWorkingCopy.getOriginal
, IJavaElement.getPrimaryElement
does not return null
if the receiver is not a working
copy.public IJavaElement getOriginalElement()
has been
deprecated.
ICompilationUnit
directly:
public ICompilationUnit getPrimary()
wc.getOriginalElement()
as ((ICompilationUnit)
wc).getPrimary()
IWorkingCopy.getOriginalElement
, IWorkingCopy.getPrimary
does not return null
if the receiver is not a working
copy.public IJavaElement[] findElements(IJavaElement)
has been
deprecated.
ICompilationUnit
directly.wc.findElements(elts)
as ((ICompilationUnit)
wc).findElements(elts)
public IType findPrimaryType()
has been deprecated.
ICompilationUnit
directly.wc.findPrimaryType()
as ((ICompilationUnit)
wc).findPrimaryType()
public IJavaElement getSharedWorkingCopy(IProgressMonitor,
IBufferFactory, IProblemRequestor)
has been deprecated.
ICompilationUnit
directly:
public ICompilationUnit getWorkingCopy(WorkingCopyOwner,
IProblemRequestor, IProgressMonitor)
WorkingCopyOwner
substitutes for IBufferFactory.
public IJavaElement getWorkingCopy()
has been deprecated.
ICompilationUnit
directly:
public ICompilationUnit getWorkingCopy(IProgressMonitor)
wc.getWorkingCopy()
as ((ICompilationUnit)
wc).getWorkingCopy(null)
public IJavaElement getWorkingCopy(IProgressMonitor,
IBufferFactory, IProblemRequestor)
has been deprecated.
ICompilationUnit
directly:
public ICompilationUnit getWorkingCopy(WorkingCopyOwner,
IProblemRequestor, IProgressMonitor)
WorkingCopyOwner
substitutes for IBufferFactory.
public boolean isBasedOn(IResource)
has been deprecated.
ICompilationUnit
directly:
public boolean hasResourceChanged()
wc.isBasesOn(res)
as ((ICompilationUnit)
wc).hasResourceChanged()
public boolean isWorkingCopy()
has been deprecated.
ICompilationUnit
directly.wc.isWorkingCopy()
as ((ICompilationUnit)
wc).isWorkingCopy()
public IMarker[] reconcile()
has been deprecated.
ICompilationUnit
directly:
public void reconcile(boolean,IProgressMonitor)
wc.reconcile()
as ((ICompilationUnit)
wc).reconcile(false, null)
null
; the
replacement method does not return a result.public void reconcile(boolean, IProgressMonitor)
has been
deprecated.
ICompilationUnit
directly.wc.reconcile(b,monitor)
as ((ICompilationUnit)
wc).reconcile(b.monitor)
public void restore()
has been deprecated.
ICompilationUnit
directly.wc.restore()
as ((ICompilationUnit)
wc).restore()
IType
(package org.eclipse.jdt.core
)
public ITypeHierarchy newSupertypeHierarchy(IWorkingCopy[],
IProgressMonitor)
has been deprecated.
public ITypeHierarchy newSupertypeHierarchy(c,
IProgressMonitor)
IWorkingCopy[]
to ICompilationUnit[]
.public ITypeHierarchy newTypeHierarchy(IWorkingCopy[],
IProgressMonitor)
has been deprecated.
public ITypeHierarchy newTypeHierarchy(ICompilationUnit[],
IProgressMonitor)
IWorkingCopy[]
to ICompilationUnit[]
.IClassFile
(package org.eclipse.jdt.core
)
public IJavaElement getWorkingCopy(IProgressMonitor,
IBufferFactory)
has been deprecated.
public ICompilationUnit getWorkingCopy(WorkingCopyOwner,
IProgressMonitor)
WorkingCopyOwner
substitutes for IBufferFactory.
JavaCore
(package org.eclipse.jdt.core
)
public IWorkingCopy[] getSharedWorkingCopies(IBufferFactory)
has been deprecated.
public ICompilationUnit[]
getWorkingCopies(WorkingCopyOwner)
WorkingCopyOwner
substitutes for IBufferFactory.
ICompilationUnit[]
to IWorkingCopy[]
.SearchEngine
(package org.eclipse.jdt.core.search
)
public SearchEngine(IWorkingCopy[])
has been deprecated.
public SearchEngine(ICompilationUnit[])
IWorkingCopy[]
to ICompilationUnit[]
.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.
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:
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.
Clients will have to create implementations of ISearchQuery
, ISearchResult
and ISearchResultPage
. The ISearchResultPage
implementation must then be contributed into the new org.eclipse.search.searchResultViewPages
extension point.
Default implementations for ISearchResult
and ISearchResultPage
are provided in the package
org.eclipse.search.ui.text
.
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.
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.
The document Showing Modal Progress in Eclipse 3.0 describes how to migrate to the new IProgressService.
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++").
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.
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:
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)).
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).
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[]).
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.
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.