# 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:

- Leading and trailing whitespace in path segments were not allowed
- The colon character (':') was reserved as a device separator character
- The backslash character ('\') was reserved as a segment separator character

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:

- Existing methods on these `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.
- A new `isValid()` method was added to these interfaces so that a client can determine whether an object is still valid.
- Recommendations were added to the specs to make it clear that hanging on to objects obtained from the extension registry is not recommended.

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.