Incompatibilities between Eclipse 3.0 and 3.1

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.

  1. Plug-in Preferences
  2. Changes to IPath constraints
  3. Extension registry
  4. Code formatter options
  5. API contract changes to AntCorePreferences
  6. API contract changes to Policy class in JFace
  7. API contract changes to allow a null default perspective
  8. API contract changes to IViewLayout
  9. API contract changes to IVMInstall
  10. SelectionEnabler.SelectionClass made package-visible
  11. ContributionItem.getParent() can return null
  12. Changes to isPropertySet(boolean) in IPropertySource and IPropertySource2
  13. handlerSubmission element deleted from the org.eclipse.ui.commands extension point
  14. Static non-final API field GLOBAL_IGNORES_CHANGED in TeamUI made final
  15. ClassCastException using FillLayout
  16. Creating a widget with a disposed parent

1. Plug-in Preferences

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:

  1. The type of the objects contained in preference change events is not guarenteed; both the old value and new value in events can be null, a 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.
  2. If your plug-in uses 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.

2. Changes to IPath constraints

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.

3. Extension registry

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:

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

4. Code formatter options

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.

5. API contract changes to AntCorePreferences

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.

6. API contract changes to Policy class in JFace

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.

7. API contract changes to allow a null default perspective

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.

8. API contract changes to IViewLayout

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.

9. API contract changes to IVMInstall

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.

10. SelectionEnabler.SelectionClass made package-visible

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.

11. ContributionItem.getParent() can return null

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.

12. Changes to isPropertySet(boolean) in IPropertySource and IPropertySource2

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.

13. handlerSubmission element deleted from the org.eclipse.ui.commands extension point

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.

14. Static non-final API field GLOBAL_IGNORES_CHANGED in TeamUI made final

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.

15. ClassCastException using FillLayout

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.

16. IllegalArgumentException thrown creating a widget with a disposed parent

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.