# Incompatibilities between Eclipse 3.2 and 3.3

Eclipse changed in incompatible ways between 3.2 and 3.3 in ways that affect plug-ins. The following entries describe the areas that changed and provide instructions for migrating 3.2 plug-ins to 3.3. Note that you only need to look here if you are experiencing problems running your 3.2 plug-in on 3.3.

1. Nested Launch Configuration Working Copies
2. Incompatible source change to getStorage() on FileEditorInput
3. Boot delegation changes
4. Lazy activation changes
5. Clarification to Bundle.getEntryPaths
6. History View didn't follow spec of IHistoryPageSource
7. Proxy settings are now managed by the platform
8. Launching Eclipse with startup.jar
9. Incompatible source change to DeviceResourceDescriptor#createResource
10. Incompatible source change to ResourceManager resource creation methods
11. JFace viewers and recursive back-calls
12. IIDEActionConstants.FIND_EXT corrected to conform to specification
13. IDEEncoding#setResourceEncoding deleted
14. ErrorDialog client area has a potential extra column
15. Binary incompatibility in IIndexEntry
16. Constant changed in FormColors
17. UI ActionHandler depends on IAction#ENABLED

## 1. Nested Launch Configuration Working Copies

What is affected: Launch configuration working copies support nesting in 3.3. Clients that programmatically create and save launch configurations may be affected by the change in behavior of the `ILaunchConfigurationWorkingCopy.doSave()` method.

Description: When a working copy (B) is created from a working copy (A) which was created from a launch configuration (X), the newly created working copy (B) is initialized with the attributes from the first working copy (A). In 3.3, whenever a working copy is saved, it is written back to the configuration from which it was created. In this example working copy B will saves changes back to working copy A, and A will save changes back to the original launch configuration. A nested working copy has a parent working copy that can be retrieved by calling `getParent()` (newly added in 3.3). In 3.2, working copies were not nested and saving a working copy always resulted in the changes being saved back to the original launch configuration.

Action required: APIs are binary compatible but clients should examine calls to `ILaunchConfiguration.getWorkingCopy()` and `ILaunchConfigurationWorkingCopy.doSave()` to determine if nested working copies might be created. Note that saving a nested working copy will not save changes back to the original launch configuration.

## 2. Incompatible source change to getStorage() on FileEditorInput

What is affected: Clients that call getStorage() on FileEditorInput.

Description: The signature of getStorage() was changed to no longer throw a checked exception. This may cause compile errors in source code previously compiled against Eclipse 3.2 that is recompiled against 3.3. This change does not break binary compatibility - existing clients built against Eclipse 3.2 or earlier will continue to function normally.

Action required: Clients should recompile against Eclipse 3.3, and remove any catch block that is now unnecessary due to the removed exception.

## 3. Boot delegation changes

What is affected: The boot delegation order has changed in 3.3. Bundles that depend on delegating to the boot (parent) class loader first may be affected by this change.

Description: In Eclipse 3.3 the default class loader delegation model has been changed to the following order:

1. Imported packages (i.e. packages specified in the Import-Package manifest header).
2. Required bundles (i.e. bundles specified in the Require-Bundle manifest header).
3. Local bundle and fragments.
4. Boot (parent) class loader as a last resort. This is only done if no source was found in the previous steps.

In 3.2 the boot (parent) class loader is always delegated to first. This provides no isolation from the classes provided by the VM. It also affects performance because the boot class loader must be delegated to for every load even though it is known that the class or resource is located in a bundle. Because of the boot delegation changes in 3.3, a bundle can now provide their own version of a package which is also available from the VM boot classpath. See bug 162231.

Action required: Bundles that export packages which may be available by the boot (parent) class loader need to evaluate whether the classes/resources they export should be added to the content from the boot class loader or replace it. If the exporting bundle should replace the content of the boot class loader then no action is required. If the exporting bundle should add to the content of the boot class loader then the exporting bundle should add "system.bundle" as a required bundle (i.e. Require-Bundle: system.bundle). To revert back to the behavior in 3.2 the configuration property "org.osgi.framework.bootdelegation=*" can be added to the config.ini file.

## 4. Lazy activation changes

What is affected: Bundles that use the lazy activation policy (i.e. "Eclipse-LazyStart: true") will enter the Bundle.STARTING state as soon as they are eligible for lazy activation. Clients that monitor the Bundle.STARTING state may be affected by this change.

