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.
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.
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 |
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, you must 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.
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, you must 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.
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:
org.eclipse.core.runtime.jobs.ILock
.
The advantage of ILock
over generic locks is that they transfer
automatically to the UI thread when doing a syncExec
, and there is
deadlock detection support built into their implementation that logs and
then resolves deadlocks.Display.asyncExec
), which
is processed entirely in the UI thread.java.lang.String
and org.eclipse.core.runtime.IPath
thread safe. The advantage of
immutable objects is extremely fast read access, at the cost of extra work
on modification.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.)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.
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.
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
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.
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.
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.
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.
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.
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:
Changes to org.eclipse.ui.texteditor.AbstractTextEditor:
ResourceAction action= new AddMarkerAction(TextEditorMessages.getResourceBundle(), "Editor.AddBookmark.", this, IMarker.BOOKMARK, true); //$NON-NLS-1$ action.setHelpContextId(ITextEditorHelpContextIds.BOOKMARK_ACTION); action.setActionDefinitionId(ITextEditorActionDefinitionIds.ADD_BOOKMARK); setAction(IDEActionFactory.BOOKMARK.getId(), action);
action= new AddTaskAction(TextEditorMessages.getResourceBundle(), "Editor.AddTask.", this); //$NON-NLS-1$ action.setHelpContextId(ITextEditorHelpContextIds.ADD_TASK_ACTION); action.setActionDefinitionId(ITextEditorActionDefinitionIds.ADD_TASK); setAction(IDEActionFactory.ADD_TASK.getId(), action);
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:
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
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.
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.
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.
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.
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.
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.
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.
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:
PRE_DELETE
or PRE_CLOSE
event notification if applicablePRE_AUTO_BUILD
event notificationPOST_AUTO_BUILD
event notificationPOST_CHANGE
event notificationWith 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:
PRE_DELETE
or PRE_CLOSE
event notification if applicablePOST_CHANGE
event notificationPeriodically, 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:
PRE_BUILD
event notification (PRE_BUILD
is the
new name for PRE_AUTO_BUILD)
POST_BUILD
event notification (POST_BUILD
is the
new name for POST_AUTO_BUILD)
POST_CHANGE
event notificationThe 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:
POST_CHANGE
listeners receive notification of absolutely all
resource changes that occur during the time they are registered. This
includes changes made by builders, and changes made by other listeners.PRE_AUTO_BUILD
listeners receive notification of all resource
changes except changes made by builders and resource change
listeners.POST_AUTO_BUILD
listeners receive notification of all resource
changes except changes made by other POST_AUTO_BUILD
listeners.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.
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.
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);
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.
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.
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.
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.
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)
).
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.
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.
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.
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
.
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.
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
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"/>
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"/>
What is affected: Scripts (e.g., Ant build.xml files) using the eclipse.buildScript task.
Description: PDE Build changed the behavior 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" .../>
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.