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.
-
Nested Launch Configuration Working Copies
-
Incompatible source change to getStorage() on FileEditorInput
-
Boot delegation changes
-
Lazy activation changes
-
Clarification to Bundle.getEntryPaths
-
History View didn't follow spec of IHistoryPageSource
-
Proxy settings are now managed by the platform
-
Launching Eclipse with startup.jar
-
Incompatible source change to DeviceResourceDescriptor#createResource
-
Incompatible source change to ResourceManager resource creation methods
-
JFace viewers and recursive back-calls
-
IIDEActionConstants.FIND_EXT corrected to conform to specification
-
IDEEncoding#setResourceEncoding deleted
-
ErrorDialog client area has a potential extra column
-
Binary incompatibility in IIndexEntry
-
Constant changed in FormColors
-
UI ActionHandler depends on IAction#ENABLED
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:
- Imported packages (i.e. packages specified in the Import-Package manifest header).
- Required bundles (i.e. bundles specified in the Require-Bundle manifest header).
- Local bundle and fragments.
- 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.
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.
- 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.
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.