equinox
migration guide

 

Summary
This document details the API changes between the standard Eclipse runtime (e.g., Eclipse 3.0 M5) to the OSGi-based runtime developed in the Equinox project (e.g., Eclipse 3.0 M6). Information on migrating workspaces, code and general workspace setup can be found in the Adoption Guide and information on how to use the new runtime is contained in the Users Guide.
Last Modified: 2300 November 25, 2003

API Changes

For each of the API changes listed below, there is a corresponding Bugzilla bug report number. Readers are encouraged to comment on or track these bug reports as a way of providing feedback into the Eclipse runtime design and implementation process. All migration related bug reports have [migration] prepended to the summary line. Users can query Bugzilla to get up to date information on new issues as well as status on old/resolved issues.

URL Stream Handler extensions (43400)

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

Description: OSGi provides a URL Stream Handler service much like that supported by Eclipse runtime. This allows people to register URL stream handlers for different URL protocols (e.g., jndi: URLs). 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. The OSGi framework provides a handy abstract superclass (org.osgi.service.url.AbstractURLStreamHandlerService) that does the bulk of this work.

Unfortunately, legacy plug-ins which supply URL handler contributions (extensions to the org.eclipse.core.runtime.urlHandlers extension point) implement only the java.net.URLStreamHandler contract. Since all of the methods on URLStreamHandler are protected, it is not possible for the runtime compatibility layer to simply wrap such handlers to and give them the required behaviour. Rather, the implementation of the handler must be updated either to implement org.osgi.service.url.URLStreamHandlerService or to extend org.osgi.service.url.AbstractURLStreamHandlerService.

Analysis: Very few plug-ins use this facility. A quick scan of major Eclipse-based products (e.g., WSAD) failed to uncover any uses. Eclipse itself uses this capability in the Help area (e.g., for help: and jndi: URLs). This has usage has been updated as described above.

Technical notes: We continue to look for ways of wrappering supplied URLStreamHandlers and thus supplying full compatibility support. Failing this, the minor code changes described here are required.

Classload order (43401)

Who is affected: Plug-ins which supply packages provided which are also supplied by other plug-ins.

Description: In standard Eclipse, classloader search for classes using the so-called PSP ordering. That is, a given classloader would first consult its parent classloader (in practice this is the Java boot classloader), then its own classpath contents (i.e., self) and finally all of its prerequisites in declared order. OSGi offers an optimization over this model, the so-called P-P|S (read P, P or S) ordering. In this approach a classloader will consult its parent (again, effectively the Java boot classloader), then either a single prerequisite known to contribute classes in the package being queried OR its own classpath entries for the desired class.

The classloader determines whether to consult self or its prerequisites based on its imported packages. This information is inferred from the plug-in content in the case of legacy plug-ins and directly specified in the case of new plug-ins. In either case, it is known a priori which classloaders 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 contain various classes from org.xml packages. Under the PSP model, 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. Under the P-P|S model, only one of the two plug-ins contributes the duplicate classes and both plug-ins see the same copies.

Analysis: In a very limited number of cases the new behaviour will change which classes are found. Note however that this may actually be beneficial (see above).

Support for multiple plug-in versions (43402)

Who is affected: System integrators/product developers expecting to configure overlapping sets of plug-ins with different version numbers into one Eclipse install.

Description: Eclipse allows multiple versions of the same plug-in to co-exist. Since OSGi resolves package imports/exports to one version it does not support multiple plug-in versions. There are two proposals for adding multiversion support to the OSGi framework. Both are feasible but differ in how version differences are propogated.

Analysis: This usecase is real and the lack of support is temporary. The Equinox team is busily working on this issue and hope to resolve it shortly.

Package duplication (43403)

Who is affected: Plug-ins which export whole packages which are also exported by other plug-ins.

Description: Eclipse allows multiple copies of the same package to co-exist (in different plug-ins). Since OSGi resolves package imports/exports to one version it does not support multiple package copies.

Analysis: This usecase is real and the lack of support is temporary. A solution to this issue is currently being implemented by the Equinox team.

Default package content cannot be shared

Who is affected: Plug-ins which expect to use types or resources in the default package of another plug-in

Description: In OSGi the only way for one bundle to access the code or resources from another bundle is if the latter exports the package containing the target code or resources. It is not possible to export the default package as all bundles have the default package and the runtime would choose just one under the normal package resolutions rules. In the Eclipse runtime this is not a problem since code/resource sharing was available at the whole plug-in level (i.e., everything in a plug-in could be made available to dependents).

Analysis: The incidence of default package use is very low so the affects are not widespread. For example, we have seen this in test suites where the test bundles try to access files from the test target using getResource() and the required file happens to be in the root of a jar on the classpath.

