Incompatibilities between Eclipse 2.1 and 3.0

Eclipse changed in incompatible ways between 2.1 and 3.0 in ways that affect plug-ins. The following entries describe the areas that changed and provide instructions for migrating 2.1 plug-ins to 3.0. Note that you only need to look here if you are experiencing problems running your 2.1 plug-in on 3.0.

  1. Plug-in manifest version
  2. Restructuring of Platform UI plug-ins
  3. Restructuring of Platform Core Runtime plug-ins
  4. Removal of Xerces plug-in
  5. Eclipse 3.0 is more concurrent
  6. Opening editors on IFiles
  7. Editor goto marker
  8. Editor launcher
  9. Editor registry
  10. Workbench marker help registry
  11. Text editor document providers
  12. Text editors
  13. Headless annotation support
  14. Console view
  15. Java breakpoint listeners
  16. Clipboard access in UI thread
  17. Key down events
  18. Tab traversal of custom controls
  19. Selection event order in SWT table and tree widgets
  20. New severity level in status objects
  21. Build-related resource change notifications
  22. Intermediate notifications during workspace operations
  23. URL stream handler extensions
  24. Class load order
  25. Class loader protection domain not set
  26. PluginModel object casting
  27. ILibrary implementation incomplete
  28. Invalid assumptions regarding form of URLs
  29. BootLoader methods moved/deleted
  30. Plug-in export does not include the plug-in's JARs automatically
  31. Re-exporting runtime API
  32. Plug-in parsing methods on Platform
  33. Plug-in libraries supplied by fragments
  34. Changes to build scripts
  35. Changes to PDE build Ant task
  36. Changes to eclipse.build Ant task
  37. Changes to eclipse.fetch Ant task
  38. Replacement of install.ini

 

1. Plug-in manifest version

The header of the manifest files for plug-ins (and plug-in fragments) has changed to include a new line which identifies the appropriate plug-in manifest version. Prior to 3.0, plug-ins did not carry one of these <?eclipse ...?> lines; after 3.0, they must always have one. This change is to allow the Eclipse runtime to reliably recognize pre-3.0 plug-ins that have not been ported to 3.0, so that it can automatically provide greater binary compatibility for such plug-ins. This is the general form of the plugin.xml file (fragment.xml is similar):

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.0"?>
<plugin ...>
    ...
</plugin>

Plug-in manifests created by PDE 3.0 automatically have this form. It is strongly recommended that you use the PDE plug-in migration tool. It automatically inserts the indicated line into the manifest of 2.1 plug-ins and plug-in fragments and addresses many of the other changes described here.

If you do add this directive to a plugin.xml (manually or using PDE), the file must also be updated to explicitly list the plug-ins on which it depends. For example, prior to Eclipse 3.0 dependencies on org.eclipse.core.runtime and org.eclipse.core.boot were implicit. With 3.0, org.eclipse.core.boot is no longer needed and developers must choose org.eclipse.core.runtime or org.eclipse.core.runtime.compatibility (or neither) as appropriate.

Note: This is one of the incompatibilities that does not impact how 2.1 binary plug-ins are run by Eclipse 3.0.

 

2. Restructuring of Platform UI plug-ins

The org.eclipse.ui plug-in, which used to be the main Platform UI plug-in, now provides just the API and extension points for the generic (i.e., non-IDE-specific) workbench. Optional and IDE-specific API and extension points have moved to other plug-ins.

The impact of this change is two-fold: (1) the moved org.eclipse.ui extension points have new extension point ids; and (2) the list of required plug-ins has changed.

The org.eclipse.ui extension points in the following table have moved to different plug-ins, causing their extension point ids to change. If an existing plug-in contributes an extension to the moved extension points, then the reference in the "point" attribute of the <extension> element in the plug-in manifest file must be changed to refer to the corresponding new ones extension point id. The PDE plug-in migration tool makes these fix-ups.

Note: This is one of the incompatibilities that does not impact how 2.1 binary plug-ins are run by Eclipse 3.0. The Eclipse 3.0 runtime automatically detects pre-3.0 plug-ins (by the absence of the aforementioned <?eclipse version="3.0"?> line in the plug-in manifest) and automatically compensates for these extension point and plug-in dependency changes.

Old extension point id

New extension point id

org.eclipse.ui.markerHelp org.eclipse.ui.ide.markerHelp
org.eclipse.ui.markerImageProviders org.eclipse.ui.ide.markerImageProviders
org.eclipse.ui.markerResolution org.eclipse.ui.ide.markerResolution
org.eclipse.ui.projectNatureImages org.eclipse.ui.ide.projectNatureImages
org.eclipse.ui.resourceFilters org.eclipse.ui.ide.resourceFilters
org.eclipse.ui.markerUpdaters org.eclipse.ui.editors.markerUpdaters
org.eclipse.ui.documentProviders org.eclipse.ui.editors.documentProviders
org.eclipse.ui.workbench.texteditor.
markerAnnotationSpecification 		org.eclipse.ui.editors.markerAnnotationSpecification

The following table lists the API packages formerly provided by the org.eclipse.ui plug-in that have been moved to different plug-ins. (The names of the API packages, classes, fields, and methods did not change.) In some cases, the API packages are now split across more than one plug-in. Since the API classes visible to any given plug-in are determined by that plug-in's list of required plug-ins, these changes may require adjusting "<requires>" elements in an existing plug-in's manifest to regain access to API class.

