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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.16 - (view) (download) (as text)

1 : johna 1.1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2 :     <html>
3 :     <head>
4 : dmegert 1.4 <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." >
5 : johna 1.1 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6 :     <meta http-equiv="Content-Style-Type" content="text/css">
7 :     <link rel="STYLESHEET" href="../../book.css" charset="ISO-8859-1" type="text/css">
8 : dmegert 1.4 <title>Adopting 3.3 mechanisms and APIs</title>
9 : johna 1.1 </head>
10 :    
11 :     <body>
12 :    
13 : dmegert 1.4 <h2>Adopting 3.3 mechanisms and APIs</h2>
14 : johna 1.1 <p>This section describes changes that are required if you are trying to change
15 :     your 3.2 plug-in to adopt the 3.3 mechanisms and APIs.</p>
16 :    
17 :     <ol>
18 : twatson 1.2 <li><a href="#AppModel">Application model changes</a></li>
19 : darin 1.3 <li><a href="#ContextLaunch">Launch selection versus launch last</a></li>
20 : darin 1.6 <li><a href="#HyperlinkDetector">Replacing a hard-coded <code>IHyperlinkDetector</code>
21 :     with an extension</a></li>
22 :     <li><a href="#FileBufferPerformance">Improve performance when working with file
23 :     buffers</a></li>
24 :     <li><a href="#LaunchDelegate">Launch delegate names and descriptions</a></li>
25 : mvalenta 1.10 <li><a href="#Compare">Support for file buffers added to Compare</a></li>
26 : emoffatt 1.15 <li><a href="#Presentation">New Minimize/Maximize behavior</a></li>
27 : pwebster 1.16 <li><a href="#MenuContribution">Menu contributions and commands</a></li>
28 : johna 1.1 </ol>
29 :     <hr>
30 :    
31 :     <!-- ############################################## -->
32 : dmegert 1.4 <h2><a name="AppModel">1. Application model changes</a></h2>
33 : twatson 1.2 <p>The Eclipse application container has been moved from <b>org.eclipse.core.runtime</b>
34 :     into the new bundle <b>org.eclipse.equinox.app</b>. The Eclipse application container included in the
35 :     org.eclipse.equinox.app bundle implements the Application Admin Service specification from the OSGi R4 specification.
36 :     </p>
37 :     <p>
38 :     The following extension points have also been moved into the org.eclipse.equinox.app bundle. Note that
39 : johna 1.14 the fully qualified extension point ids are unchanged:</p>
40 : twatson 1.2 <ul>
41 :     <li>org.eclipse.core.runtime.applications</li>
42 :     <li>org.eclipse.core.runtime.products</li>
43 :     </ul>
44 :     The interface <b>org.eclipse.core.runtime.IPlatformRunnable</b> has been deprecated and the
45 :     org.eclipse.equinox.app.IApplication interface should be used instead. IPlatformRunnable is supported for
46 :     backwards compatibility, and clients are encouraged to move to the new IApplication API
47 :     instead.
48 :     <p>
49 :     As a result of the code move, custom configurations and scripts that explicitly
50 :     reference <b>org.eclipse.core.runtime</b> might need to add the <b>org.eclipse.equinox.app</b> bundle.
51 :     </p>
52 : twatson 1.12 <p>See <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=109893">bug 109893</a>
53 : darin 1.3 for more details. </p>
54 : dmegert 1.4 <!-- ############################################## -->
55 : dmegert 1.5 <p>&nbsp;</p>
56 : dmegert 1.4 <h2><a name="ContextLaunch">2. Launch selection versus launch last</a></h2>
57 : darin 1.3 <p>By default, running and debugging applications has been simplified to run or
58 :     debug the selected file or active editor. When the selected resource (or active
59 :     editor) is not executable, users can opt to launch the associated project or
60 :     re-launch the previous launch. These settings are managed on the <strong>Run/Debug
61 :     &gt; Launching</strong> preference page. Users can also revert to the 3.2 behavior
62 :     of always launching the previous application.</p>
63 :     <p>Pressing the <strong>Run</strong> or <strong>Debug</strong> toolbar button
64 :     will launch the selected resource (as will the <strong>Run</strong> or <strong>Debug</strong>
65 :     action in the top level Run menu). When no launch configuration exists for a
66 :     file and there is only one way to launch it, the file will simply be launched
67 :     in the mode selected. When there is more than one way to launch a file, the
68 :     user will be prompted to select how to run or debug the application. For example,
69 :     when running a JUnit test it can be run as a Java application or JUnit test.
70 :     A launch configuration will be created and an entry will be added to the launch
71 :     history for the application. When the same resource is launched again, it will
72 :     use the most recent configuration in the launch history associated with that
73 :     resource.</p>
74 :     <p>The underlying infrastructure for selection based launching relies on the launch
75 :     shortcuts applicable to a resource (or editor) and the resource mappings associated
76 :     with existing launch configurations. As well, API (a new extension element)
77 :     has been added to the <code>launchShortcuts</code> extension to associate a
78 :     launch shortcut with one or more types of launch configurations. For example,
79 :     this tells the platform that the &quot;Java Application&quot; launch shortcut
80 :     is associated with &quot;Java Application&quot; launch configurations.</p>
81 :     <p>The contextual launch support uses the following approach to determine how
82 :     a selection or active editor should be launched.</p>
83 :     <ol>
84 :     <li>An <code>IResource</code> adapter is retrieved from the selection or active
85 :     editor (which can be <code>null</code>).</li>
86 :     <li>A set of applicable launch configuration types are computed from the set
87 :     of launch shortcuts applicable to the selection/editor (using the new launch
88 :     configuration type elements defined by launch shortcuts).</li>
89 :     <li>A set of applicable launch configurations is computed based on the launch
90 :     configuration types applicable to the selection/editor and the existing launch
91 :     configurations in the workspace.</li>
92 :     <li>The set of applicable launch configurations is reduced to those that have
93 :     a resource mapping equal to or contained by the retrieved resource adapter</li>
94 :     <li>The set of applicable launch configurations is compared to the launch history
95 :     and the most recently launched configuration in the set is selected for launching.</li>
96 :     <li>When there are applicable launch configurations, but none are in the recent
97 :     launch history, the user is prompted to select one of the applicable configurations
98 :     to launch.</li>
99 :     <li>When there are applicable launch shortcuts and no applicable launch configurations,
100 :     the user is prompted on how they want to launch the selection (i.e. which
101 :     shortcut they want to use).</li>
102 :     </ol>
103 :     <p>When there are no applicable launch configurations or launch shortcuts, the
104 :     platform either attempts to launch the associated project or launches last,
105 :     based on user preference settings. When the user has chosen to launch the associated
106 :     project, the same steps as above are followed, except the resource used is the
107 :     project.</p>
108 :     <p>For selection based launching to work well, plug-in providers should ensure
109 :     the following.</p>
110 :     <ol>
111 :     <li>Resource mappings for launch configurations should be scoped to the appropriate
112 :     resource. For example, to support projects with multiple Java executables,
113 :     Java application launch configurations are associated with the the .java file
114 :     containing the main class.</li>
115 :     <li>Launch shortcut extensions should be updated with <code>configurationType</code>
116 :     elements so the platform can infer which launch configuration types to consider
117 : darin 1.9 when resolving launch configurations applicable to a selection/editor. As
118 :     well, launch shortcuts should be updated with the new <code>description</code>
119 :     attribute. This attribute is used when presenting the user with a list of
120 :     shortcuts to choose from.</li>
121 : darin 1.3 <li>Launch configuration migration delegates should be updated to create appropriate
122 :     resource mappings for existing launch configurations. For example, if launch
123 :     your launch configuration resource mappings in 3.2 were always associated
124 :     with a project, but now you want to associated them with specific files in
125 :     a project to better support context launching, your migration delegate should
126 :     be updated to update resource mappings.</li>
127 :     </ol>
128 : dmegert 1.4 <!-- ############################################## -->
129 : dmegert 1.5 <p>&nbsp;</p>
130 : dmegert 1.4 <h2><a name="HyperlinkDetector">3. Replacing a hard-coded <code>IHyperlinkDetector</code> with an extension</a></h2>
131 :     Before 3.3 it was not possible to contribute hyperlink detectors to existing source viewers and textual editors. Only
132 :     their implementors could add them directly through code by providing their hyper link detectors via
133 :     <code>SourceViewerConfiguration.getHyperlinkDetectors(ISourceViewer)</code>.
134 :     <p>
135 :     As of 3.3, clients can define hyperlink detector targets for their viewers and editors and they can contribute
136 : johna 1.14 their own hyperlink detectors to such targets via the following extension points:</p>
137 : dmegert 1.4 <ul>
138 :     <li><a href="../../reference/extension-points/org_eclipse_ui_workbench_texteditor_hyperlinkDetectorTargets.html">org.eclipse.ui.workbench.texteditor.hyperlinkDetectorTargets</a></li>
139 :     <li><a href="../../reference/extension-points/org_eclipse_ui_workbench_texteditor_hyperlinkDetectors.html">org.eclipse.ui.workbench.texteditor.hyperlinkDetectors</a></li>
140 :     </ul>
141 : dmegert 1.5 <!-- ############################################## -->
142 :     <h2><a name="FileBufferPerformance">4. Improve performance when working with file buffers</a></h2>
143 : johna 1.14 <p>In earlier versions file buffer manager API methods used to take an <code>IPath</code> and it was
144 : dmegert 1.5 up to the file buffer manager to detect whether that path pointed to a workspace or an external location.
145 :     Those API methods have been deprecated in 3.3 in order to improve performance as in most cases clients already
146 : johna 1.13 know whether their path is a workspace path or an external path. New methods with same names have been added
147 : johna 1.14 that take one of the following location kind arguments:</p>
148 : dmegert 1.5 <ul>
149 : johna 1.13 <li><a href="../../reference/api/org/eclipse/core/filebuffers/LocationKind.html#IFILE">IFILE</a></li>
150 : darin 1.7 <li><a href="../../reference/api/org/eclipse/core/filebuffers/LocationKind.html#LOCATION">LOCATION</a></li>
151 :     <li><a href="../../reference/api/org/eclipse/core/filebuffers/LocationKind.html#NORMALIZE">NORMALIZE</a></li>
152 :     </ul>
153 : johna 1.14 <p>Clients using the deprecated methods are encouraged to adopt the new API in order
154 : johna 1.13 to take advantage of the performance improvement.
155 :     </p>
156 : dmegert 1.8 <!-- ############################################## -->
157 :     <p>&nbsp;</p>
158 : darin 1.6 <h2><a name="LaunchDelegate">5. Launch delegate names and descriptions</a></h2>
159 :     <p>New attributes have been added to the <code>launchConfigurationTypes</code>
160 :     and <code>launchDelegates</code> extension points to provide names and descriptions
161 :     for launch delegates. Since 3.3, the debug platform allows for more than one
162 :     launcher to be contributed for the same kind of launch configuration type and
163 :     launch mode. When more than one launcher is available the user must choose a
164 :     preferred launcher and is presented with names and descriptions of available
165 :     launchers. Clients contributing launch delegates with either of these extension
166 :     points are encouraged to provide meaningful names and descriptions.</p>
167 :     <p>Clients contributing to the <code>org.eclipse.debug.core.launchConfigruationTypes</code>
168 :     extension point should define the following new attributes:</p>
169 :     <ul>
170 :     <li><code>delegateName</code></li>
171 :     <li><code>delegateDescription</code></li>
172 :     </ul>
173 :     <p>Clients contributing to the <code>org.eclipse.debug.core.launchDelegates </code>extension
174 :     point should define the following new attributes:</p>
175 :     <ul>
176 :     <li><code>name</code></li>
177 :     <li><code>delegateDescription</code></li>
178 :     </ul>
179 : mvalenta 1.10
180 :     <h2><a name="Compare">6. Support for file buffers added to Compare</a></h2>
181 :    
182 :     <p>Compare editors can now be configured to use the same file buffers that are used by regular editors.
183 :     This means that changes made in a compare editor will immediately be reflected in any other
184 :     editor on the same file buffer or vice versa. Both the compare client and the provider of the compare
185 : johna 1.14 viewer must make changes to enable this feature.</p>
186 : mvalenta 1.10
187 :     <ul>
188 :     <li>In order for compare viewer providers to enable this feature, they must subclass TextMergeViewer and
189 :     override both the getDocumentPartitioning and getDocumentPartitioning methods if they provide custom syntax highlighting.
190 :     File buffer support in the basic TextMergeViewer is enabled. It is only subclasses that provide syntax highlighting that
191 :     need to makes changes to adopt the feature. Also, providers of structure creators should subclass StructureCreator and
192 :     override the getDocumentPartition and getDocumentPartitioning in order for their structure merge viewer to use the file buffer
193 :     as well. This is described in more detail in the
194 :     <a href="../../guide/compare_contentviewer.htm">Implementing a Content Viewer</a> section.</li>
195 :     <li>Client can enable the use of file buffers by using the SaveableCompareEditorInput. The static method
196 :     <code>createFileElement</code> can be used to create a typed element that wraps a file in order to enable the
197 :     file buffer support for the file. This is described in more detail in the
198 :     <a href="../../guide/compare_beyond.htm">Advanced compare techniques</a> section.</li>
199 : aniefer 1.11 </ul>
200 : emoffatt 1.15
201 :     <h2><a name="Presentation">7. New Minimize/Maximize behavior</a></h2>
202 :    
203 :     <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):
204 :     </p>
205 :     <p>
206 :     org.eclipse.ui/ENABLE_MIN_MAX=false
207 :     </p>
208 :    
209 : pwebster 1.16
210 :     <h2><a name="MenuContribution">8. Menu contributions and commands</a></h2>
211 :    
212 :     <p>
213 :     Support is now available to place commands in menus and toolbars through the
214 :     <a href="../../reference/extension-points/org_eclipse_ui_menus.html">org.eclipse.ui.menus</a>
215 :     extension point.
216 :     </p>
217 :     <p>
218 :     <b>org.eclipse.ui.menus</b> focuses on the appearance (label, tooltip, icon),
219 :     location, and visibility of the command in the menu or toolbar. Command
220 :     enabled state is still controlled via the <b>org.eclipse.ui.handlers</b> extension
221 :     point or the <code>IHandlerService</code>.
222 :     </p>
223 :     <p>
224 :     In 3.2 placing a command in a toolbar or menu involved using one of the
225 :     <code>IActionDelegate</code> extensions and coding the run method to use the
226 :     <code>IHandlerService</code> to execute the command.
227 :     </p>
228 :    
229 :    
230 : johna 1.1 </body>
231 :     </html>