Plug-in developers can address this by moving such files but moving them to, say icons/ in the jar (rather than the root) does not help because the package "icons" would have to be exported and would surely conflict with some other bundle doing the same. The best approach is to either put the files in a real, unique, package or remove such files from the classpath and access them via the Bundle.getFileEntry() API.

Technical notes: This issue could be addressed in backwards compatible way as part of the bundle as module work. If the dependent bundle imports the prerequisite bundle (rather than specific packages), it should have access to the prerequisite's entire list of provided packages. This list would include the default package.

PluginModel object casting (43404)

Who is affected: Plug-ins which cast objects of type IPlugin* to Plugin*Model.

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 implementation it happens that the model classes implement the relevant interfaces. In the runtime we are unable to maintain this relationship.

Analysis: The relationship between the interfaces and the model classes is not a specified part of the API. We have found however that PDE takes advantage of this assumption. We do not expect there to be many (any) other uses of this relationship and the PDE code is quite easily changed.

Invalid assumptions regarding the form of URLs (43406)

Who is affected: Plug-ins which 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 this form not being specified, various plug-ins make 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 unsafe approach. For example, if a plug-in is installed on a web server, it is possible that an http: URL would be returned. The OSGi runtime opens more possibilities for execution configurations (e.g., maintaining whole plugins in JARs rather than exploded in directories).

Analysis: The new runtime does not actually break current behaviour but as described above, it exposes more cases where current assumptions are invalid. Plug-in writers should ensure that the information to which they need access is available via getResource(), use the relevant API for accessing the contents of a bundle/plug-in.

Plug-ins hosting classpath entries for fragments (43658)

Who is affected: Plug-ins which declare classpath entries in their plugin.xml file but where the actual jars are intended to be supplied by fragments to the plug-in and fragments which expect to see package visible code in their host.

Description: Standard Eclipse manages fragments by seamlessly merging the entries in their fragment.xml files with those of the host plug-in's plugin.xml file. For example, at runtime only the host has a classloader. This classloader loads the classes from the plug-in as well as all the fragments. This leads to situations where the host specifies a classpath entry such as "$ws$/swt.jar" but does not in fact supply the swt.jar.

Under this new model, there is no reason for the host to specify a vacuous classpath entry. Rather, it should remain silent about jars potentially supplied by fragments and leave them to specify their own classpath.

The new fragment model sees fragments as first class entities which have classloaders of their own (if needed) but yet delegate class/resource discovery to the classloader of their host prior to consulting their own classpath. This is similar to the standard Eclipse approach but leads to a situation where package visible code in the host is not visible to code in the same package in fragments. This happens because the two packages in question are actually managed by different classloaders and so are in fact different packages.

Analysis: The current Eclipse behaviour is somewhat anomalous in that the runtime and the tooling have to take exceptional measures when computing the classpath related to a set of fragments and their host plug-in. The new approach simplifies this but does make it harder to generate the bundle manifests corresponding to the plugin.xml and fragment.xmls using the old model. For example, the current Equinox runtime relies on the SWT elements to include hand-crafted manifest files with the characteristics outlined above.

The ability of fragments to see package visibility code in their host is an asset for people writing tests and tools. For example, the Core Tools use this to access internals of the runtime and resources plugins and interpret the behaviour of these components. Similarly, white box test suites can be constructed using package visible code and thus not forcing the exposure of internals as public code.

Technical notes: The Equinox team is investigating the fragment classloading semantics to see if it is possible to merge the fragment and host classpaths. They are also looking at enhancing the plug-in converter to analyze potential cases and generate the appropriate classpath entries in the bundle and fragment manifests.

Plug-in Development Notes

Additional projects required

Who is affected: Plug-in developers setting up runtime workspaces or maintaining build scripts.

Description: Several new plug-ins have been added to support the new runtime. When setting up a runtime workspace, developers will need to add projects for these of these plug-ins to enable compilation. For more details, see the Equinox Runtime Adoption Guide.

Build-related issues

Who is affected: Writers of bundles who want to make those bundles available people using plug-in oriented tooling.

Description: Current build structures (e.g., PDE, custom builds done by product teams, ...) are based on plug-ins, fragments and features. While the new runtime supports these components, it is bundle based. To support existing build structures we (and other bundle developers) must take care to include plugin.xml and fragment.xml files (as appropriate) for all bundles. This allows the tooling and build mechanisms to correctly interpret the content of the bundle and make it available.

Analysis: By maintaining the plugin.xml content, tooling and build mechanisms will continue to function. As these are updated to handle the new structures, the need to maintain plugin.xml and fragment.xml files will diminish.