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.
-
Application model changes
-
Launch selection versus launch last
-
Replacing a hard-coded
IHyperlinkDetector
with an extension
-
Improve performance when working with file
buffers
-
Launch delegate names and descriptions
-
Support for file buffers added to Compare
-
New Minimize/Maximize behavior
-
Menu contributions and commands
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.
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.
- An
IResource adapter is retrieved from the selection or active
editor (which can be null).
- 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).
- 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.
- The set of applicable launch configurations is reduced to those that have
a resource mapping equal to or contained by the retrieved resource adapter
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
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:
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:
Clients using the deprecated methods are encouraged to adopt the new API in order
to take advantage of the performance improvement.
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:
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.
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
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.