This change only affects plug-ins that depend on the org.eclipse.ui plug-in (that is, includes <import plugin="org.eclipse.ui"/> in the <requires> section of the plug-in manifest); all other plug-ins are unaffected. If it is affected, you may need to change the <import> element, or add additional <import> elements, so that all the API classes your plug-in needs are in scope. We strongly recommend that plug-ins only state dependencies on the plug-ins that they actually use. Including unnecessary dependencies reduces runtime performance because the Java class loader must search for classes in all dependents. (The PDE plug-in migration tool will fix up the dependencies, and help to determine a minimal set.)

API package

2.1 plug-in

Corresponding 3.0 plug-in(s)

org.eclipse.jface.text.* org.eclipse.ui org.eclipse.jface.text
org.eclipse.text.* org.eclipse.ui org.eclipse.jface.text
org.eclipse.ui org.eclipse.ui org.eclipse.ui, org.eclipse.ui.ide
org.eclipse.ui.actions org.eclipse.ui org.eclipse.ui, org.eclipse.ui.ide
org.eclipse.ui.dialogs org.eclipse.ui org.eclipse.ui, org.eclipse.ui.ide
org.eclipse.ui.editors.* org.eclipse.ui org.eclipse.ui.editor
org.eclipse.ui.model org.eclipse.ui org.eclipse.ui, org.eclipse.ui.ide
org.eclipse.ui.part org.eclipse.ui org.eclipse.ui, org.eclipse.ui.ide
org.eclipse.ui.texteditor org.eclipse.ui org.eclipse.ui.workbench.texteditor, org.eclipse.ui.editors
org.eclipse.ui.texteditor.* org.eclipse.ui org.eclipse.ui.workbench.texteditor
org.eclipse.ui.views.bookmarkexplorer org.eclipse.ui org.eclipse.ui.ide
org.eclipse.ui.views.contentoutline org.eclipse.ui org.eclipse.ui.views
org.eclipse.ui.views.markers org.eclipse.ui org.eclipse.ui.ide
org.eclipse.ui.views.navigator org.eclipse.ui org.eclipse.ui.ide
org.eclipse.ui.views.properties org.eclipse.ui org.eclipse.ui.views
org.eclipse.ui.views.tasklist org.eclipse.ui org.eclipse.ui.ide
org.eclipse.ui.wizards.datatransfer org.eclipse.ui org.eclipse.ui.ide
org.eclipse.ui.wizards.newresource org.eclipse.ui org.eclipse.ui.ide

 

3. Restructuring of Platform Core Runtime plug-ins

The Eclipse 3.0 Platform Runtime is based on OSGi, necessitating changes to the structure of the two Platform Runtime plug-ins, org.eclipse.core.runtime and org.eclipse.core.boot.

A new org.eclipse.core.runtime.compatibility plug-in provides an implementation bridge between the old and new APIs, and is the new home for many of the obsolete APIs formerly found in org.eclipse.core.runtime and org.eclipse.core.boot. Platform Runtime extension points are unaffected by the restructuring.

When migrating the existing plug-in to 3.0, the plug-in's manifest needs to be updated to reflect the new structure of the Eclipse Platform Runtime plug-ins. The PDE plug-in manifest migration tool will add a dependency to org.eclipse.core.runtime.compatibility if required.

Note also that if you mark you plug-in as 3.0 (using <?eclipse version="3.0"?>) and your plug-in defines a Plugin class, either explicitly <import plugin="org.eclipse.core.runtime.compatibility"/> in the plug-in manifest or ensure that the Plugin class defines the default constructor.

Note: This is one of the incompatibilities that does not impact how 2.1 binary plug-ins are run by Eclipse 3.0. The Eclipse 3.0 runtime automatically detects pre-3.0 plug-ins (by the absence of the <?eclipse version="3.0"?> line in the plug-in manifest) and automatically compensates for these changes to the Platform Runtime.

 

4. Removal of Xerces plug-in

The org.eclipse.xerces plug-in is no longer necessary and has been deleted. XML parsing support is built in to J2SE 1.4, and the presence of the Xerces plug-in creates class loader conflicts. The javax.xml.parsers, org.w3c.dom.*, and org.xml.sax.* API packages formerly provided by the org.eclipse.xerces plug-in are now available from the J2SE libraries.

If your plug-in requires the org.eclipse.xerces plug-in, change your plug-in manifest to remove this stated dependency. Once that is done, the plug-in's code should compile and run without further change.

A 2.1 binary plug-ins with a stated dependency on the org.eclipse.xerces plug-in will be missing a prerequisite when run in a standard Eclipse 3.0 configuration. The plug-in will not be activated as a consequence.

 

5. Eclipse 3.0 is more concurrent

Prior to Eclipse 3.0, Eclipse operated mostly in a single thread. Most API methods and extension points operated either in the UI thread, or in a thread spawned from a progress dialog that blocked the UI thread. Most plug-in writers did not have to worry much about thread safety, apart from ensuring that all UI activity occurred in the UI thread. In Eclipse 3.0, there is generally much more concurrency. Many operations now occur in a background thread, where they may run concurrently with other threads, including the UI thread. All plug-ins whose code runs in a background thread must now be aware of the thread safety of their code.