Description: Eclipse 3.3 implements the OSGi R4.1 specification. The OSGi R4.1 specification standardizes the lazy activation policy implemented in Eclipse. Part of the standardization work changed the behavior of how bundles states are transitioned when a lazy activation policy is used. When a bundle becomes available for lazy activation the bundle enters the Bundle.STATING state and a BundleEvent.LAZY_ACTIVATION event is fired. This occurs before any class load request is made to the bundle. The bundle will remain in the Bundle.STARTING state until the first class load is made and the bundle is activated. When the bundle is activated a BundleEvent.STARTING event is fired and the BundleActivator.start method is called. See bug 135885.

Bundles with a lazy activation policy could remain in the Bundle.STARTING state for a long time waiting for the first class load (trigger load) to occur. Entering the Bundle.STARTING state does not mean the BundleActivator.start method has been called. The BundleActivator.start method is only called right after the BundleEvent.STARTING event is fired. Bundles that monitor calls to BundleActivators must use a SynchronousBundleListener to listen for the BundleEvent.STARTING and BundleEvent.STOPPING events.

Action required: A SynchronousBundleListener must be used to monitor BundleEvent.STARTING and BundleEvent.STOPPING events for clients that are monitoring the calls to BundleActivators.

## 5. Clarification to Bundle.getEntryPaths

What is affected: Clients of the Bundle.getEntryPaths method.

Description: The OSGi R4.1 specification has made a clarification on the behavior of the org.osgi.framework.Bundle#getEntryPaths method. The javadoc for the method Bundle#getEntryPaths did not make it clear whether the String paths returned had a leading "/" character or not. The following clarification has been made:

The returned paths are all relative to the root of this bundle and must not begin with "/".

Eclipse 3.2 had a bug for directory (non-jarred) bundles where a leading "/" character was included in the result if the client used a path argument that contained a leading "/". For jarred bundles Eclipse 3.2 always ensures the returned paths do not have a leading "/" character. This is inconsistent behavior. Directory bundles have been fixed to be consistent with jarred bundles. See bug 174101.

Action required: Some clients may have a dependency on the old behavior for directory bundles. If a client uses the method Bundle#getEntryPaths then ensure that it can handle returned paths that do not begin with a "/" character. This dependency is a bug in the client code because it would have failed for jarred bundles.

## 6. History View didn't follow spec of IHistoryPageSource

What is affected: The History view may no longer show the history for certain elements.

Description: In 3.2, the History view did not follow the specification of IHistoryPageSource in the sense that, in some situations, it did not call canShowHistoryFor(Object) before requesting a history page. In 3.3, this was corrected which has lead to a situation where client code may have worked in 3.2 even though their implementation of IHistoryPageSource did not follow the specification in the javadoc.

Action required: Implementors of IHistoryPageSource need to ensure that their implementation follows the specification defined in the javadoc of the interface.

## 7. Proxy settings are now managed by the platform

What is affected: plug-ins in Eclipse that provided their own support for proxy specification (e.g HTTP, SSL or SOCKS).

Description: A preference page and API was added in 3.3 to support the specification of HTTP, SSL and SOCKS proxies. Any tooling that provided their own support for this may conflict with the new settings being managed by the Platform. The fix should be for tooling to remove their support for specifying proxies and adopt the support provided by the Platform.

## 8. Launching Eclipse with startup.jar

What is affected: Eclipse can no longer be started with `java -jar startup.jar`.

Description: In 3.2, Eclipse was started using startup.jar from the root of the Eclipse install. In 3.3, this jar is a bundle in the plugins directory named org.eclipse.equinox.launcher.

Action required: Change the command to `java -jar plugins/org.eclipse.equinox.launcher_1.0.0.<version>.jar` or use the eclipse launcher executable.

## 9. Incompatible source change to DeviceResourceDescriptor#createResource

What is affected: Clients that call createResource(Device) on DeviceResourceDescriptor.

Description: The DeviceResourceException thrown by JFace has been changed to a runtime exception. As part of this change, the method signature of createResource(Device) was changed to no longer throw the exception. This may cause compile errors in source code previously compiled against Eclipse 3.2 that is recompiled against 3.3. This change does not break binary compatibility - existing clients built against Eclipse 3.2 or earlier will continue to function normally.

Action required: Clients should recompile against Eclipse 3.3, and remove any catch block that is now unnecessary due to the removed exception.

## 10. Incompatible source change to ResourceManager resource creation methods

What is affected: Clients that call resource creation methods on ResourceManager.

