| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <html> |
| |
| <head> |
| |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2006. 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"> |
| <script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> |
| <title>Changes required when adopting 3.2 mechanisms and APIs</title> |
| </head> |
| |
| <body> |
| |
| <h1>Changes required when adopting 3.2 mechanisms and APIs</h1> |
| <p>This section describes changes that are required if you are trying to change |
| your 3.1 plug-in to adopt the 3.2 mechanisms and APIs.</p> |
| |
| <ol> |
| <li><a href="#launchConfigs">Launch configurations</a></li> |
| <li><a href="#launchModes">Launch Modes</a></li> |
| <li><a href="#icuJava">International Components for Unicode for Java (ICU4J)</a></li> |
| <li><a href="#runtimeSplit">Runtime split</a></li> |
| </ol> |
| <h2><a name="launchConfigs">Launch configurations</a></h2> |
| <h3>Launch configuration resource mapping</h3> |
| <p>Eclipse 3.2 provides new infrastructure for associating launch configurations |
| with resources. This mapping allows the platform to perform resource based filtering |
| on launch configurations and allows the platform to optionally delete launch |
| configurations when an associated project is deleted. The launch dialog has |
| been enhanced to support a set of filters to optionally hide configurations |
| associated with closed and deleted projects. As well, the launch dialog supports |
| filtering based on selected working sets in the active workbench window, which |
| can also be selected in the launch dialog.</p> |
| <p>It is a client responsibility to manage the resource mapping for launch configurations. |
| API has been added to <code>ILaunchConfigurationWorkingCopy</code> to set the |
| resources associated with a configuration, and API has been added to <code>ILaunchConfiguration</code> |
| to get the resources associated with a configuration. For example, launch tabs, |
| launch shortcuts and refactoring participants should be considered when migrating. |
| Code that creates or modifies launch configurations should also update resource |
| mappings.</p> |
| <h3>Launch configuration migration support</h3> |
| <p>Eclipse 3.2 provides new infrastructure for migrating launch configurations |
| to be compatible with new tooling. For example, in Eclipse 3.2, support has |
| been added to perform resource based filter on launch configurations. Launch |
| configurations need to be upgraded to provide resource mappings to leverage |
| this new feature. Users can manually migrate launch configurations in their |
| workspace from the |
| |
| <a class="command-link" href='javascript:executeCommand("org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.debug.ui.LaunchConfigurations)")'> |
| <img src="PLUGINS_ROOT/org.eclipse.help/command_link.png"> |
| <b>Run/Debug > Launching > Launch Configurations</b></a> |
| |
| preference page, by pressing the <strong>Migrate</strong> button.</p> |
| <p>A new optional migration delegate attribute has been added to the <code>launchConfigurationTypes</code> |
| extension point, specifying a class that implements the new interface <code>ILaunchConfigurationMigrationDelegate</code>. |
| A migration delegate is responsible for identifying migration candidates and |
| migrating them.</p> |
| <h2><a name="launchModes">Launch Modes</a></h2> |
| <p>A new optional attribute has been added to the <code>launchModes</code> extension |
| point to properly support the externalization of cascade launch menu action |
| labels. Clients that contribute launch modes should specify the proper label |
| to use for launch cascade menus such as "Run As". The new attribute |
| is named <code>launchAsLabel</code>. Proper labels have been provided by the |
| platform for run, debug and profile launch modes. For backwards compatibility, |
| when the new attribute is unspecified for a launch mode, the cascade menu labels |
| are generated as before, via MessageFormat with "<code>{0} As</code>". |
| See related bug <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=105235">105235</a>.</p> |
| <h2><a name="icuJava">International Components for Unicode for Java (ICU4J)</a></h2> |
| <p>ICU4J is a set of Java libraries that provides more comprehensive support for Unicode, software globalization, and internationalization. In order to provide this functionality to the Eclipse community, ICU4J was added to the platform build for Eclipse 3.2. You will see it in the build as a plug-in named <strong>com.ibm.icu</strong>. The Eclipse platform will be utilizing ICU APIs in Eclipse 3.2. </p> |
| <h3>Migration </h3> |
| <p>Migration of application code can be done incrementally, meaning full adoption of all ICU4J function is not necessary to reap the benefits of using ICU4J. See the <a href="http://wiki.eclipse.org/index.php/ICU4J">ICU4J page</a> on the Eclipse wiki for more details on how to migrate your code to use ICU4J. </p> |
| <h3>ICU4J Replacement Plug-in</h3> |
| <p>The addition of the ICU4J plug-in adds on the order of 3MB to the footprint. Some applications may not want to absorb ICU4J if application size takes precedence over adopting ICU4J function. If this is the case, a replacement plug-in (<strong>com.ibm.icu.base</strong>) is available from the <a href="http://download.eclipse.org/eclipse/downloads/">Eclipse platform build page</a>. Download the plug-in, remove the <strong>com.ibm.icu</strong> plug-in and its source counterpart from the /plugins directory, and drop in the replacement plug-in. This is required because the Eclipse platform adopted the ICU APIs for 3.2 so just removing the ICU plug-in will result in compilation errors in platform code. The replacement plug-in is about 100KB in size and simply calls through to the default JDK's implementation of the most commonly used classes and APIs in ICU4J. Again, you can read the <a href="http://wiki.eclipse.org/index.php/ICU4J">ICU4J page</a> on the Eclipse wiki for more details using the ICU replacement plug-in.</p> |
| <h3>Effect on JFace - ViewerSorter and StructuredViewer </h3> |
| <p> In order to support ICU4J in JFace, some creative API additions were required to prevent referencing ICU classes in API. This resulted in the addition of:</p> |
| <ol> |
| <li>a new class called <code>org.eclipse.jface.viewers.ViewerComparator</code>, of which <code>org.eclipse.jface.viewers.ViewerSorter</code> is now a subclass.</li> |
| <li>two new methods to <code>org.eclipse.jface.viewers.StructuredViewer</code>, to support the addition of <code>org.eclipse.jface.viewers.ViewerComparator</code>.</li> |
| </ol> |
| <h4>Rationale</h4> |
| <p>The <code>ViewerSorter</code> class has a public method <code>getCollator()</code> that returns a <code>java.text.Collator</code>. Since this method is API it could not simply be changed to use an ICU Collator. Also, ICU classes cannot be part of the API (signatures) as a direct plug-in dependency on ICU would prevent JFace from being used standalone (with SWT). To accomodate these constraints, the <code>ViewerComparator</code> class that uses a <code>java.util.Comparator</code>, rather than an ICU Collator, was added. This was done because ICU's Collator class implements <code>java.util.Comparator</code>, so any <code>StructuredViewer</code> can now use ICU's Collator rather than <code>java.text.Collator</code>, but JFace doesn't have to add a dependency on the ICU4J plug-in. |
| |
| The two new methods added to <code>StructuredViewer</code> support using ICU's Collator to sort the contents of the viewer via a <code>ViewerComparator</code>, rather than a <code>ViewerSorter</code>. It is recommended that any <code>StructuredViewer</code> now use these methods to get/set the viewer's sorter (comparator), instead of the <code>getSorter()</code> and <code>setSorter(ViewerSorter)</code> methods. |
| </p> |
| <ul> |
| <li><code>public ViewerComparator getComparator()</code></li> |
| <li><code>public void setComparator(ViewerComparator comparator)</code></li> |
| </ul> |
| |
| <h2><a name="runtimeSplit">Runtime split</a></h2> |
| <h3>New runtime APIs</h3> |
| <p> The <b>org.eclipse.equinox.common</b> bundle includes several new API classes (e.g., <code>Assert</code> and |
| <code>ListenerList</code>) that have common names. If your code has a class with the same name and uses import * |
| statements to import both the local class and classes from the runtime, you might get the following error message:</p> |
| <pre> |
| The type ABC is ambiguous |
| </pre> |
| <p> Organizing the imports and choosing the appropriate import source should resolve this problem.</p> |
| <h3>Explicit class paths in the custom build scripts</h3> |
| <p> As a result of the code being moved into new runtime plug-ins, custom scripts that explicitly |
| references <b>org.eclispe.core.runtime</b> might need to add one or more of the following plug-ins:</p> |
| <ul> |
| <li>org.eclipse.equinox.common</li> |
| <li>org.eclipse.equinox.registry</li> |
| <li>org.eclipse.equinox.preferences</li> |
| <li>org.eclipse.core.jobs</li> |
| <li>org.eclipse.core.contenttype</li> |
| </ul> |
| |
| </body> |
| |
| </html> |
