# Incompatibilities between Eclipse 3.7 and 4.2

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

1. Platform keyring implementation removed
2. Compatibility bundles for Eclipse 1.0-2.1 removed
3. Bundle org.eclipse.help.appserver removed
4. Bundle org.eclipse.equinox.concurrent no longer in Platform feature
5. Update Manager bundles removed
6. Presentation API no longer functional
7. Workbench window advisor can no longer customize window creation
8. Servlet 3.0 and Jetty 8
9. Equinox OSGi console no longer built into the Equinox Framework

## 1. Platform keyring implementation removed

What is affected: Clients that call the following methods for storing and retrieving passwords in the platform keyring file:

- Platform#addAuthorizationInfo
- Platform#getAuthorizationInfo
- Platform#flushAuthorizationInfo
- Platform#addProtectionSpace
- Platform#getProtectionSpace

Description: These APIs were deprecated and superseded by new API in the `org.eclipse.equinox.security.storage` package in Eclipse 3.4. These APIs made use of a custom encryption algorithm that caused problems for organizations distributing and exporting Eclipse-based products. The system was also inherently flawed due to relying on a password supplied on the command line that users never set. In Eclipse 4.2 this problematic implementation has been removed. The API remains in place and will log an exception when used.

Action required: Clients that call these methods should instead use the corresponding Equinox security APIs for storing authentication information instead. Refer to the deprecation comment on each method for precise migration instructions.

## 2. Compatibility bundles for Eclipse 1.0-2.1 removed

What is affected:Bundles built for Eclipse 1.0 to 2.1 that have not been compiled in Eclipse 3.0 or later. Also, any bundle or feature that requires or includes a removed bundle.

Description: The following bundles provided implementation of compatibility mechanisms to support bundles compiled against Eclipse prior to version 3.0. These bundles have not contained any API since the 3.0 release, and no API is changed or removed as a consequence of these bundles being removed.

- org.eclipse.core.boot
- org.eclipse.ui.presentations.r21
- org.eclipse.ui.workbench.compatibility

Action required: Clients with a bundle or feature including or requiring any of these bundles should remove the requirement.

## 3. Bundle org.eclipse.help.appserver removed

What is affected:Any bundle or feature that requires or includes the bundle `org.eclipse.help.appserver`.

Description: This bundle provided implementation of a Tomcat-based web server application for the Eclipse help system. This was replaced in Eclipse 3.3 with a Jetty-based application server. This bundle defines no API and has been unused in the Eclipse platform for many releases.

Action required: Clients with a bundle or feature including or requiring the bundle `org.eclipse.help.appserver` should remove the requirement.

## 4. Bundle org.eclipse.equinox.concurrent no longer in Platform feature

What is affected:Any bundle or feature that requires or includes the bundle `org.eclipse.equinox.concurrent`.

Description:This bundle was never explicitly included in the Eclipse platform, but was installed due to an optional dependency from one of the platform's bundles. Due to a change in how optional dependencies are treated at install-time, this bundle is no longer included in the Eclipse platform. The bundle is still included in the Equinox SDK, and is included in both the Eclipse project and Juno release train central repositories.

Action required: Clients with a feature depending on but not directly including the bundle `org.eclipse.equinox.concurrent` will need to add a direct dependency if they need it.

## 5. Update Manager bundles removed

What is affected: Clients that rely on the provisional API or implementation found in the following bundles:

- org.eclipse.update.core
- org.eclipse.update.core.win32
- org.eclipse.update.scheduler
- org.eclipse.update.ui

Description: These provisional APIs were deprecated and superseded by new API provided by Equinox p2 in Eclipse 3.4. These bundles have been removed from the Eclipse SDK in 4.2, but remain available and fully compatible with 4.2 should any application or product require them.

Action required: Clients that rely on the provisional API or implementation in these bundles should migrate to the functionality and API provided by Equinox p2. Alternatively, products can install these bundles from the Eclipse 3.8 repository and they will continue to function in Eclipse 4.2-based applications.

## 6. Presentation API no longer functional

