## Adopting 3.3 mechanisms and APIs

This section describes changes that are required if you are trying to change your 3.2 plug-in to adopt the 3.3 mechanisms and APIs.

1. Application model changes
2. Launch selection versus launch last
3. Replacing a hard-coded `IHyperlinkDetector` with an extension
4. Improve performance when working with file buffers
5. Launch delegate names and descriptions
6. Support for file buffers added to Compare
7. New Minimize/Maximize behavior
8. Menu contributions and commands

## 1. Application model changes

The Eclipse application container has been moved from org.eclipse.core.runtime into the new bundle org.eclipse.equinox.app. The Eclipse application container included in the org.eclipse.equinox.app bundle implements the Application Admin Service specification from the OSGi R4 specification.

The following extension points have also been moved into the org.eclipse.equinox.app bundle. Note that the fully qualified extension point ids are unchanged:

- org.eclipse.core.runtime.applications
- org.eclipse.core.runtime.products

The interface org.eclipse.core.runtime.IPlatformRunnable has been deprecated and the org.eclipse.equinox.app.IApplication interface should be used instead. IPlatformRunnable is supported for backwards compatibility, and clients are encouraged to move to the new IApplication API instead.

As a result of the code move, custom configurations and scripts that explicitly reference org.eclipse.core.runtime might need to add the org.eclipse.equinox.app bundle.

See bug 109893 for more details.

## 2. Launch selection versus launch last

By default, running and debugging applications has been simplified to run or debug the selected file or active editor. When the selected resource (or active editor) is not executable, users can opt to launch the associated project or re-launch the previous launch. These settings are managed on the Run/Debug > Launching preference page. Users can also revert to the 3.2 behavior of always launching the previous application.

Pressing the Run or Debug toolbar button will launch the selected resource (as will the Run or Debug action in the top level Run menu). When no launch configuration exists for a file and there is only one way to launch it, the file will simply be launched in the mode selected. When there is more than one way to launch a file, the user will be prompted to select how to run or debug the application. For example, when running a JUnit test it can be run as a Java application or JUnit test. A launch configuration will be created and an entry will be added to the launch history for the application. When the same resource is launched again, it will use the most recent configuration in the launch history associated with that resource.

The underlying infrastructure for selection based launching relies on the launch shortcuts applicable to a resource (or editor) and the resource mappings associated with existing launch configurations. As well, API (a new extension element) has been added to the `launchShortcuts` extension to associate a launch shortcut with one or more types of launch configurations. For example, this tells the platform that the "Java Application" launch shortcut is associated with "Java Application" launch configurations.

The contextual launch support uses the following approach to determine how a selection or active editor should be launched.

1. An `IResource` adapter is retrieved from the selection or active editor (which can be `null`).
2. A set of applicable launch configuration types are computed from the set of launch shortcuts applicable to the selection/editor (using the new launch configuration type elements defined by launch shortcuts).
3. A set of applicable launch configurations is computed based on the launch configuration types applicable to the selection/editor and the existing launch configurations in the workspace.
4. The set of applicable launch configurations is reduced to those that have a resource mapping equal to or contained by the retrieved resource adapter
5. The set of applicable launch configurations is compared to the launch history and the most recently launched configuration in the set is selected for launching.
6. When there are applicable launch configurations, but none are in the recent launch history, the user is prompted to select one of the applicable configurations to launch.
7. When there are applicable launch shortcuts and no applicable launch configurations, the user is prompted on how they want to launch the selection (i.e. which shortcut they want to use).

When there are no applicable launch configurations or launch shortcuts, the platform either attempts to launch the associated project or launches last, based on user preference settings. When the user has chosen to launch the associated project, the same steps as above are followed, except the resource used is the project.

For selection based launching to work well, plug-in providers should ensure the following.

1. Resource mappings for launch configurations should be scoped to the appropriate resource. For example, to support projects with multiple Java executables, Java application launch configurations are associated with the the .java file containing the main class.
2. Launch shortcut extensions should be updated with `configurationType` elements so the platform can infer which launch configuration types to consider when resolving launch configurations applicable to a selection/editor. As well, launch shortcuts should be updated with the new `description` attribute. This attribute is used when presenting the user with a list of shortcuts to choose from.
3. Launch configuration migration delegates should be updated to create appropriate resource mappings for existing launch configurations. For example, if launch your launch configuration resource mappings in 3.2 were always associated with a project, but now you want to associated them with specific files in a project to better support context launching, your migration delegate should be updated to update resource mappings.

