org.eclipse.platform.doc.isv/porting/3.3/recommended.html

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.17 - (download) (as text) (annotate)
Tue Mar 24 14:00:00 2009 UTC (8 months ago) by mcq
Branch: MAIN
CVS Tags: v20090922-0800, v20091103-0800, r351_v20090821-0800, v20090908-0800, v20090811-0800, v20091013-0800, v20090528-2000, v20090513-2000, v20090714-0800, v20090825-0800, v20090902, v20090611, v20090526-2000, v20090601-2000, v20090727, v20090504-2000, v20090601-1909, v20090505-2000, v20091020-0800, v20090421-0800, v20090414-0800, v20090429-1800b, v20090527-2000, v20090728-0800, v20091124-0800b, R3_5, v20090707-0800, v20090429, v20090425, v20090506-2000, v20090331-0800, v20090507-2000, v20090915, v20091026-1200, r351_v20090810-0600, v20090902-1317, v20091117-0800, v20090602, v20090603, v20090522-1100, v20090604-2000, r351_v20090708-0800, v20090508-2000, v20090602-2000, v20090531-2000, v20090810, v20090527-2010, v20090506_1800, v20090521-2000, v20090929-0800, v20090921-1800, v20090427-1800, v20090407-0800, v20090426-2000, v20090603-2000, v20090413, v20091110-0800, v20090914-0800, v20090730-2000, v20090514-2000, v20090520-2000, v20090901-0800, v20090818-0800, r351_v20090831, R3_5_1, v20090604, v20090511-2000, v20091006-0800, v20090429_1800, v20090803-1800, HEAD
Branch point for: R3_5_maintenance
Changes since 1.16: +1 -1 lines 
Added lang="en" to html, and xml:lang="en" to xhtml files.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html lang="en">
<head>
<meta name="copyright" content="Copyright (c) IBM Corporation and others 2007. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="STYLESHEET" href="../../book.css" charset="ISO-8859-1" type="text/css">
<title>Adopting 3.3 mechanisms and APIs</title>
</head>

<body>

<h2>Adopting 3.3 mechanisms and APIs</h2>
<p>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.</p>
  
<ol>
  <li><a href="#AppModel">Application model changes</a></li>
  <li><a href="#ContextLaunch">Launch selection versus launch last</a></li>
  <li><a href="#HyperlinkDetector">Replacing a hard-coded <code>IHyperlinkDetector</code> 
    with an extension</a></li>
  <li><a href="#FileBufferPerformance">Improve performance when working with file 
    buffers</a></li>
  <li><a href="#LaunchDelegate">Launch delegate names and descriptions</a></li>
  <li><a href="#Compare">Support for file buffers added to Compare</a></li>
  <li><a href="#Presentation">New Minimize/Maximize behavior</a></li>
  <li><a href="#MenuContribution">Menu contributions and commands</a></li>
</ol>
<hr>

<!-- ############################################## -->
<h2><a name="AppModel">1. Application model changes</a></h2>
<p>The Eclipse application container has been moved from <b>org.eclipse.core.runtime</b> 
into the new bundle <b>org.eclipse.equinox.app</b>. The Eclipse application container included in the 
org.eclipse.equinox.app bundle implements the Application Admin Service specification from the OSGi R4 specification.  
</p>
<p>
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:</p>
<ul>
 <li>org.eclipse.core.runtime.applications</li>
 <li>org.eclipse.core.runtime.products</li>
</ul>
The interface <b>org.eclipse.core.runtime.IPlatformRunnable</b> 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.
<p>
As a result of the code move, custom configurations and scripts that explicitly 
reference <b>org.eclipse.core.runtime</b> might need to add the <b>org.eclipse.equinox.app</b> bundle.
</p>
<p>See <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=109893">bug 109893</a> 
  for more details. </p> 
<!-- ############################################## -->
<p>&nbsp;</p>
<h2><a name="ContextLaunch">2. Launch selection versus launch last</a></h2>
<p>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 <strong>Run/Debug 
  &gt; Launching</strong> preference page. Users can also revert to the 3.2 behavior 
  of always launching the previous application.</p>
