Eclipse 3.0 Plug-in Migration FAQ

Why did Eclipse API change in incompatible ways between 2.1 and 3.0?

Eclipse 3.0 is an evolution of Eclipse 2.1. There were a few areas where we could not evolve Eclipse while maintaining perfect compatibility across the board. The four main sources of incompatibilities are:

• The Eclipse 3.0 runtime is now based on OSGi.
• The Eclipse 3.0 UI workbench is now split into RCP and IDE parts.
• The Xerces plug-in has been dropped from 3.0.
• Eclipse 3.0 performs more work in background threads.

The list of specific incompatibilities.

Will a 2.1 plug-in work in Eclipse 3.0?

Yes, except in a few cases. If a plug-in relies only on Eclipse 2.1 APIs, then it will continue to work in 3.0. The very few exceptions are places in the API where the changes between 2.1 and 3.0 could not be done in any compatible way; if a plug-in uses one of these, it will not work.

My 2.1 plug-in makes use of classes in internal packages. Will it still work in Eclipse 3.0?

If a plug-in relies on internal classes or behavior not specified in the Eclipse 2.1 API, it's impossible to make blanket claims one way or the other about whether the plug-in might work in 3.0. You'll need to try it.

How do I run my plug-in in Eclipse 3.0 without touching it?

Install your 2.1 plug-in in the eclipse/plugins/ subdirectory of an Eclipse 3.0-based product and restart Eclipse. Eclipse will recognize that the plug-in is an unconverted 2.1 plug-in (by the header on the plugin.xml) and automatically make adjustments to compensate for changes to Platform plug-in dependencies and renamed Platform extension points.

Will a 2.1 plug-ins need to be changed to compile properly in Eclipse 3.0?

Yes in all cases. There are certain differences between Eclipse 2.1 and 3.0 that necessitate changes to all plug-ins going forward. If you have a plug-in written for 2.1 and wish to recompile it, it needs to be migrated to 3.0 before it can be developed further for 3.0.

How do I migrate my plug-in to Eclipse 3.0?

Once you've loaded (or imported) your plug-in project into an Eclipse 3.0 workspace, use PDE Tools > Migrate to 3.0 (project context menu) to convert the plug-in's manifest to the 3.0 format and automatically adjust the list of required Platform plug-ins and references to Platform extension points that were renamed. In most cases, the code for the plug-in should then compile and run successfully. The code for the plug-in should then be reviewed to make sure that it is not dependent on one of the areas of incompatible API change.

Can I trust that a plug-in will have compile errors or warnings if it relies on API that has changed incompatibly?

No. There are some areas of incompatible change that do not get flagged by the Java compiler.

Can I safely ignore warnings in the code coming from use of deprecated API?

Yes, in the short term. Wherever possible, obsolete APIs are marked as deprecated rather than being deleted outright and continue to work (albeit possibly only under limited conditions). So while there is usually no urgency to get off the deprecated API, the fact that it is now considered obsolete means that there is now a better way to do something. Plug-ins should be weaned off all usage to deprecated API at the earliest convenience.

Once I migrate my plug-in to Eclipse 3.0, can I still install and run the resulting binary plug-in in Eclipse 2.1?

No. This is not supported, and probably wouldn't work due to the renamed extension points.

What is the purpose of org.eclipse.core.runtime.compatibility?

The move in 3.0 to an OSGi-base runtime made some of the existing core runtime APIs obsolete. Wherever possible, obsolete APIs in the org.eclipse.core.runtime.* packages, along with the implementation behind it, were moved from the org.eclipse.core.runtime plug-in to a new org.eclipse.core.runtime.compatibility plug-in. By default, newly-created plug-ins depend on org.eclipse.core.runtime and are expected to use only non-deprecated runtime APIs. On the other hand, existing plug-ins migrating from 2.1 will depend by default on org.eclipse.core.runtime.compatibility and can make use of the old APIs as well (the org.eclipse.core.runtime.compatibility plug-in re-exports APIs of org.eclipse.core.runtime). While the org.eclipse.core.runtime.compatibility plug-in is likely to be included in Eclipse IDE configurations, it's dead wood that's unlikely to be included in products based on RCP configurations.

What is the purpose of org.eclipse.ui.workbench.compatibility?

org.eclipse.ui.workbench.compatibility is a plug-in fragment that provides enhanced binary compatibility for 2.1 plug-ins being run in an Eclipse 3.0-based product. In 3.0, six methods with an explicit dependence on IFile or IMarker were moved from the org.eclipse.ui.IWorkbenchPage interface in order to cleanly separate the workbench from workspace and resources. The org.eclipse.ui.workbench.compatibility fragment arranges to add back these methods so that existing 2.1 plug-ins can run without modification. Note, however, that plug-ins being migrated to 3.0 that reference the moved methods will see compile errors that can (only) be resolved by calling the replacement methods now located on org.eclipse.ui.ide.IDE.

The IWorkbenchPage methods in question are: openEditor(IFile), openEditor(IFile, String), openEditor(IFile, String, boolean), openEditor(IMarker), openEditor(IMarker, boolean), and openSystemEditor(IFile).