## 3. Replacing a hard-coded `IHyperlinkDetector` with an extension

Before 3.3 it was not possible to contribute hyperlink detectors to existing source viewers and textual editors. Only their implementors could add them directly through code by providing their hyper link detectors via `SourceViewerConfiguration.getHyperlinkDetectors(ISourceViewer)`.

As of 3.3, clients can define hyperlink detector targets for their viewers and editors and they can contribute their own hyperlink detectors to such targets via the following extension points:

- org.eclipse.ui.workbench.texteditor.hyperlinkDetectorTargets
- org.eclipse.ui.workbench.texteditor.hyperlinkDetectors

## 4. Improve performance when working with file buffers

In earlier versions file buffer manager API methods used to take an `IPath` and it was up to the file buffer manager to detect whether that path pointed to a workspace or an external location. Those API methods have been deprecated in 3.3 in order to improve performance as in most cases clients already know whether their path is a workspace path or an external path. New methods with same names have been added that take one of the following location kind arguments:

- IFILE
- LOCATION
- NORMALIZE

Clients using the deprecated methods are encouraged to adopt the new API in order to take advantage of the performance improvement.

## 5. Launch delegate names and descriptions

New attributes have been added to the `launchConfigurationTypes` and `launchDelegates` extension points to provide names and descriptions for launch delegates. Since 3.3, the debug platform allows for more than one launcher to be contributed for the same kind of launch configuration type and launch mode. When more than one launcher is available the user must choose a preferred launcher and is presented with names and descriptions of available launchers. Clients contributing launch delegates with either of these extension points are encouraged to provide meaningful names and descriptions.

Clients contributing to the `org.eclipse.debug.core.launchConfigruationTypes` extension point should define the following new attributes:

- `delegateName`
- `delegateDescription`

Clients contributing to the `org.eclipse.debug.core.launchDelegates` extension point should define the following new attributes:

- `name`
- `delegateDescription`

## 6. Support for file buffers added to Compare

Compare editors can now be configured to use the same file buffers that are used by regular editors. This means that changes made in a compare editor will immediately be reflected in any other editor on the same file buffer or vice versa. Both the compare client and the provider of the compare viewer must make changes to enable this feature.

- In order for compare viewer providers to enable this feature, they must subclass TextMergeViewer and override both the getDocumentPartitioning and getDocumentPartitioning methods if they provide custom syntax highlighting. File buffer support in the basic TextMergeViewer is enabled. It is only subclasses that provide syntax highlighting that need to makes changes to adopt the feature. Also, providers of structure creators should subclass StructureCreator and override the getDocumentPartition and getDocumentPartitioning in order for their structure merge viewer to use the file buffer as well. This is described in more detail in the Implementing a Content Viewer section.
- Client can enable the use of file buffers by using the SaveableCompareEditorInput. The static method `createFileElement` can be used to create a typed element that wraps a file in order to enable the file buffer support for the file. This is described in more detail in the Advanced compare techniques section.

## 7. New Minimize/Maximize behavior

All RCP applications will, by default, get the new min/max behavior regardless of the presentation that is defined as long as it is capable of supporting the necessary operations (i.e. supports trim...). If the pre-3.3 min/max behavior is desired then the application should explicitly set the preference to false by adding the following line to their preference customization file (as defined by the product extension):

org.eclipse.ui/ENABLE_MIN_MAX=false

## 8. Menu contributions and commands

Support is now available to place commands in menus and toolbars through the org.eclipse.ui.menus extension point.

org.eclipse.ui.menus focuses on the appearance (label, tooltip, icon), location, and visibility of the command in the menu or toolbar. Command enabled state is still controlled via the org.eclipse.ui.handlers extension point or the `IHandlerService`.

In 3.2 placing a command in a toolbar or menu involved using one of the `IActionDelegate` extensions and coding the run method to use the `IHandlerService` to execute the command.