In addition to plug-ins that are explicitly running operations in the background using the org.eclipse.core.runtime.jobs API, there are several platform API facilities and extension points that make use of background threads. Plug-ins that hook into these facilities need to ensure that their code is thread safe. The following table summarizes the API and extension points that run some or all of their code in a background thread in Eclipse 3.0:

Extension point or API class

Notes

org.eclipse.core.runtime.IRegistryChangeListener New in Eclipse 3.0, runs in background
org.eclipse.core.resources.IResourceChangeListener AUTO_BUILD events now in background
org.eclipse.core.resources.builders (ext. point) Auto-build now in background
org.eclipse.core.resources.ISaveParticipant SNAPSHOT now in background
org.eclipse.ui.workbench.texteditor.quickdiffReferenceProvider (ext. point) New in Eclipse 3.0, runs in background
org.eclipse.ui.decorators (ext. point) Already in background in Eclipse 2.1
org.eclipse.ui.startup (ext. point) Already in background in Eclipse 2.1
org.eclipse.team.core.org.eclipse.team.core.repository (ext. point) Many operations now in background
org.eclipse.team.ui.synchronizeParticipants (ext. point) New in Eclipse 3.0, runs in background
org.eclipse.debug.core.launchConfigurationTypes (ext. point) Now runs in background
org.eclipse.jdt.core.IElementChangedListener ElementChangedEvent.PRE_AUTO_BUILD now runs in background, POST_RECONCILE already ran in the background

There are various strategies available for making code thread safe. A naive solution is to ensure all work occurs in the UI thread, thus ensuring serialized execution. This is a common approach for UI plug-ins that are not doing CPU-intensive processing. When doing this, be aware of the deadlock risk inherent in Display.syncExec. Display.asyncExec is generally safer as it does not introduce deadlock risk, at the expense of losing precise control over when the code is executed.

Other techniques for making thread safe code include:

 

6. Opening editors on IFiles

The following methods were deleted from the org.eclipse.ui.IWorkbenchPage interface. IWorkbenchPage is declared in the generic workbench, but the methods are inherently resource-specific.

Clients of these IWorkbenchPage.openEditor methods should instead call the corresponding public static methods declared in the class org.eclipse.ui.ide.IDE (in the org.eclipse.ui.ide plug-in).

Clients of these IWorkbenchPage.openSystemEditor(IFile) method should convert the IFile to an IEditorInput using new FileEditorInput(IFile) and then call the openEditor(IEditorInput,String) method. In other words, rewrite page.openSystemEditor(file) as page.openEditor(new FileEditorInput(file), IEditorRegistry.SYSTEM_EXTERNAL_EDITOR_ID). Note: clients using editor id IEditorRegistry.SYSTEM_EXTERNAL_EDITOR_ID must pass an editor input which implements org.eclipse.ui.IPathEditorInput (which FileEditorInput does).

Note: This is one of the incompatibilities that does not impact how 2.1 binary plug-ins are run by Eclipse 3.0. Eclipse 3.0 includes a binary runtime compatibility mechanism that ensures existing 2.1 plug-in binaries using any of the deleted openEditor and openSystemEditor methods continue to work as in 2.1 in spite of this API change. (The deleted methods are effectively "added back" by the org.eclipse.ui.workbench.compatibility fragment.)

 

7. Editor goto marker

The following method was deleted from the org.eclipse.ui.IEditorPart interface. IEditorPart is declared in the generic workbench, but the method is inherently resource-specific.

The corresponding methods were also deleted from the classes in the org.eclipse.ui.part package that implement IEditorPart, namely EditorPart, MultiEditor, MultiPageEditorPart, and MultiPageEditor. 

Clients that call this method should instead test if the editor part implements or adapts to org.eclipse.ui.ide.IGotoMarker (in the org.eclipse.ui.ide plug-in) and if so, call gotoMarker(IMarker). The IDE class has a convenience method for doing so: IDE.gotoMarker(editor, marker);

Clients that implement an editor that can position itself based on IMarker information should implement or adapt to org.eclipse.ui.ide.IGotoMarker.

Since IGotoMarker's only method is gotoMarker(IMarker) and has the same signature and specification as the old IEditorPart.gotoMarker(IMarker), existing editor implementations can adapt to this change simply by including IGotoMarker in the implements clause of the class definition.

A 2.1 binary plug-ins with code that calls this method will get an class linking error exception when run in a standard Eclipse 3.0 configuration.

 

8. Editor launcher

The editor launcher interface org.eclipse.ui.IEditorLauncher is implemented by plug-ins that contribute external editors. The following method was removed from this interface. IEditorLauncher is declared in the generic workbench, but the method is inherently resource-specific.

It was replaced by

Clients that call IEditorLauncher.open(file) should instead call IEditorLauncher.open(file.getLocation()). Clients that implement this interface should replace (or augment) their implementation of open(IFile) by one for open(IPath).

A 2.1 binary plug-ins with code that calls this method will get an class linking error exception when run in a standard Eclipse 3.0 configuration.

 

9. Editor registry

The following methods were removed from the org.eclipse.ui.IEditorRegistry interface. IEditorRegistry is declared in the generic workbench, but the methods are inherently resource-specific.

