## 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:

- org.eclipse.core.boot - entire plug-in is legacy
- org.eclipse.core.runtime.compatibility - entire plug-in is legacy
- org.eclipse.core.runtime - various classes and methods are legacy

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:

- Lifecycle - The `Plugin` 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:
  - Registration - Hook various event mechanisms (e.g., register listeners) and otherwise make their presence known in the system (e.g., start needed threads).
  - Initialization - Initialize or prime their data structures and load models so they are ready for use.
- 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 `getDialogSettings()` and `getWorkbench()`.
- Context - The standard `Plugin` class provides access to various runtime-provided function such as preferences and logging.

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` object 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)

- 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.

#### IEditorDescriptor (package org.eclipse.ui)

- 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.

#### ISharedImages (package org.eclipse.ui)

- The following fields were removed (deprecated) from this interface because they were IDE-specific:
  - String IMG_OBJ_PROJECT
  - String IMG_OBJ_PROJECT_CLOSED
  - String IMG_OPEN_MARKER
  - String IMG_OBJS_TASK_TSK
  - String IMG_OBJS_BKMRK_TSK
- 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.

#### IWorkbenchActionConstants (package org.eclipse.ui)

- The following fields were removed (deprecated) from this interface; they are subsumed by the new ActionFactory class:
  - String ABOUT
  - String BACK
  - String CLOSE
  - String CLOSE_ALL
  - String COPY
  - String CUT
  - String DELETE
  - String EXPORT
  - String FIND
  - String FORWARD
  - String IMPORT
  - String MOVE
  - String NEW
  - String NEXT
  - String PASTE
  - String PREVIOUS
  - String PRINT
  - String PROPERTIES
  - String QUIT
  - String REDO
  - String REFRESH
  - String RENAME
  - String REVERT
  - String SAVE
  - String SAVE_ALL
  - String SAVE_AS
  - String SELECT_ALL
  - String UNDO
  - String UP
- 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().
- The following fields were removed (deprecated) from this interface because they were IDE-specific.
  - String ADD_TASK
  - String BOOKMARK
  - String BUILD
  - String BUILD_PROJECT
  - String CLOSE_PROJECT
  - String FIND
  - String OPEN_PROJECT
  - String REBUILD_ALL
  - String REBUILD_PROJECT
- 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().

#### IWorkbenchPreferenceConstants (package org.eclipse.ui)

- The following fields were removed (deprecated) from this interface because they were IDE-specific:
  - String PROJECT_OPEN_NEW_PERSPECTIVE
- Clients should instead use the fields of the same names declared on IDE.Preferences in the org.eclipse.ui.ide package.

#### IExportWizard (package org.eclipse.ui)

- 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.
- The selection passed to the wizard is generally used to prime the particular wizard page with contextually appropriate values.
- Client that implement IExportWizard and requires this resource-specific selection transformation should add the following to their init(IWorkbench, IStructuredSelection selection) method to computer `filteredSelection` from `selection`:
  - `IStructuredSelection filteredSelection = selection;
    List selectedResources = IDE.computeSelectedResources(currentSelection);
    if (!selectedResources.isEmpty()) {
    filteredSelection = new StructuredSelection(selectedResources);
    }`

#### IImportWizard (package org.eclipse.ui)

- 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.
- The selection passed to the wizard is generally used to prime the particular wizard page with contextually appropriate values.
- 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:
  - `IStructuredSelection filteredSelection = selection;
    List selectedResources = IDE.computeSelectedResources(currentSelection);
    if (!selectedResources.isEmpty()) {
    filteredSelection = new StructuredSelection(selectedResources);
    }`

#### INewWizard (package org.eclipse.ui)

- 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.
- The selection passed to the wizard is generally used to prime the particular wizard page with contextually appropriate values.
- 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:

      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());
               }
            }
        }
      }

#### WorkbenchHelp (package org.eclipse.ui.help)

- The following WorkbenchHelp method was removed (deprecated) from this class because its result (IHelp) was removed (deprecated):
  - public static IHelp getHelpSupport()
- Clients that called this method to obtain an IHelp should instead call the static methods on HelpSystem or WorkbenchHelp.

#### IHelp (package org.eclipse.help)

- 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).
- The following IHelp methods now appear as static methods on a new HelpSystem class in the same package:
  - public IToc[] getTocs()
  - public IContext getContext(String contextId)
- The rest of the IHelp methods now appear as static method on WorkbenchHelp.
- 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).
- There should be no clients implementing this interface beyond the Platform which supplied the sole implementation of this interface.

#### ITextEditorActionConstants (package org.eclipse.ui.texteditor)

- 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.

#### IAbstractTextEditorHelpContextIds (package org.eclipse.ui.texteditor)

- 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.

#### BasicTextEditorActionContributor (package org.eclipse.ui.texteditor)

- 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:

-      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()));
       }

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

- 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.

#### 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:

- `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.