Description: The DeviceResourceException thrown by JFace has been changed to a runtime exception. As part of this change, the following method signatures were changed to no longer throw the exception.

- ResourceManager#create(DeviceResourceDescriptor)
- ResourceManager#createColor(ColorDescriptor)
- ResourceManager#createColor(RGB)
- ResourceManager#createFont(FontDescriptor)
- ResourceManager#createImage(ImageDescriptor)

These changes may cause compile errors in source code previously compiled against Eclipse 3.2 that is recompiled against 3.3. This change does not break binary compatibility - existing clients built against Eclipse 3.2 or earlier will continue to function normally.

Action required: Clients should recompile against Eclipse 3.3, and remove any catch block that is now unnecessary due to the removed exception.

## 11. JFace viewers and recursive back-calls

What is affected: Clients of `TableViewer` and `TreeViewer`, implementers of `IStructuredContentProvider` or `IBaseLabelProvider`

Description: `StructuredViewer` and its subclasses were never designed to handle recursive back-calls to methods such as `setInput()`, `refresh()`, `add()`, `remove()`, `update()` etc. In the past, calls to one of these update methods that happened while the viewer was already in the process of processing another update, lead to unpredictable behavior or even runtime errors later on that were hard to debug. Starting with 3.3, subclasses of ColumnViewer detect recursive back-calls, log an error and ignore the nested update request. This helps uncover programming errors such as spinning the event loop from a content provider or label provider, but potentially changes the behavior in cases where clients used recursive back-calls but didn't see immediate problems in the past in their particular usage scenarios. See bug 154571 for details.

Action required: No action required if you don't see entries about ignored calls in the .log file. If you do see log entries, the provided stack trace should have sufficient information to find the problematic back-call. Depending on the situation, you might need to post an asyncExec runnable to avoid the back-call.

## 12. IIDEActionConstants.FIND_EXT corrected to conform to specification

What is affected: Clients of `IIDEActionConstants` who use the values directly instead of via the constant.

Description: Edit menu: name of group for extra Find-like actions (value `"find.ext"`).

The value of this constant has changed in 3.3 to match the specification; before 3.3, its value was incorrect (`"cut.ext"`). See bug 155856 for details.

Action required: No action required if you refer to the constant rather than its value.

## 13. IDEEncoding#setResourceEncoding deleted

What is affected: Clients of `IDEEncoding`.

Description: `IDEEncoding#setResourceEncoding` was deprecated in 3.2 (the same release it was added in) in favor of setting the ResourcesPlugin.PREF_ENCODING value in the Resources plug-ins preference store. It was not deleted in the 3.2 release despite never having been valid API. It was deleted in the 3.3 release.

Action required: Update references to `IDEEncoding#setEncoding` to calls to `ResourcesPlugin#getPlugin()#getPluginPreferences()#setValue(ResourcesPlugin.PREF_ENCODING,value)`.

## 14. ErrorDialog client area has a potential extra column

What is affected: Subclasses of `ErrorDialog`.

Description: `ErrorDialogs` will have an extra column in their client area if there is an `ErrorSupportProvider` registered in an install. ErrorDialog subclasses that assume there are 2 columns should call `IconAndMessageDialog#getColumnCount` instead.

Action required: Update hard coded column counts to call to `IconAndMessageDialog#getColumnCount` .

## 15. Binary incompatibility in IIndexEntry

What is affected: Clients of IIndexEntry who rely on binary compatibility.

Description: The return type of function getTopics() has changed from IHelpResource[] to the subclass ITopic[]. See bug 191224 for details.

Action required: Source which uses this interface must be recompiled.

## 16. Constant changed in FormColors

What is affected: Clients of FormColors who rely on binary compatibility.

Description: The value of the constant org.eclipse.ui.forms.FormColors.TB_GBG changed in Eclipse 3.3. See bug 191233 for details.

Action required: Update hard coded column counts to call to `IconAndMessageDialog#getColumnCount` .

## 17. UI ActionHandler depends on IAction#ENABLED

What is affected: Clients using `IKeyBindingService#registerAction(IAction)` or using `org.eclipse.ui.commands.ActionHandler` to submit `IActions` to the handler service.

Description: Commands now add listeners to their handlers. The `ActionHandler` will now depend on the IAction firing the property change for ENABLED to update its enabled state. One side effect is that `IAction#isEnabled()` will not be called frequently.

Action required: Clients must ensure their `IActions` do not require frequent callings of `isEnabled()` to manage their enabled state, and must fire the ENABLED property at the appropriate times.