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.
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.
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.
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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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)
.
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
.
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.
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
.
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.