Clients that call getEditors(file) or getImageDescriptor(file) should call the "String" equivalent methods:

Clients that call setDefaultEditor(IFile file, String editorId) and getDefaultEditor(IFile file) should should instead call the corresponding public static methods declared in the class org.eclipse.ui.ide.IDE (in the org.eclipse.ui.ide plug-in):

Also, the API contract for the method IEditorRegistrygetDefaultEditor() was changed. This method, which is also now deprecated, and will always return the System External Editor editor descriptor. This change impacts clients that assumed the default editor returned would be a text editor.

There are new constants that represent the system external editor and system in-place editor identifiers (SYSTEM_EXTERNAL_EDITOR_ID and SYSTEM_INPLACE_EDITOR_ID). These two editors require an editor input that implements or adapts to org.eclipse.ui.IPathEditorInput. Note that the in-place editor descriptor will not exist in Eclipse configurations that do not support in-place editing.

 

10. Workbench marker help registry

The following method was deleted from the org.eclipse.ui.IWorkbench interface. IWorkbench is declared in the generic workbench, but the method is inherently resource-specific.

Clients of IWorkbench.getMarkerHelpRegistry() should instead call the public static method org.eclipse.ui.ide.IDE.getMarkerHelpRegistry() (in the org.eclipse.ui.ide plug-in).

A 2.1 binary plug-ins with code that calls this method will get an exception when run in a standard Eclipse 3.0 configuration.

 

11. Text editor document providers

In order to make org.eclipse.ui.texteditor.AbstractTextEditor independent of IFile, org.eclipse.ui.texteditor.AbstractDocumentProvider introduces the concept of a document provider operation (DocumentProviderOperation) and a document provider operation runner (IRunnableContext). When requested to perform reset, save, or synchronize, AbstractDocumentProvider creates document provider operations and uses the operation runner to execute them. The runnable context can be provided by subclasses via the getOperationRunner method. Here is a summary of the changes that clients must adapt to:

The AbstractDocumentProvider subclass org.eclipse.ui.editors.text.StorageDocumentProvider implements the getOperationRunner method to always returns null. This means that subclasses of StorageDocumentProvider should not be affected by this change.

The StorageDocumentProvider subclass org.eclipse.ui.editors.text.FileDocumentProvider implements the getOperationRunner method that returns an IRunnableContext for executing the given DocumentProviderOperations inside a WorkspaceModifyOperation. Other changes to FileDocumentProvider are:

 

12. Text editors

Changes to org.eclipse.ui.texteditor.AbstractTextEditor:

The AbstractTextEditor subclass org.eclipse.ui.texteditor.StatusTextEditor provides the predicate method isErrorStatus(IStatus). Subclasses may override in order to decide whether a given status must considered an error or not.

Changes to org.eclipse.ui.editors.text.AbstractDecoratedTextEditor:

 

13. Headless annotation support

As part of the introduction of headless annotation support, the following changes to Annotation were made:

        org.eclipse.jface.text.source.Annotation 
        org.eclipse.jface.text.source.AnnotationModel 
        org.eclipse.jface.text.source.AnnotationModelEvent 
        org.eclipse.jface.text.source.IAnnotationModel 
        org.eclipse.jface.text.source.IAnnotationModelListener 
        org.eclipse.jface.text.source.IAnnotationModelListenerExtension

 

14. Console view

Eclipse 3.0 has new generic console support. The generic console is available via the Window > Show View > Basic > Console, and is used by the Eclipse debug and Ant integration.

The view id for the console has changed from org.eclipse.debug.ui.ConsoleView to org.eclipse.ui.console.ConsoleView. 2.1 plug-ins that programmatically open the console will be unsuccessful because that the old view no longer exists.

 

15. Java breakpoint listeners

In 3.0, the return types for the methods org.eclipse.jdt.debug.core.IJavaBreakpointListener.breakpointHit(IJavaBreakpoint, IJavaThread) and installingBreakpoing(IJavaTarget, IJavaBreakpoint, IJavaType) changed from boolean to int to allow listeners to vote "don't care". In releases prior to 3.0, listeners could only vote "suspend" or "don't suspend" when a breakpoint was hit, and "install" or "don't install" when a breakpoint was about to be installed. In 3.0, listeners can also vote "don't care" for either of these notifications. This allows clients to only make a decisive vote in situations that they care about. For "breakpoint hit" notifications, the breakpoint will suspend if any listeners vote "suspend", or all listeners vote "don't care"; and it will not suspend if at least one listener votes "don't suspend" and no listeners vote "suspend". Similarly, for "breakpoint installing" notifications, the breakpoint will be installed if any listeners vote to install, or all listeners vote "don't care"; and it will not be installed if at least one listener votes "don't install" and no listeners vote "install". In general, implementors should return DONT_CARE unless they have a strong opinion one way or the other. It is important to keep in mind, for example, that voting "suspend" will override any other listener's vote of "don't suspend".

The IJavaBreakpointListener interface is implemented by clients that create or react to breakpoints in Java code. There are likely few clients beyond JDT itself, save the one that reported the problem (bug 37760) that this change remedies. This is a breaking change for existing code that implements the IJavaBreakpointListener interface. This code needs to be modified to return an appropriate int value before it will compile or run in 3.0.

 