#### [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:

- `IWorkingCopy` (package `org.eclipse.jdt.core`)
  - `public void commit(boolean, IProgressMonitor)` has been deprecated.
    - The equivalent functionality is now provided on `ICompilationUnit` directly:
      - `public void commitWorkingCopy(boolean, IProgressMonitor)`
    - Rewrite `wc.commit(b,monitor)` as `((ICompilationUnit) wc).commitWorkingCopy(b,monitor)`
  - `public void destroy()` has been deprecated.
    - The equivalent functionality is now provided on `ICompilationUnit` directly:
      - `public void discardWorkingCopy(boolean, IProgressMonitor)`
    - Rewrite `wc.destroy()` as `((ICompilationUnit) wc).discardWorkingCopy()`
  - `public IJavaElement findSharedWorkingCopy(IBufferFactory)` has been deprecated.
    - The equivalent functionality is now provided on `ICompilationUnit` directly:
      - `public ICompilationUnit findWorkingCopy(WorkingCopyOwner)`
    - Note: `WorkingCopyOwner` substitutes for `IBufferFactory.`
  - `public IJavaElement getOriginal(IJavaElement)` has been deprecated.
    - The equivalent functionality is now provided on `IJavaElement`:
      - `public IJavaElement getPrimaryElement()`
    - Rewrite `wc.getOriginal(elt)` as `elt.getPrimaryElement()`
    - Note: Unlike `IWorkingCopy.getOriginal`, `IJavaElement.getPrimaryElement` does not return `null` if the receiver is not a working copy.
  - `public IJavaElement getOriginalElement()` has been deprecated.
    - The equivalent functionality is now provided on `ICompilationUnit` directly:
      - `public ICompilationUnit getPrimary()`
    - Rewrite `wc.getOriginalElement()` as `((ICompilationUnit) wc).getPrimary()`
    - Note: Unlike `IWorkingCopy.getOriginalElement`, `IWorkingCopy.getPrimary` does not return `null` if the receiver is not a working copy.
  - `public IJavaElement[] findElements(IJavaElement)` has been deprecated.
    - The method is now declared on `ICompilationUnit` directly.
    - Rewrite `wc.findElements(elts)` as `((ICompilationUnit) wc).findElements(elts)`
  - `public IType findPrimaryType()` has been deprecated.
    - The method is now declared on `ICompilationUnit` directly.
    - Rewrite `wc.findPrimaryType()` as `((ICompilationUnit) wc).findPrimaryType()`
  - `public IJavaElement getSharedWorkingCopy(IProgressMonitor, IBufferFactory, IProblemRequestor)` has been deprecated.
    - The equivalent functionality is now provided on `ICompilationUnit` directly:
      - `public ICompilationUnit getWorkingCopy(WorkingCopyOwner, IProblemRequestor, IProgressMonitor)`
    - Note: the parameter order has changed, and `WorkingCopyOwner` substitutes for `IBufferFactory.`
  - `public IJavaElement getWorkingCopy()` has been deprecated.
    - The equivalent functionality is now provided on `ICompilationUnit` directly:
      - `public ICompilationUnit getWorkingCopy(IProgressMonitor)`
    - Rewrite `wc.getWorkingCopy()` as `((ICompilationUnit) wc).getWorkingCopy(null)`
  - `public IJavaElement getWorkingCopy(IProgressMonitor, IBufferFactory, IProblemRequestor)` has been deprecated.
    - The equivalent functionality is now provided on `ICompilationUnit` directly:
      - `public ICompilationUnit getWorkingCopy(WorkingCopyOwner, IProblemRequestor, IProgressMonitor)`
    - Note: the parameter order has changed, and `WorkingCopyOwner` substitutes for `IBufferFactory.`
  - `public boolean isBasedOn(IResource)` has been deprecated.
    - The equivalent functionality is now provided on `ICompilationUnit` directly:
      - `public boolean hasResourceChanged()`
    - Rewrite `wc.isBasesOn(res)` as `((ICompilationUnit) wc).hasResourceChanged()`
  - `public boolean isWorkingCopy()` has been deprecated.
    - The method is now declared on `ICompilationUnit` directly.
    - Rewrite `wc.isWorkingCopy()` as `((ICompilationUnit) wc).isWorkingCopy()`
  - `public IMarker[] reconcile()` has been deprecated.
    - The equivalent functionality is now provided on `ICompilationUnit` directly:
      - `public void reconcile(boolean,IProgressMonitor)`
    - Rewrite `wc.reconcile()` as `((ICompilationUnit) wc).reconcile(false, null)`
    - Note: The former method always returned `null`; the replacement method does not return a result.
  - `public void reconcile(boolean, IProgressMonitor)` has been deprecated.
    - The method is now declared on `ICompilationUnit` directly.
    - Rewrite `wc.reconcile(b,monitor)` as `((ICompilationUnit) wc).reconcile(b.monitor)`
  - `public void restore()` has been deprecated.
    - The method is now declared on `ICompilationUnit` directly.
    - Rewrite `wc.restore()` as `((ICompilationUnit) wc).restore()`
