# Changes required when adopting 3.2 mechanisms and APIs

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.

1. Launch configurations
2. Launch Modes
3. International Components for Unicode for Java (ICU4J)
4. Runtime split

## Launch configurations

### Launch configuration resource mapping

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.

It is a client responsibility to manage the resource mapping for launch configurations. API has been added to `ILaunchConfigurationWorkingCopy` to set the resources associated with a configuration, and API has been added to `ILaunchConfiguration` 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.

### Launch configuration migration support

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 Run/Debug > Launching > Launch Configurations preference page, by pressing the Migrate button.

A new optional migration delegate attribute has been added to the `launchConfigurationTypes` extension point, specifying a class that implements the new interface `ILaunchConfigurationMigrationDelegate`. A migration delegate is responsible for identifying migration candidates and migrating them.

## Launch Modes

A new optional attribute has been added to the `launchModes` 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 `launchAsLabel`. 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 "`{0} As`". See related bug 105235.

## International Components for Unicode for Java (ICU4J)

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 com.ibm.icu. The Eclipse platform will be utilizing ICU APIs in Eclipse 3.2.

### Migration

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 ICU4J page on the Eclipse wiki for more details on how to migrate your code to use ICU4J.

### ICU4J Replacement Plug-in

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 (com.ibm.icu.base) is available from the Eclipse platform build page. Download the plug-in, remove the com.ibm.icu 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 ICU4J page on the Eclipse wiki for more details using the ICU replacement plug-in.

### Effect on JFace - ViewerSorter and StructuredViewer

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:

1. a new class called `org.eclipse.jface.viewers.ViewerComparator`, of which `org.eclipse.jface.viewers.ViewerSorter` is now a subclass.
2. two new methods to `org.eclipse.jface.viewers.StructuredViewer`, to support the addition of `org.eclipse.jface.viewers.ViewerComparator`.

#### Rationale

The `ViewerSorter` class has a public method `getCollator()` that returns a `java.text.Collator`. 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 `ViewerComparator` class that uses a `java.util.Comparator`, rather than an ICU Collator, was added. This was done because ICU's Collator class implements `java.util.Comparator`, so any `StructuredViewer` can now use ICU's Collator rather than `java.text.Collator`, but JFace doesn't have to add a dependency on the ICU4J plug-in. The two new methods added to `StructuredViewer` support using ICU's Collator to sort the contents of the viewer via a `ViewerComparator`, rather than a `ViewerSorter`. It is recommended that any `StructuredViewer` now use these methods to get/set the viewer's sorter (comparator), instead of the `getSorter()` and `setSorter(ViewerSorter)` methods.

- `public ViewerComparator getComparator()`
- `public void setComparator(ViewerComparator comparator)`

## Runtime split

### New runtime APIs

The org.eclipse.equinox.common bundle includes several new API classes (e.g., `Assert` and `ListenerList`) 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:

       The type ABC is ambiguous

Organizing the imports and choosing the appropriate import source should resolve this problem.

### Explicit class paths in the custom build scripts

As a result of the code being moved into new runtime plug-ins, custom scripts that explicitly references org.eclispe.core.runtime might need to add one or more of the following plug-ins:

- org.eclipse.equinox.common
- org.eclipse.equinox.registry
- org.eclipse.equinox.preferences
- org.eclipse.core.jobs
- org.eclipse.core.contenttype