16. Clipboard access in UI thread

Prior to 3.0, the methods on the SWT class org.eclipse.swt.dnd.Clipboard were tacitly permitted to run in threads other than the UI thread. This oversight resulted in failures on GTK where the operating system requires that all clipboard interactions be performed in the UI thread. The oversight was not revealed earlier because many applications are single-threaded and receive most of their testing on Windows. In order for the Clipboard API to be sustainable and cross-platform, in 3.0 the specification and implementation of all Clipboard API methods have been changed to throw an SWT Exception (ERROR_THREAD_INVALID_ACCESS) if invoked from a non-UI thread. Clipboard services are commonly provided automatically by Eclipse components such as the text editor, which insulate many clients from this breaking change. Existing code that does make direct use of Clipboard should ensure that the API methods are called on the correct thread, using Display.asyncExec or syncExec when appropriate to shift accesses into the UI thread.

 

17. Key down events

In 3.0, SWT reports key down events before the work is done in the OS. This is much earlier than it was prior to 3.0. This change was made to support key bindings in Eclipse which necessitates intercepting key events before any widget has a chance to process the character. Consequences of this change are visible to code that handles low-level org.eclipse.swt.SWT.KeyDown events directly. For example, it means that when a listener on a Text widget receives a key down event, the widget's content (getText()) will not yet include the key just typed (it would have prior to 3.0). The recommended way to get the full text from the widget including the current key is to handle the higher-level SWT.Modify or SWT.Verify events rather than the low-level SWT.KeyDown event; code that already does it this way is unaffected by this change.

 

18. Tab traversal of custom controls

Prior to 3.0, when the focus was in the SWT class org.eclipse.swt.widgets.Canvas or one of its subclasses (including custom widgets), typing Ctrl+Tab, Shift+Tab, Ctrl+PgUp, or Ctrl+PgDn would automatically trigger traversal to the next/previous widget without reporting a key event. This behavior was unspecified, and runs counter to the rule that Canvases see every key typed in them. The proper way to handle traversal is by registering a traverse listener. In order to properly support Eclipse key bindings in 3.0, the default behavior was changed so that Canvas now sees Ctrl+Tab, Shift+Tab, Ctrl+PgUp, and Ctrl+PgDn key events instead of traversing. If you use a raw Canvas or define a subclass of Canvas, ensure that that you register a traverse listener.

 

19. Selection event order in SWT table and tree widgets

Mouse selections of items in the SWT classes org.eclipse.swt.widgets.Table and Tree generate the event sequence MouseDown-Selection-MouseUp uniformly in all operating environments. Similarly, keyboard selections generate the event sequence KeyDown-Selection-KeyUp uniformly in all operating environments. Prior to 3.0, the event order was not uniform, with Motif and Photon at variance with the rest by always reporting the Selection event first; i.e., Selection-MouseDown-MouseUp or Selection-KeyDown-KeyUp. For 3.0, the event order on Motif and Photon has been changed to match the others. Existing code that was functioning correctly on {Windows, GTK} and on {Motif, Photon} is unlikely to be affected. But it is wise to check your code to ensure that it does not rely on an invalid event order.

 

20. New severity level in status objects

org.eclipse.core.runtime.IStatus has a new severity constant, IStatus.CANCEL, that can be used to indicate cancelation. Callers of IStatus.getSeverity() that rely on the set of possible severities being limited to IStatus.OK, INFO, WARNING, and ERROR are affected by this addition. Callers of getSeverity should update their code to include the new severity.

 

21. Build-related resource change notifications

In Eclipse 3.0, workspace auto-builds now occur in a background thread. This required an API contract change to org.eclipse.core.resources.IResourceChangeEvent. The contract of IResourceChangeEvent previously guaranteed the following ordering of events for all workspace changes:

  1. PRE_DELETE or PRE_CLOSE event notification if applicable
  2. Perform the operation
  3. PRE_AUTO_BUILD event notification
  4. If auto-build is on, perform incremental workspace build
  5. POST_AUTO_BUILD event notification
  6. POST_CHANGE event notification

With auto-build now running in the background, there is no longer any guarantee about the temporal relationship between the AUTO_BUILD events and the POST_CHANGE event. In Eclipse 3.0, steps 3-5 in the above structure are removed from the operation. The resulting picture looks like this:

  1. PRE_DELETE or PRE_CLOSE event notification if applicable
  2. Perform the operation
  3. POST_CHANGE event notification

Periodically, the platform will perform a background workspace build operation. Note that this happens regardless of the whether auto-build is on or off. The exact timing of when this build occurs will not be specified. The structure of the build operation will look like this:

  1. PRE_BUILD event notification (PRE_BUILD is the new name for PRE_AUTO_BUILD)
  2. If auto-build is on, perform incremental workspace build
  3. POST_BUILD event notification (POST_BUILD is the new name for POST_AUTO_BUILD)
  4. POST_CHANGE event notification
The reference point for the deltas received by auto-build listeners will be different from post-change listeners. Build listeners will receive notification of all changes since the end of the last build operation. Post-change listeners will receive a delta describing all changes since the last post-change notification. This new structure retains three characteristics of resource change listeners that have been true since Eclipse 1.0:

