bundles/org.eclipse.platform.doc.isv/porting/removals.html - platform/eclipse.platform.common - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 <html lang="en">
 <head>
 <meta name="copyright" content="Copyright (c) IBM Corporation and others 2011, 2013. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
 <meta http-equiv="Content-Style-Type" content="text/css">
 <link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css">
 <title>Deprecated API removals</title>
 </head>
 <body>
 <h1>Deprecated API removals</h1>

 <p>
   Often there is no sufficiently compelling reason to ever remove deprecated API, so the
   API may remain in place indefinitely after the release in which it was deprecated.
   However, there are situations where continuing to maintain the deprecated API
   creates too high a burden for both API developers and clients: the code bloat of
   keeping old implementations, the added complexity of multiple redundant APIs, etc.
   For this reason the Eclipse project has a
   <a href="http://wiki.eclipse.org/Eclipse/API_Central/Deprecation_Policy">policy</a>
   to occasionally delete deprecated API after providing two years advance notice to clients.
   This section describes API removals that occurred in this release, and upcoming
   removals in future releases.
 </p>

 <p>
 API removals in the Kepler (4.3) release:
 </p>
 <ol>
  <li><a href="#luceneSearchParticipants">luceneSearchParticipants</a></li>
 </ol>

 <p>
 API removals after June 2013:
 </p>
 <ol>
  <li><a href="#workspaceLock">WorkspaceLock</a></li>
  <li><a href="#incrementalProjectBuilder_getRule">IncrementalProjectBuilder#getRule()</a></li>
 </ol>
 <p>
 API removals after June 2014:
 </p>
 <ol>
  <li><a href="#presentation">Workbench presentation API</a></li>
  <li><a href="#runtime">Eclipse 2.0 runtime model and boot API</a></li>
  <li><a href="#auth">Platform authorization API</a></li>
  <li><a href="#compositeBundles">Composite Bundles</a></li>
  <li><a href="#batchBundleEvent">Batch Bundle Event</a></li>
 </ol>

 <hr>

 <!-- ############################################## -->

 <h2>API removals in this release</h2>

 <h3>1. <a name="luceneSearchParticipants">luceneSearchParticipants</a></h3>
 <p>
 The extension point <code>org.eclipse.help.base.luceneSearchParticipants</code>
 used API classes which exposed classes from Apache Lucene in their method parameters.
 This means that clients would be impacted with at least binary incompatibility if the Eclipse
 Help system switched from Lucene 1.x to 2.x or 3.x and has caused the help system
 to stay on an old version of Lucene. In the 3.6 release this extension point and the classes
 it requires were deprecated. The replacement extension point
 <code>org.eclipse.help.base.searchParticipant</code> should be used instead.
 The specific API being removed includes:
 </p>
 <ul>

 <li>The extension point org.eclipse.help.base.luceneSearchParticipants</li>
 <li>The class org.eclipse.help.search.LuceneSearchParticipant</li>
 <li>The class org.eclipse.help.search.ISearchIndex</li>
 <li>The class org.eclipse.help.search.XMLSearchParticipant</li>

 </ul>
 <p>
 For further details or to provide feedback on this change, see <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=311931">bug 311931</a>.
 </p>

 <!-- ############################################## -->

 <h2>API removals after June 2013</h2>

 <h3>1. <a name="workspaceLock">WorkspaceLock</a></h3>
 <p>
 The <code>WorkspaceLock</code> API allowed a special client (usually platform UI) to
 hook into the locking protocols used by the workspace implementation. This hook
 was used to mitigate deadlocks due to interaction with synchronous SWT events,
 and was never intended to be used by other clients. In the 3.0 release this API
 was deprecated in favor of a more general API provided by the <code>org.eclipse.core.jobs</code>
 bundle. Invoking this API has had no effect since the 3.0 release. The specific API
 to be removed includes:
 </p>
 <ul>
 <li>The <code>org.eclipse.core.resources.WorkspaceLock</code> class.</li>
 <li>The method <code>org.eclipse.core.resources.IWorkspace#setWorkspaceLock</code></li>
 </ul>
 <p>
 For further details or to provide feedback on this change, see <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=311240">bug 311240</a>.
 </p>

 <!-- ############################################## -->

 <h3>2. <a name="incrementalProjectBuilder_getRule">IncrementalProjectBuilder#getRule()</a></h3>
 <p>
 The <code>IncrementalProjectBuilder#getRule()</code> method returned a scheduling rule
 that was required for building the project by the builder. This method was intended to be used by the builder framework only.
 In the 3.6 release this method was deprecated in favor of a more general method <code>IncrementalProjectBuilder#getRule(int, Map)</code>.
 The specific API to be removed includes:
 </p>
 <ul>
 <li>The method <code>org.eclipse.core.resources.IncrementalProjectBuilder#getRule()</code></li>
 </ul>
 <p>
 For further details or to provide feedback on this change, see <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=310072">bug 310072</a>.
 </p>

 <!-- ############################################## -->

 <h2>API removals after June 2014</h2>

 <h3>1. <a name="presentation">Workbench presentation API</a></h3>
 <p>
 The workbench <i>presentation API</i> 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. The following API will be removed:
 </p>
 <ul>
 <li>API package <tt>org.eclipse.ui.presentations</tt></li>
 <li>Extension point <tt>org.eclipse.ui.presentationFactories</tt></li>
 </ul>
 <p>
 For further details or to provide feedback on this change, see <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=370248">bug 370248</a>.
 </p>

 <h3>2. <a name="runtime">Eclipse 2.0 runtime model and boot API</a></h3>
 <p>
 When the Eclipse runtime transitioned to use OSGi as its implementation, some existing
 APIs for interacting with the old runtime were deprecated and moved to a compatibility fragment
 (<tt>org.eclipse.core.runtime.compatibility</tt>). All API that was still valid was moved
 elsewhere. These APIs have been non-functional since Eclipse 3.0 and will therefore
 be removed in the future. The following packages will be removed:
 </p>
 <ul>
  <li><tt>org.eclipse.core.boot</tt></li>
  <li><tt>org.eclipse.core.runtime.model</tt></li>
  </ul>
  The compatibility fragment, <tt>org.eclipse.core.runtime.compatibility</tt> will
  also be removed.
 <p>
 For further details or to provide feedback on this change, see <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=370248">bug 370248</a>.
 </p>

 <h3>3. <a name="auth">Platform authorization API</a></h3>
 <p>
 Since Eclipse 1.0, the Eclipse Platform class provided API for storing and retrieving
 passwords in a keyring file. This API used an inherently insecure method for encrypting
 credentials, and used a custom encryption algorithm that made it difficult for some
 consumers to distribute and export Eclipse-based products. For these and other reasons,
 this API was deprecated and replaced in Eclipse 3.4 with a new Equinox secure storage API.
 In Eclipse 4.2 the implementation of the old authorization methods was removed, but the API left in place.
 This old API will be removed completely in a future release. The following API methods will
 be removed from <tt>org.eclipse.core.runtime.Platform</tt>:
 </p>
 <ul>
  <li><tt>addAuthorizationInfo(URL serverUrl, String realm, String authScheme, Map info)</tt></li>
  <li><tt>getAuthorizationInfo(URL serverUrl, String realm, String authScheme)</tt></li>
  <li><tt>flushAuthorizationInfo(URL serverUrl, String realm, String authScheme)</tt></li>
  <li><tt>addProtectionSpace(URL resourceUrl, String realm)</tt></li>
  <li><tt>getProtectionSpace(URL resourceUrl)</tt></li>
  </ul>
 <p>
 For further details or to provide feedback on this change, see <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=370248">bug 370248</a>.
 </p>

 <!-- ############################################## -->

 <h3>4. <a name="compositeBundles">Composite Bundles</a></h3>
 <p>
 In the Equinox 3.5 release an implementation of an OSGi provisional API was
 included for composite bundles.  This API includes all classes from the
 <code>org.osgi.service.framework package</code>.  This provisional OSGi API has never been
 considered API by Equinox and as such has always been marked as x-internal.
 </p>
 <p>
 The OSGi Alliance has decided to reject this provisional API.  It will never
 become a part of the official OSGi specification.  Any users of the
 <code>org.osgi.service.framework</code> composite bundle API must migrate to using framework
 hooks to provide additional isolation within a single OSGi framework.  See the
 sub-packages of <code>org.osgi.framework.hooks</code> for ways to control
 visibility and isolation for resolution, bundles and services.  Equinox plans to
 remove the <code>org.osgi.service.framework</code> API and composite bundle implementation
 in the Summer of 2012 (after the 3.8 release).
 </p>
 <p>
 Equinox also has a region digraph implementation that allows for the definition
 and configuration of regions that can be used to isolate bundles.  The region
 digraph is built on top of the standard OSGi framework hooks.

 The specific API to be removed includes:
 </p>
 <ul>

 <li>The complete org.osgi.service.framework package</li>

 </ul>
 <p>
 For further details or to provide feedback on this change, see <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=345790">bug 345790</a>.
 </p>

 <!-- ############################################## -->

 <h3>5. <a name="batchBundleEvent">Batch Bundle Event</a></h3>
 <p>
 Since Eclipse 3.1, the Equinox Framework has provided API to allow bundle
 listeners to batch bundle events.  This functionality never has been
 standardized with OSGi and the approach as several drawbacks that make the
 API difficult to use.  For these and other reasons the API package
 <tt>org.eclipse.osgi.event</tt> will be removed.
 </p>
 <p>
 For further details or to provide feedback on this change, see <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=407302">bug 407302</a>.
 </p>

 <!-- ############################################## -->

 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	<html lang="en">
	<head>
	<meta name="copyright" content="Copyright (c) IBM Corporation and others 2011, 2013. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
	<meta http-equiv="Content-Style-Type" content="text/css">
	<link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css">
	<title>Deprecated API removals</title>
	</head>
	<body>
	<h1>Deprecated API removals</h1>

	<p>
	Often there is no sufficiently compelling reason to ever remove deprecated API, so the
	API may remain in place indefinitely after the release in which it was deprecated.
	However, there are situations where continuing to maintain the deprecated API
	creates too high a burden for both API developers and clients: the code bloat of
	keeping old implementations, the added complexity of multiple redundant APIs, etc.
	For this reason the Eclipse project has a
	<a href="http://wiki.eclipse.org/Eclipse/API_Central/Deprecation_Policy">policy</a>
	to occasionally delete deprecated API after providing two years advance notice to clients.
	This section describes API removals that occurred in this release, and upcoming
	removals in future releases.
	</p>

	<p>
	API removals in the Kepler (4.3) release:
	</p>
	<ol>
	<li><a href="#luceneSearchParticipants">luceneSearchParticipants</a></li>
	</ol>

	<p>
	API removals after June 2013:
	</p>
	<ol>
	<li><a href="#workspaceLock">WorkspaceLock</a></li>
	<li><a href="#incrementalProjectBuilder_getRule">IncrementalProjectBuilder#getRule()</a></li>
	</ol>
	<p>
	API removals after June 2014:
	</p>
	<ol>
	<li><a href="#presentation">Workbench presentation API</a></li>
	<li><a href="#runtime">Eclipse 2.0 runtime model and boot API</a></li>
	<li><a href="#auth">Platform authorization API</a></li>
	<li><a href="#compositeBundles">Composite Bundles</a></li>
	<li><a href="#batchBundleEvent">Batch Bundle Event</a></li>
	</ol>

	<hr>

	<!-- ############################################## -->

	<h2>API removals in this release</h2>

	<h3>1. <a name="luceneSearchParticipants">luceneSearchParticipants</a></h3>
	<p>
	The extension point <code>org.eclipse.help.base.luceneSearchParticipants</code>
	used API classes which exposed classes from Apache Lucene in their method parameters.
	This means that clients would be impacted with at least binary incompatibility if the Eclipse
	Help system switched from Lucene 1.x to 2.x or 3.x and has caused the help system
	to stay on an old version of Lucene. In the 3.6 release this extension point and the classes
	it requires were deprecated. The replacement extension point
	<code>org.eclipse.help.base.searchParticipant</code> should be used instead.
	The specific API being removed includes:
	</p>
	<ul>

	<li>The extension point org.eclipse.help.base.luceneSearchParticipants</li>
	<li>The class org.eclipse.help.search.LuceneSearchParticipant</li>
	<li>The class org.eclipse.help.search.ISearchIndex</li>
	<li>The class org.eclipse.help.search.XMLSearchParticipant</li>

	</ul>
	<p>
	For further details or to provide feedback on this change, see <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=311931">bug 311931</a>.
	</p>

	<!-- ############################################## -->

	<h2>API removals after June 2013</h2>

	<h3>1. <a name="workspaceLock">WorkspaceLock</a></h3>
	<p>
	The <code>WorkspaceLock</code> API allowed a special client (usually platform UI) to
	hook into the locking protocols used by the workspace implementation. This hook
	was used to mitigate deadlocks due to interaction with synchronous SWT events,
	and was never intended to be used by other clients. In the 3.0 release this API
	was deprecated in favor of a more general API provided by the <code>org.eclipse.core.jobs</code>
	bundle. Invoking this API has had no effect since the 3.0 release. The specific API
	to be removed includes:
	</p>
	<ul>
	<li>The <code>org.eclipse.core.resources.WorkspaceLock</code> class.</li>
	<li>The method <code>org.eclipse.core.resources.IWorkspace#setWorkspaceLock</code></li>
	</ul>
	<p>
	For further details or to provide feedback on this change, see <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=311240">bug 311240</a>.
	</p>

	<!-- ############################################## -->

	<h3>2. <a name="incrementalProjectBuilder_getRule">IncrementalProjectBuilder#getRule()</a></h3>
	<p>
	The <code>IncrementalProjectBuilder#getRule()</code> method returned a scheduling rule
	that was required for building the project by the builder. This method was intended to be used by the builder framework only.
	In the 3.6 release this method was deprecated in favor of a more general method <code>IncrementalProjectBuilder#getRule(int, Map)</code>.
	The specific API to be removed includes:
	</p>
	<ul>
	<li>The method <code>org.eclipse.core.resources.IncrementalProjectBuilder#getRule()</code></li>
	</ul>
	<p>
	For further details or to provide feedback on this change, see <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=310072">bug 310072</a>.
	</p>

	<!-- ############################################## -->

	<h2>API removals after June 2014</h2>

	<h3>1. <a name="presentation">Workbench presentation API</a></h3>
	<p>
	The workbench <i>presentation API</i> 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. The following API will be removed:
	</p>
	<ul>
	<li>API package <tt>org.eclipse.ui.presentations</tt></li>
	<li>Extension point <tt>org.eclipse.ui.presentationFactories</tt></li>
	</ul>
	<p>
	For further details or to provide feedback on this change, see <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=370248">bug 370248</a>.
	</p>

	<h3>2. <a name="runtime">Eclipse 2.0 runtime model and boot API</a></h3>
	<p>
	When the Eclipse runtime transitioned to use OSGi as its implementation, some existing
	APIs for interacting with the old runtime were deprecated and moved to a compatibility fragment
	(<tt>org.eclipse.core.runtime.compatibility</tt>). All API that was still valid was moved
	elsewhere. These APIs have been non-functional since Eclipse 3.0 and will therefore
	be removed in the future. The following packages will be removed:
	</p>
	<ul>
	<li><tt>org.eclipse.core.boot</tt></li>
	<li><tt>org.eclipse.core.runtime.model</tt></li>
	</ul>
	The compatibility fragment, <tt>org.eclipse.core.runtime.compatibility</tt> will
	also be removed.
	<p>
	For further details or to provide feedback on this change, see <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=370248">bug 370248</a>.
	</p>

	<h3>3. <a name="auth">Platform authorization API</a></h3>
	<p>
	Since Eclipse 1.0, the Eclipse Platform class provided API for storing and retrieving
	passwords in a keyring file. This API used an inherently insecure method for encrypting
	credentials, and used a custom encryption algorithm that made it difficult for some
	consumers to distribute and export Eclipse-based products. For these and other reasons,
	this API was deprecated and replaced in Eclipse 3.4 with a new Equinox secure storage API.
	In Eclipse 4.2 the implementation of the old authorization methods was removed, but the API left in place.
	This old API will be removed completely in a future release. The following API methods will
	be removed from <tt>org.eclipse.core.runtime.Platform</tt>:
	</p>
	<ul>
	<li><tt>addAuthorizationInfo(URL serverUrl, String realm, String authScheme, Map info)</tt></li>
	<li><tt>getAuthorizationInfo(URL serverUrl, String realm, String authScheme)</tt></li>
	<li><tt>flushAuthorizationInfo(URL serverUrl, String realm, String authScheme)</tt></li>
	<li><tt>addProtectionSpace(URL resourceUrl, String realm)</tt></li>
	<li><tt>getProtectionSpace(URL resourceUrl)</tt></li>
	</ul>
	<p>
	For further details or to provide feedback on this change, see <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=370248">bug 370248</a>.
	</p>

	<!-- ############################################## -->

	<h3>4. <a name="compositeBundles">Composite Bundles</a></h3>
	<p>
	In the Equinox 3.5 release an implementation of an OSGi provisional API was
	included for composite bundles. This API includes all classes from the
	<code>org.osgi.service.framework package</code>. This provisional OSGi API has never been
	considered API by Equinox and as such has always been marked as x-internal.
	</p>
	<p>
	The OSGi Alliance has decided to reject this provisional API. It will never
	become a part of the official OSGi specification. Any users of the
	<code>org.osgi.service.framework</code> composite bundle API must migrate to using framework
	hooks to provide additional isolation within a single OSGi framework. See the
	sub-packages of <code>org.osgi.framework.hooks</code> for ways to control
	visibility and isolation for resolution, bundles and services. Equinox plans to
	remove the <code>org.osgi.service.framework</code> API and composite bundle implementation
	in the Summer of 2012 (after the 3.8 release).
	</p>
	<p>
	Equinox also has a region digraph implementation that allows for the definition
	and configuration of regions that can be used to isolate bundles. The region
	digraph is built on top of the standard OSGi framework hooks.

	The specific API to be removed includes:
	</p>
	<ul>

	<li>The complete org.osgi.service.framework package</li>

	</ul>
	<p>
	For further details or to provide feedback on this change, see <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=345790">bug 345790</a>.
	</p>

	<!-- ############################################## -->

	<h3>5. <a name="batchBundleEvent">Batch Bundle Event</a></h3>
	<p>
	Since Eclipse 3.1, the Equinox Framework has provided API to allow bundle
	listeners to batch bundle events. This functionality never has been
	standardized with OSGi and the approach as several drawbacks that make the
	API difficult to use. For these and other reasons the API package
	<tt>org.eclipse.osgi.event</tt> will be removed.
	</p>
	<p>
	For further details or to provide feedback on this change, see <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=407302">bug 407302</a>.
	</p>

	<!-- ############################################## -->

	</body>
	</html>