<p>Pressing the <strong>Run</strong> or <strong>Debug</strong> toolbar button 
  will launch the selected resource (as will the <strong>Run</strong> or <strong>Debug</strong> 
  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.</p>
<p>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 <code>launchShortcuts</code> extension to associate a 
  launch shortcut with one or more types of launch configurations. For example, 
  this tells the platform that the &quot;Java Application&quot; launch shortcut 
  is associated with &quot;Java Application&quot; launch configurations.</p>
<p>The contextual launch support uses the following approach to determine how 
  a selection or active editor should be launched.</p>
<ol>
  <li>An <code>IResource</code> adapter is retrieved from the selection or active 
    editor (which can be <code>null</code>).</li>
  <li>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).</li>
  <li>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.</li>
  <li>The set of applicable launch configurations is reduced to those that have 
    a resource mapping equal to or contained by the retrieved resource adapter</li>
  <li>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.</li>
  <li>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.</li>
  <li>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).</li>
</ol>
<p>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.</p>
<p>For selection based launching to work well, plug-in providers should ensure 
  the following.</p>
<ol>
  <li>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.</li>
  <li>Launch shortcut extensions should be updated with <code>configurationType</code> 
    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 <code>description</code> 
    attribute. This attribute is used when presenting the user with a list of 
    shortcuts to choose from.</li>
  <li>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.</li>
</ol>
<!-- ############################################## -->
<p>&nbsp;</p>
<h2><a name="HyperlinkDetector">3. Replacing a hard-coded <code>IHyperlinkDetector</code> with an extension</a></h2>
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
<code>SourceViewerConfiguration.getHyperlinkDetectors(ISourceViewer)</code>.
<p>
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:</p>
<ul>
	<li><a href="../../reference/extension-points/org_eclipse_ui_workbench_texteditor_hyperlinkDetectorTargets.html">org.eclipse.ui.workbench.texteditor.hyperlinkDetectorTargets</a></li>
	<li><a href="../../reference/extension-points/org_eclipse_ui_workbench_texteditor_hyperlinkDetectors.html">org.eclipse.ui.workbench.texteditor.hyperlinkDetectors</a></li>
</ul>
<!-- ############################################## -->
<h2><a name="FileBufferPerformance">4. Improve performance when working with file buffers</a></h2>
<p>In earlier versions file buffer manager API methods used to take an <code>IPath</code> 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:</p>
<ul>
  <li><a href="../../reference/api/org/eclipse/core/filebuffers/LocationKind.html#IFILE">IFILE</a></li>
  <li><a href="../../reference/api/org/eclipse/core/filebuffers/LocationKind.html#LOCATION">LOCATION</a></li>
  <li><a href="../../reference/api/org/eclipse/core/filebuffers/LocationKind.html#NORMALIZE">NORMALIZE</a></li>
</ul>
<p>Clients using the deprecated methods are encouraged to adopt the new API in order
to take advantage of the performance improvement.
</p>
<!-- ############################################## -->
<p>&nbsp;</p>
<h2><a name="LaunchDelegate">5. Launch delegate names and descriptions</a></h2>
<p>New attributes have been added to the <code>launchConfigurationTypes</code> 
  and <code>launchDelegates</code> 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.</p>
<p>Clients contributing to the <code>org.eclipse.debug.core.launchConfigruationTypes</code> 
  extension point should define the following new attributes:</p>
<ul>
  <li><code>delegateName</code></li>
  <li><code>delegateDescription</code></li>
</ul>
<p>Clients contributing to the <code>org.eclipse.debug.core.launchDelegates </code>extension 
  point should define the following new attributes:</p>
<ul>
  <li><code>name</code></li>
  <li><code>delegateDescription</code></li>
</ul>

<h2><a name="Compare">6. Support for file buffers added to Compare</a></h2>

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

<ul>
<li>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 
<a href="../../guide/compare_contentviewer.htm">Implementing a Content Viewer</a> section.</li>
<li>Client can enable the use of file buffers by using the SaveableCompareEditorInput. The static method
<code>createFileElement</code> 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 
<a href="../../guide/compare_beyond.htm">Advanced compare techniques</a> section.</li>
</ul>

<h2><a name="Presentation">7. New Minimize/Maximize behavior</a></h2>

<p>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):
</p>
<p>
org.eclipse.ui/ENABLE_MIN_MAX=false
</p>


<h2><a name="MenuContribution">8.  Menu contributions and commands</a></h2>

<p>
Support is now available to place commands in menus and toolbars through the
<a href="../../reference/extension-points/org_eclipse_ui_menus.html">org.eclipse.ui.menus</a>
extension point.
</p>
<p>
<b>org.eclipse.ui.menus</b> 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 <b>org.eclipse.ui.handlers</b> extension
point or the <code>IHandlerService</code>.  
</p>
<p>
In 3.2 placing a command in a toolbar or menu involved using one of the
<code>IActionDelegate</code> extensions and coding the run method to use the
<code>IHandlerService</code> to execute the command.
</p>


</body>
</html>