However, there are some important differences with this approach. Prior to Eclipse 3.0, auto-build listeners were always called before POST_CHANGE listeners. For this reason, the delta received by auto-build listeners was always a subset of the delta received by the POST_CHANGE listeners. This relationship is now essentially reversed. Auto-build listeners will receive a delta that is a super-set of all deltas supplied to POST_CHANGE listeners since the end of the last background build. As before, auto-build listeners will be allowed to modify the workspace, and post-change listeners will not.

It will no longer be true that upon completion of a workspace changing operation, that AUTO_BUILD event listeners will have been notified. Client code that registers resource change listeners with IWorkspace.addResourceChangeListener(IResourceChangeListener) is unlikely to be affected by this change because AUTO_BUILD events were never reported to these listeners. However, clients that use IWorkspace.addResourceChangeListener(IResourceChangeListener,int) and specify an event mask that includes AUTO_BUILD events are likely to be broken by this change if they make assumptions about when auto-build listeners run or what thread they run in. For example, if an auto-build listener is updating a domain model to reflect changes to the workspace, then this update might not have happened when the workspace changing operation returns. It is worth noting that only UI-level code can be affected in this way. Core-level code that is called via API may be called within the scope of an IWorkspaceRunnable, so it can never be sure about when resource change listeners will be called. The suggested fix for this breakage is to use POST_CHANGE instead of build listeners if it is necessary to have notification occur before the operation completes.

 

22. Intermediate notifications during workspace operations

It will no longer be guaranteed that all resource changes that occur during the dynamic scope of an IWorkspaceRunnable will be batched in a single notification. This mechanism can still be used for batching changes to avoid unnecessary builds and notifications, but the Platform may now decide to perform notifications during the operation. This API contract change is not likely to be a breaking change for existing clients. It is equivalent to the Platform deciding to call IWorkspace.checkpoint periodically during a long running operations. The reason for this change is that it is now possible for multiple threads to be modifying the workspace concurrently. When one thread finishes modifying the workspace, a notification is required to prevent responsiveness problems, even if the other operation has not yet completed. This change also allows users to begin working on a set of resources before the operation completes. For example, a user can now begin browsing files in a project that is still in the process of being checked out. The new method IWorkspace.run(IWorkspaceRunnable, ISchedulingRule, int, IProgressMonitor) has an optional flag, AVOID_UPDATE, which operations can use as a hint to the platform to specify whether periodic updates are desired.

 

23. URL stream handler extensions

What is affected: Plug-ins that contribute extensions to the org.eclipse.core.runtime.urlHandlers extension point.

Description: The contract for the org.eclipse.core.runtime.urlHandlers extension point was changed to use the URL Stream Handler service provided by OSGi. The OSGi support is superior to the one in Eclipse 2.1, and correctly handles dynamic handlers. Because of various design issues with the base Java URL handler mechanism, URLStreamHandlers registered with the OSGi handler service must implement org.osgi.service.url.URLStreamHandlerService.

Action required: Formerly, the handler class had to implement java.net.URLStreamHandler and extend the urlHandlers extension point. The extension point is no longer supported and the handler must be updated to implement org.osgi.service.url.URLStreamHandlerService interface. The OSGi framework provides an abstract base class (org.osgi.service.url.AbstractURLStreamHandlerService) that can be trivially subclassed to fill this role.

Instead of registering the handler using an extension point, plug-ins must now do so by registering their handler as a service. For example,

    Hashtable properties = new Hashtable(1);
    properties.put(URLConstants.URL_HANDLER_PROTOCOL, new String[] {MyHandler.PROTOCOL});
    String serviceClass = URLStreamHandlerService.class.getName();
    context.registerService(serviceClass, new MyHandler(), properties);

 

24. Class load order

What is affected: Plug-ins which supply packages provided which are also supplied by other plug-ins. A very limited number of plug-ins are affected by this change and some of those affected will actually benefit (see below).

Description: In Eclipse 2.x, class loaders search for classes in the following order: consult (1) parent class loader (in practice this is the Java boot class loader), then (2) its own classpath contents, and finally (3) all of its prerequisites in the order declared. OSGi offers an optimization over this model. In this approach a class loader will consult (1) parent class loader (again, effectively the Java boot classloader), then either (2a) a single prerequisite known to contribute classes in the package being queried or (2b) its own classpath entries for the desired class.

The class loader determines whether to consult self or its prerequisites based on its imported and required packages. This information is inferred from the plug-in content in the case of traditional plug-ins and directly specified in the case of plug-ins with explicit OSGi bundle manifest. In either case, it is known a priori which class loaders will supply the classes for which packages. This offers performance improvements as well as a solution to the vexing problem of multiple prerequisites contributing the same classes.

Take for example the case of Xerces and Xalan, both of which contain various classes from org.xml packages. Using the first approach, the Xerces plug-in would see its copy of these classes while the Xalan plug-in would see their copy. Since these plug-ins need to communicate, ClassCastExceptions occur. Using the second approach, only one of the two plug-ins contributes the duplicate classes and both plug-ins see the same copies.

Action required: The action required depends on the particulars of the usecase. Affected developers need to review their classpath and resolve any conflicts which may be happening.

 

25. Class loader protection domain not set

What is affected: Plug-ins that expect the protection domain of their class loader to be set at all times.

