Eclipse changed in incompatible ways between 3.0 and 3.1 in ways that affect plug-ins. The following entries describe the areas that changed and provide instructions for migrating 3.0 plug-ins to 3.1. Note that you only need to look here if you are experiencing problems running your 3.0 plug-in on 3.1.
What is affected: Plug-ins who initialize their default plug-in preference values by over-riding Plugin#initializeDefaultPreferences
or
use preference change listeners.
Description: In Eclipse 3.1 the org.eclipse.jface.preference.IPreferenceStore
object obtained from org.eclipse.ui.plugin.AbstractUIPlugin#getPreferenceStore
was migrated to live on top of the new 3.0 Eclipse preference framework supplied
by the org.eclipse.core.runtime
plug-in.
Action required: As a result, clients using the preference APIs should check for two possible issues:
String
, or a typed object. Therefore to be
a good client, preference change listeners should be able to handle all three of these possible situations.org.eclipse.ui.plugin.AbstractUIPlugin#initializeDefaultPreferences
then
you must be sure to include the org.eclipse.core.runtime.compatibility
plug-in in your plug-in's list
of required plug-ins as this dependancy has been removed from the org.eclipse.ui.workbench
plug-in.See the preference store documentation for more details.
What is affected: Plug-ins that create, manipulate, or store IPath objects.
Description: In Eclipse 3.0, IPath had a number of restrictions on the segments of paths that were more restrictive than the restrictions of the underlying operating system. These included:
These restrictions have been removed in Eclipse 3.1 when the platform's data location (workspace) is located on a file system that does not have these restrictions.
Action required: In order to enable the proper treatment of the expanded range of paths, all usage of Path and IPath within plug-ins should be reviewed and updated as described below. Most unmodified plug-ins will continue to behave exactly as in 3.0 on all paths considered legal in 3.0. However, unless these prescribed changes are made, they are likely to fail in cases involving paths considered legal in 3.1 that were illegal in 3.0.
Plug-ins that store string representations of paths in a format that needs to be readable across different platforms should migrate to the new Path.fromPortableString factory method. This method produces an IPath instance from a platform-independent format. This string representation of paths can be created using the IPath.toPortableString method. Examples of metadata files that are affected include files that are stored inside Eclipse workspace projects (.project, .classpath, etc), and all paths stored in the preference store (org.eclipse.core.runtime.preferences.IPreferencesService).
Note: fromPortableString will correctly read all path strings that were created using the Eclipse 3.0 IPath.toString method, but not the Eclipse 3.1 toString method. Thus in most cases no change is required to existing metadata file formats except to begin writing paths with toPortableString and reading paths with fromPortableString.
Plug-ins that were creating paths from hard-coded string literals that assumed ':' and '\' had special meaning on all platforms will need to migrate. The easiest solution is to restrict string path literals to the subset that is supported on all platforms (avoid colon and backslash characters). Path literals can support the complete set of valid Unix paths by using the portable path string format produced by Path.toPortableString. This format interprets the first single colon (':') as the device separator, slash ('/') as the segment separator, and double colon ("::") as a literal colon character. For example, the code new Path("c:/temp") will now create a relative path with two segments on Unix platforms. Similarly, new Path("a\\b") will now create a path with a single segment on Unix platforms, and a path with two segments on Windows.
Plug-ins constructing paths using the IPath.append(String) method that assumed ':' and '\' had special meaning on all platforms may need to update their code. In Eclipse 3.1, this method uses operating-system specific device and segment delimiters to interpret the provided path string. For example, calling append("a\\b") on Unix platforms will now append a single segment, whereas on Windows it will continue to append two segments.
Any data files read and interpreted by the platform will no longer treat ':' and '\' as special characters on all platforms. All paths stored in data files that can be read on multiple platforms must be in portable form. For example, paths of icon files and other paths in plugin.xml must use only '/' as the path segment separator.
What is affected: Plug-ins that manipulate or retain IExtensionPoint
,
IExtension
, and IConfigurationElement
objects from the
Eclipse Platform's plug-in or extension registry.
Description: Prior to 3.0, all objects obtained from the extension
registry (of the former plug-in registry) were good forever. Changes were made
in Eclipse 3.0 that allowed plug-ins to be dynamically added or removed without
having to restart Eclipse. When a plug-in is removed without restarting, its
entries in the extension registry necessarily become invalid. This means that
another plug-in holding on to an object obtained previously from the deleted
plug-in's extension registry entry would be left holding an invalid object. The
only hint that a client could get would be from listening to IRegistryChangeEvent
.
The problem has existed since Eclipse 3.0, but is rarely encountered in practice
because it is highly unusual for a plug-in to be removed without restarting
Eclipse.
This problem has been addressed in 3.1 by:
IExtensionPoint
, IExtension
,
and IConfigurationElement
now specify that InvalidRegistryObjectException
will be thrown when the object is invalid. The exception is unchecked so
that dynamic unaware clients are not forced to check it.isValid()
method was added to these interfaces so that
a client can determine whether an object is still valid.Action required: If your plug-in needs to be dynamic-aware (i.e.
capable of dealing with the on-the-fly addition or removal of plug-ins), the
code that deals with IExtensionPoint
, IExtension
, and IConfigurationElement
object sourced from some other plug-in must be changed to catch IRegistryChangeEvent
,
exactly as if it were a checked exception. Catching the exception (rather than
an isValid()
pre-check) is the only surefire way to deal with the
case of a plug-in being removed by a concurrent thread (which, if it happens, it
almost certainly will be).
What is affected: Plug-ins that programmatically access the Java code formatter options.
Description: In Eclipse 3.0, the values for the code formatter option
org.eclipse.jdt.core.formatter.DefaultCodeFormatterConstants#FORMATTER_TAB_CHAR
could only be TAB
or SPACE
. The specification made
no explicit mention that the value type was an enumeration that might grow in
future releases. In Eclipse 3.1, a third possible value, MIXED
,
was added to address bug 73104.
The specification has been changed to include this new value, and to allow for
more values being added in the future.
Action required: Clients programmatically reading or setting this code formatter option should check their code to take account of the new third value, and to ensure that it is written in a robust way that fails gracefully if it ever encounters an option value that it did not anticipate.
What is affected: Plug-ins that subclass or instantiate org.eclipse.ant.core.AntCorePreferences
Description: In Eclipse 3.0, the class org.eclipse.ant.core.AntCorePreferences
was not marked that clients may not instantiate or subclass.
This was an oversight that has been addressed in Eclipse 3.1 with the class marked as not intended to be subclassed or instantiated.
Action required: Clients programmatically creating an instance of org.eclipse.ant.core.AntCorePreferences
should migrate their code to retrieve the preferences using: org.eclipse.ant.core.AntCorePlugin.getPreferences()
.
Any subclass will need to be reworked to no longer subclass org.eclipse.ant.core.AntCorePreferences
.
What is affected: RCP applications that override the JFace log set by the workbench.
Description: In Eclipse 3.0, the workbench set the workbench's log as
the log to use for logging JFace errors, by passing the workbench plug-in's
log directly to org.eclipse.jface.util.Policy.setLog(ILog)
. In
3.1, the dependency on ILog
has been removed from JFace in order
to enable standalone applications using SWT and JFace outside of the eclipse
runtime. A new interface, ILogger
, has been introduced to meet
JFace's needs. The workbench has been changed to provide an ILogger
wrapping the workbench ILog
. For further details, see bug 88608.
Action required: Most RCP applications should not need to override the
log set by the workbench, but if they previously called Policy.setLog(ILog)
,
they will need to be changed to pass an ILogger
instead.
What is affected: RCP applications expecting a non-null default perspective.
Description: In order to allow RCP applications to start with an empty
window with no perspectives open (enhancement 71150),
WorkbenchAdvisor.getInitialWindowPerspectiveId()
and IPerspectiveRegistry.getDefaultPerspective()
have been changed to allow null to be returned. In the IDE, there is always
a default perspective, so IPerspectiveRegistry.getDefaultPerspective()
will not return null. Similarly, if an existing RCP app previously returned
a non-null value from WorkbenchAdvisor.getInitialWindowPerspectiveId()
,
then IPerspectiveRegistry.getDefaultPerspective()
will still return
a non-null value.
Action required: No action should be required by clients.
What is affected: Plug-ins that implement org.eclipse.ui.IViewLayout.
Description: In Eclipse 3.0, the class org.eclipse.ui.IViewLayout
was not marked that clients may not implement. This was an oversight that has
been addressed in Eclipse 3.1 with the class marked as not intended to be implemented
by clients.
Action required: Any implementing classes will need to be reworked to
no longer implement org.eclipse.ui.IViewLayout
.
What is affected: Plug-ins that implement org.eclipse.jdt.launching.IVMInstall.
Description: In Eclipse 3.0, the class org.eclipse.jdt.launching.IVMInstall
was not marked that clients may not implement directly. This was an oversight
that has been addressed in Eclipse 3.1 with the class marked as not intended
to be implemented directly by clients. To maintain binary compatibility, we
still allow clients to implement the interface directly, but strongly recommend
that clients subclass org.eclipse.jdt.launching.AbstractVMInstall
instead. Clients that implement IVMInstall
should also implement
the new optional interface org.eclipse.jdt.launching.IVMInstall2
,
which AbstractVMInstall
now implements. It is recommended that
clients implement the new interface, IVMInstall2
, to avoid the
problem noted in bug 73493. The recommended migration is to subclass AbstractVMInstall
.
Action required: Any implementing classes that do not already subclass
org.eclipse.jdt.launching.AbstractVMInstall
should be reworked
to subclass org.eclipse.jdt.launching.AbstractVMInstall.
What is affected: Plug-ins that use org.eclipse.ui.SelectionEnabler.SelectionClass.
Description: In Eclipse 3.0, the nested implementation class org.eclipse.ui.SelectionEnabler.SelectionClass
was public, with no restrictions on its usage. This was an oversight that has
been addressed in Eclipse 3.1 with the class being made package-visible.
Action required: Any classes instantiating or extending org.eclipse.ui.SelectionEnabler.SelectionClass
will need to be reworked to no longer refer to this class.
What is affected: Plug-ins that call getParent()
on a subclass
of org.eclipse.jface.action.ContributionItem.
Description: In Eclipse 3.0, method org.eclipse.jface.action.ContributionItem.getParent()
did not specify that it could return null. This was an oversight that has been
addressed in Eclipse 3.1 with Javadoc for the method clarifying when it can
return null. For more details, see bug 92777.
Action required: Any code calling ContributionItem.getParent() must ensure that it can handle a null result.
What is affected: Plug-ins that implement org.eclipse.ui.views.properties.IPropertySource
or IPropertySource2.
Description: In Eclipse 3.0, the specification for the method org.eclipse.ui.views.properties.IPropertySource.isPropertySet(boolean)
was incorrectly changed to specify that true should be returned if the specified
property did not have a meaningful default value. In previous versions, it specified
that false should be returned in this case. This was an inadvertent breaking
API change, although the implementation worked the same as before if the property
source implemented IPropertySource
and not IPropertySource2
.
This has been corrected in 3.1, with IPropertySource.isPropertySet(boolean)
being reverted back to its earlier specification (that false should be returned
in this case), and IPropertySource2.isPropertySet(boolean) overriding this to
specify that true should be returned in this case. For more details, see bug
21756.
Action required: Any classes implementing IPropertySource or IPropertySource2, where some of the properties do not have meaningful default values, should be checked to ensure that they return the appropriate value for isPropertySource(boolean). Clients should check that the Restore Default Value button in the Properties view works as expected for their property source.
What is affected: Plug-ins that used the experimental
handlerSubmission
element introduced into the
org.eclipse.ui.commands
extension point Eclipse 3.0.
Description: In Eclipse 3.0, an experimental element was introduced
into the org.eclipse.ui.commands
extension point. This element was
intended as a way to register handlers through XML. Since then, a far superior
mechanism, the org.eclipse.ui.handlers
extension point, has been
introduced. Since the element was marked as experimental, it has now been
removed.
Action required: Any plug-ins defining a
handlerSubmission
element should migrate to the
org.eclipse.ui.commands
extension point.
What is affected: Plug-ins that were setting the GLOBAL_IGNORES_CHANGED field of TeamUI.
Description: In Eclipse 3.0, the GLOBAL_IGNORES_CHANGED field was added to the TeamUI class. This field is a constant that is used in a property change event to indicate that the list of global ignores maintained by the Team plugin has changed. This field was not marked final in 3.0 but should have been. It has been made final in 3.1.
Action required: Any plugins that were setting the above field can no longer do so.
What is affected: Plug-ins that incorrectly use FillLayout.
Description: In Eclipse 3.0, no layout data was associated with the FillLayout and if an application assigned layout data to a child that was managed by a FillLayout, it was ignored. In Eclipse 3.1, support was added to FillLayout to cache size information in order to improve resize performance. The cached data is stored in a FillData object associated with each child managed by the FillLayout. If an application has incorrectly assigned layout data to a child, a ClassCastException will be thrown when computeSize is called on the parent.
Action required: Find any children in a FillLayout that have layout data assigned and stop assigning the layout data.
What is affected: Plug-ins that catch exceptions while creating widgets.
Description: In Eclipse 3.0, if a widget was created with a disposed parent, no exception was thrown and the widget code failed at a later point or an SWTException with text "Widget Is Disposed" was thrown. In Eclipse 3.1, if a widget is created with a disposed parent, the constructor will throw an IllegalArgumentException with text "Argument not valid".
Action required:Any code that handles the SWTException when creating a widget will also need to handle the IllegalArgumentException.