What is affected: Clients that the used the API in package `org.eclipse.ui.presentations`, or the `org.eclipse.ui.presentationFactories` extension point.

Description: The workbench presentation API allowed plug-ins to override certain aspects of the workbench appearance, such as the shape of view and editor tabs. This mechanism is fundamentally incompatible with the pluggable rendering and declarative styling systems in Eclipse 4.2, which offer applications complete control over all aspects of the workbench layout and style.

Action required: Using the presentation API and extension point to customize the workbench appearance will no longer have any effect. Clients are encouraged to try out the provisional new API in Eclipse 4.2 for performing equivalent workbench customization. Complete rendering control can be achieved by supplying an `org.eclipse.e4.ui.workbench.IPresentationEngine`. Customization of fonts, spacing, and color can be achieved by supplying custom CSS style sheets via the `org.eclipse.e4.ui.css.swt.theme` extension point. For more details, see the Eclipse 4 CSS Styling wiki page.

## 7. Workbench window advisor can no longer customize window creation

What is affected: Clients that implemented the API methods `createWindowContents` or `createEmptyWindowContents` on subclasses of `org.eclipse.ui.application.WorkbenchWindowAdvisor`.

Description: The workbench window advisor provided these methods for rich client applications to build customized workbench windows. This is achieved in Eclipse 4.2 by defining a customized application model, so these workbench window advisor methods are no longer used. Client implementations of these methods will no longer be called, and therefore no longer have any effect.

Action required: Clients that still customize many aspects of the workbench window layout by invoking the `set*` methods on `org.eclipse.ui.application.IWorkbenchWindowConfigurer`. Complete customization of the workbench window elements can be achieved by defining a custom workbench model for the application. For more details, see the Eclipse 4 workbench model wiki page.

## 8. Servlet 3.0 and Jetty 8

What is affected: Clients that relied on the Servlet and Jetty implementations provided by the platform.

Description: For the Juno release, Equinox will no longer support the use of older Jetty implementations and we are no longer shipping Jetty 6. The Equinox HTTP service implementation will no longer work with the Servlet 2.5 and JSP 2.1 APIs. Also note that the Jasper and expresson language implementation bundles have changed in order to support the Servlet 3.0 and JSP 2.2 specifications. The following bundles have been removed:

- org.apache.jasper
- org.apache.commons.el
- org.mortbay.jetty.server
- org.mortbay.jetty.util

These have been replaced with the following to support Servlet 3.0 and JSP 2.2:

- org.eclipse.jetty.continuation
- org.eclipse.jetty.http
- org.eclipse.jetty.io
- org.eclipse.jetty.security
- org.eclipse.jetty.server
- org.eclipse.jetty.servlet
- org.eclipse.jetty.util
- javax.el
- org.apache.jasper.glassfish
- com.sun.el

Action required: Clients relying on old Servlet and JSP specifications, or directly requiring old Jetty 6 packages and bundles, must migrate to the new Servlet 3.0 specification, and Jetty 8.

## 9. Equinox OSGi console no longer built into the Equinox Framework

What is affected:Any product or launch configuration that supports the Equinox -console command line option.

Description: The new Equinox console shell is based on Apache Felix Gogo shell and provides features upon it. It is decoupled from the framework itself. The built-in OSGi console provided by the Equinox framework (org.eclipse.osgi) is disabled by default. The new Equinox console is now provided by bundles which must be installed in order to support the -console option. The new console supports completely and transparently the traditional Equinox-style commands, and also supports the new Gogo-style commands. It also provides telnet and ssh connectivity.

Action required: In order to use Equinox with the new shell, it is necessary to install along with the framework also the console bundle itself - org.eclipse.equinox.console and the three Gogo bundles - org.apache.felix.gogo.runtime, org.apache.felix.gogo.command, org.apache.felix.gogo.shell. A detailed documentation for the new Equinox console is available at Console Shell. The old built-in Equinox OSGi console shell may be enabled by specifying the following configuration property:

      osgi.console.enable.builtin=true