Description: In Eclipse 2.1 plug-in class loaders were java.security.SecureClassloaders and, as such, always had a protection domain set. In Eclipse 3.0, class loaders do not extend SecureClassloader and only set the protection domain if Java security is turned on (not the normal case).

Action required: The action required will depend on the scenario in which the plug-in is using the protection domain.

 

26. PluginModel object casting

What is affected: Plug-ins which cast objects of type org.eclipse.core.runtime.IPlugin* to org.eclipse.core.runtime.model.Plugin*Model. Even though the relationship between these interfaces and the model classes is not specified in the Eclipse 2.1 API, we are explicitly calling out this change as we have found instances of plug-ins relying on this relationship in the 2.1 implementation.

Description: The Eclipse API provides a series of interfaces (e.g., IPluginDescriptor) and so-called "model" classes (e.g., PluginDescriptorModel) related to plug-ins and the plug-in registry. In the Eclipse 2.1 implementation it happens that the model classes implement the relevant interfaces. In the new OSGi-based runtime, the plug-in registry has been significantly reworked to allow for a separation between the class loading and prerequisite aspects of plug-ins and the extension and extension-point aspects. As such the Eclipse 3.0 runtime is unable to maintain the implementation relationship present in 2.1.

Action required: Plug-ins relying on this non-API relationship need to be reworked code according to their usecase. More information on this is given in the recommended changes section of this document and in the Javadoc for the related classes and methods.

 

27. ILibrary implementation incomplete

What is affected: Plug-ins that use org.eclipse.core.runtime.ILibrary.

Description: The new runtime maintains the classpath entries in a different and incompatible form from Eclipse. As a result, the compatibility layer is unable to correctly model the underlying OSGi structures as ILibrary objects. The runtime's compatibility support creates ILibrary objects but must assume default values for everything except the library's path.

Action required: Users of ILibrary should consider accessing the desired header values (e.g., Bundle-Classpath) from the appropriate Bundle (see Bundle.getHeaders()) and using the ManifestElement helper class to interpret the entries. See the class Javadoc for more details.

 

28 Invalid assumptions regarding form of URLs

What is affected: Plug-ins that make assumptions regarding their installation structure, location and the local file system layout.

Description: Methods such as IPluginDescriptor.getInstallURL() return URLs of a particular form. Despite their form being unspecified, various plug-ins are making assumptions based on the current implementation. For example, they may expect to get a file: URL and use URL.getFile() and use java.io.File manipulation on the result. To date, this has been a workable but rather fragile approach. For example, if a plug-in is installed on a web server, it is possible that an http: URL would be returned. The new Eclipse 3.0 runtime is even more flexible and opens more possibilities for execution configurations (e.g., maintaining whole plug-ins in JARs rather than exploded in directories). That is, while the new OSGi-based runtime does not actually break 2.1 API, it exposes more cases where assumptions made in current plug-ins are invalid.

Action required: Plug-in writers should ensure that the information to which they need access is available via getResource() (and is on the classpath) or use the relevant API for accessing the contents of a plug-in (e.g., Bundle.getEntry(String)).

 

29. BootLoader methods moved/deleted

What is affected: Non-plug-in code that calls certain methods from the class org.eclipse.core.boot.BootLoader.

Description: The static methods BootLoader.startup(), shutdown() and run() were moved to org.eclipse.core.runtime.adaptor.EclipseStarter, which is part of the OSGi framework. This API is the interface between the main() in startup.jar and the OSGi framework/Eclipse runtime. The restructuring of the runtime did not permit these methods to remain on BootLoader. The old BootLoader class is now located in the runtime compatibility layer and is deprecated, and the moved methods are stubbed to do nothing.

There is no replacement for the old BootLoader.getRunnable() as the runtime can no longer support the acquisition of individual applications. Rather, users must indicate the application of interest when they start the platform.

Action required: In general this API is used by very few people (it cannot be used from within an Eclipse plug-in). In the rare case that it is, the code must be adapted to use the corresponding methods on EclipseStarter.

 

30. Plug-in export does not include the plug-in's JARs automatically

What is affected: All plug-ins.

Description: In Eclipse 2.1, a plug-in's bin.includes line from their build.properties did not have to contain the list of JARs from their library declaration in the plugin.xml file; these JARs were added for free. In Eclipse 3.0 the list of files in the bin.includes section of the build.properties is an exhaustive list and must include all files which plug-in developers intend to be included in their plug-in when building or exporting.

Action required: Ensure that the bin.includes line from the build.properties file includes all of the JARs listed in your plugin.xml file.

 

31. Re-exporting runtime API

What is affected: Plug-ins that expose API that includes elements from changed runtime API.

Description: Various plug-ins expose API that includes elements from the runtime API. With the changes to the Eclipse 3.0 runtime outlined here, client plug-ins must re-evaluate their use of runtime API in their API.

Action required: This scenario is quite rare as very little of the Eclipse runtime API is changing. Depending on the scenario, clients may have to change their API or continue to rely on the the compatibility layer.

 

32. Plug-in parsing methods on Platform

What is affected: Plug-ins that use org.eclipse.core.runtime.Platform.parsePlugins(..., Factory).