- `IType` (package `org.eclipse.jdt.core`)
  - `public ITypeHierarchy newSupertypeHierarchy(IWorkingCopy[], IProgressMonitor)` has been deprecated.
    - The replacement method is provided on the same class:
      - `public ITypeHierarchy newSupertypeHierarchy(c, IProgressMonitor)`
    - Note: The Java language rules for array types preclude casting `IWorkingCopy[]` to `ICompilationUnit[]`.
  - `public ITypeHierarchy newTypeHierarchy(IWorkingCopy[], IProgressMonitor)` has been deprecated.
    - The replacement method is provided on the same class:
      - `public ITypeHierarchy newTypeHierarchy(ICompilationUnit[], IProgressMonitor)`
    - Note: The Java language rules for array types preclude casting `IWorkingCopy[]` to `ICompilationUnit[]`.
- `IClassFile` (package `org.eclipse.jdt.core`)
  - `public IJavaElement getWorkingCopy(IProgressMonitor, IBufferFactory)` has been deprecated.
    - The replacement method is provided on the same class:
      - `public ICompilationUnit getWorkingCopy(WorkingCopyOwner, IProgressMonitor)`
    - Note: the parameter order has changed, and `WorkingCopyOwner` substitutes for `IBufferFactory.`
- `JavaCore` (package `org.eclipse.jdt.core`)
  - `public IWorkingCopy[] getSharedWorkingCopies(IBufferFactory)` has been deprecated.
    - The replacement method is provided on the same class:
      - `public ICompilationUnit[] getWorkingCopies(WorkingCopyOwner)`
    - Note: `WorkingCopyOwner` substitutes for `IBufferFactory.`
    - Note: The Java language rules for array types preclude casting `ICompilationUnit[]` to `IWorkingCopy[]`.
- `SearchEngine` (package `org.eclipse.jdt.core.search`)
  - `public SearchEngine(IWorkingCopy[])` has been deprecated.
    - The replacement constructor is provided on the same class:
      - `public SearchEngine(ICompilationUnit[])`
    - Note: The Java language rules for array types preclude casting `IWorkingCopy[]` to `ICompilationUnit[]`.

#### 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:

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

#### 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:

- index their source by converting it into Java equivalent source, and feeding it to the Java indexer
- index their source by parsing it themselves, but record Java index entries
- locate matches in their source by converting it into Java equivalent source, and feeding it to the Java match locator
- locate matches in their source by matching themselves, and return Java matches

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.