Changes required when adopting 3.0 mechanisms and APIs

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.

 

Getting off of org.eclipse.core.runtime.compatibility

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.

Plug-ins and bundles

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.

Bundle

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 Plugin class, the OSGi Bundle class is not extensible. That is, developers do not have the opportunity to define their own bundle class.

BundleActivator

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 Plugin class. The specified class is instantiated by the framework and used to implement the start() and stop() 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 Plugin classes do both initialization and registration. In OSGi activators must only do registration. Doing large amounts of initialization (or any other work) in BundleActivator.start() threatens the liveness of the system.

BundleContext

BundleContexts are the OSGi mechanism for exposing general system function to individual bundles. Each bundle has a unique and private instance of BundleContext which they can use to access system function (e.g., getBundles() to discover all bundles in the system).

Plugin

The new Plugin is very much like the original Eclipse Plugin class with the following exceptions: Plugin 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 Platform class in the runtime.

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:

Initialization

Datastructure and model initialization is quite often done in Plugin.startup(). The natural/obvious mapping would be to do this work in a BundleActivator.start(), that is to leave the function on Plugin. This is strongly discouraged. As with 2.x plug-ins, 3.0 plug-ins/bundles may be started for many different reasons in many different circumstances.
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 code 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 startup() but yet all users, in all usecases had to pay the memory and time penalty for this eager initialization.
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.

Registration

Plug-in startup is a convenient time to register listeners, services etc. and start background processing threads (e.g., listening on a socket). Plugin.start() 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).

Plug-in global data

Your Plugin class can continue to play this role. The main issue is that Plugin objects are no longer globally accessible via a system-managed list. In Eclipse 2.x you could discover any plug-in's Plugin ojbect via the plug-in registry. This is no longer possible. In most circumstances this type of access is not required. Plugins accessed via the registry are more typically used as generic Plugins rather than calling domain-specific methods. The equivalent level of capability can be had by accessing and manipulating the corresponding Bundle objects.

Registries and the plug-in model

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.

 

NL fragment structure

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.

 

API changes overview

org.eclipse.core.boot (package org.eclipse.core.boot)

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.

IExtension and IExtensionPoint (package org.eclipse.core.runtime)

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.

ILibrary, IPluginDescriptor, IPluginRegistry and IPrerequisite (package org.eclipse.core.runtime)

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.

Platform and Plugin (package org.eclipse.core.runtime)

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.

org.eclipse.core.runtime.model (package org.eclipse.core.runtime.model)

All types in this package are now deprecated. See the discussion on registries for more information.

IWorkspaceRunnable and IWorkspace.run (package org.eclipse.core.resources)

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.

IWorkbenchPage (package org.eclipse.ui)

IEditorDescriptor (package org.eclipse.ui)

ISharedImages (package org.eclipse.ui)

IWorkbenchActionConstants (package org.eclipse.ui)

IWorkbenchPreferenceConstants (package org.eclipse.ui)

IExportWizard (package org.eclipse.ui)

IImportWizard (package org.eclipse.ui)

INewWizard (package org.eclipse.ui)

WorkbenchHelp (package org.eclipse.ui.help)

IHelp (package org.eclipse.help)

ITextEditorActionConstants (package org.eclipse.ui.texteditor)

IAbstractTextEditorHelpContextIds (package org.eclipse.ui.texteditor)

BasicTextEditorActionContributor (package org.eclipse.ui.texteditor)

TextEditorActionContributor (package org.eclipse.ui.editors.text)

annotationTypes extension point (plug-in org.eclipse.ui.editors)

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.

markerAnnotationSpecification extension point (plug-in org.eclipse.ui.editors)

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.

Migration to annotationTypes extension point (plug-in org.eclipse.ui.editors)

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.

ILaunchConfigurationType (package org.eclipse.debug.core)

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.

ILaunchConfigurationTab and ILaunchConfigurationTabGroup (package org.eclipse.debug.ui)

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.

ILaunchConfigurationTab and AbstractLaunchConfigurationTab (package org.eclipse.debug.ui)

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.

launchConfigurationTabGroup extension point Type (package org.eclipse.debug.ui)

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.

[JDT only] IVMRunner (package org.eclipse.jdt.launching)

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.

[JDT only] VMRunnerConfiguration and Bootstrap Classes (package org.eclipse.jdt.launching)

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:

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.

[JDT only] Improved support for working copies (package org.eclipse.jdt.core)

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:

Restructuring of org.eclipse.help plug-in

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:

New Search UI API

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.

null messages in MessageBox and DirectoryDialog (package org.eclipse.swt.widgets)

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.

Improving modal progress feedback

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.

Debug Action Groups removed

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++").

BreakpointManager can be disabled

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.

[JDT only] Java search participants (package org.eclipse.jdt.core.search)

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.

Legal notices