Description: The method org.eclipse.core.runtime.Platform.parsePlugins(..., Factory) has been moved. The API associated with the Factory argument has been moved from the org.eclipse.core.runtime plug-in up to the org.eclipse.core.runtime.compatibility plug-in (which depends on the runtime plug-in). As a result, the parsing method has been moved as well.

Action required: Users of this method should use the same method on the class org.eclipse.core.runtime.model.PluginRegistryModel.

 

33. Plug-in libraries supplied by fragments

What is affected: Plug-ins that specify code on their classpath but do not supply that code (i.e., the JAR is supplied by a fragment; for example, the org.eclipse.swt plug-in).

Description: The new runtime must convert plug.xml files to manifest.mf files behind the scenes. This is done through a straight mechanical transformation and an analysis of the jars listed and supplied by the plug-in. In the case where a plug-in specifies a jar on its classpath but does not supply the jar, there is no code to analyze and the plug-in convertor cannot generate a correct manifest.mf.

Action required: Providers of such plug-ins must either change to supply the appropriate jar in the plug-in itself or hand craft/maintain a META-INF/MANIFEST.MF file for their plug-in. Typically this can be done using PDE to get the initial manifest and then adding in the appropriate Provide-Package header.

 

34. Changes to build scripts

What is affected: Scripts (e.g., Ant build.xml files) which define classpaths containing runtime-related jars and class directories.

Description: The new runtime contains a number of new plug-ins and jars. Their introduction was mandated by the refactoring of the runtime into configurable pieces. For most runtime situations these changes are transparent. However, if you have custom build.xml (or similar) scripts which currently compile code against org.eclipse.core.runtime, you will need to update them before they will function correctly. A typical script contains a classpath entry in a <javac> task that references the org.eclipse.core.runtime plug-in as follows:

    ../org.eclipse.core.runtime/bin;../org.eclipse.core.runtime/runtime.jar

The runtime plug-in continues to contain much of the original runtime code. However, various parts of the runtime which are there only for compatibility purposes are contained in a compatibility plug-in (org.eclispe.core.runtime.compatibility). Most of the new runtime code is contained in a collection of plug-ins (org.eclipse.osgi.*).

Action required: Developers should add the entries below as needed to eliminate compilation errors. While the complete set of jars supplied is listed below, typical uses require only a subset on the classpath at compile time. As usual, the inclusion of the /bin directories is discretionary. The entries are given here in logical groupings by supplying plug-in:

In addition the following jars may be required in special cases:

While updating such scripts, you should also take the opportunity to clean up (i.e., remove) references to org.eclipse.core.boot. This plug-in is obsolete and longer contains any code. The entries can be left on the classpath but they serve no purpose and should be removed. Look to remove: 

    ../org.eclipse.core.boot/bin;../org.eclipse.core.boot/boot.jar

 

35. Changes to PDE build Ant task

What is affected: Scripts (e.g., Ant build.xml files) using the eclipse.buildScript task.

Description: PDE Build introduced a new property to the eclipse.buildScript task to control the generation of plug-ins build scripts. This was mandated by the introduction of the new OSGi-based runtime.

Action required: If you want to use Eclipse 3.0 to build a 2.1 based product, then introduce in eclipse.buildScript the property "buildingOSGi" and set it to false. For example: 

<eclipse.buildScript ... buildingOSGi="false"/>

 

36. Changes to eclipse.build Ant task

What is affected: Scripts (e.g., Ant build.xml files) using the eclipse.buildScript task.

Description: PDE Build introduced a new property to the eclipse.buildScript task to control the generation of plug-ins build scripts. This was mandated by the introduction of the new OSGi-based runtime.

Action required: If you want to use Eclipse 3.0 to build a 2.1 based product, then introduce in eclipse.buildScript the property "buildingOSGi" and set it to false. For example: 

<eclipse.buildScript ... buildingOSGi="false"/>

 

37. Changes to eclipse.fetch Ant task

What is affected: Scripts (e.g., Ant build.xml files) using the eclipse.buildScript task.

Description: PDE Build changed the behaviour of the eclipse.fetch task to ease building eclipse in an automated build style. The elements style now only support one entry at a time and the scriptName is always ignored.

Action required: If you had a list of entries in the "elements" tag of an eclipse.fetch call, spread them out over several call to eclipse.fetch. If you use to set the scriptName, note that now the generated fetch script is always called "fetch_{elementId}". For example: 

<eclipse.fetch elements="plugin@org.eclipse.core.runtime, feature@org.eclipse.platform" .../>
becomes 
<eclipse.fetch elements="plugin@org.eclipse.core.runtime" .../>
<eclipse.fetch elements="feature@org.eclipse.platform" .../>

 

38. Replacement of install.ini

The install.ini file is no longer included. In its place is the new config.ini file in the configuration sub-directory. Products that used the install.ini file to specify a primary feature (e.g., to provide branding information) need to make changes to the config.ini file instead. In addition to the new filename, the names of the keys have changed.

The value of the feature.default.id key in 2.1 should be set as the value of the new eclipse.product key. The value of the eclipse.application should be set to "org.eclipse.ui.ide.workbench".

Finally, in 2.1 the image for the splash image was always splash.bmp in the branding plug-in's directory. In 3.0 the location of the splash image is provided explicitly by the osgi.splashPath key in the config.ini file.

Legal notices