# 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

## 1. Plug-in Preferences

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

## 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. Three new methods have been added to this interface with default implementations provided by `org.eclipse.jdt.launching.AbstractVMInstall`.

Action required: Any implementing classes that do not already subclass `org.eclipse.jdt.launching.AbstractVMInstall` will need to 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.