bundles/org.eclipse.platform.doc.isv/porting/4.7/incompatibilities.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) 2016, 2017 IBM Corporation and others. 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=UTF-8">
 <meta http-equiv="Content-Style-Type" content="text/css">
 <link rel="STYLESHEET" href="../../book.css" charset="ISO-8859-1" type="text/css">
 <title>Incompatibilities between Eclipse 4.6 and 4.7</title>
 </head>

 <body>

 <h1>Incompatibilities between Eclipse 4.6 and 4.7</h1>

 <p>
   Eclipse changed in incompatible ways between 4.6 and 4.7 in ways that affect
   plug-ins. The following entries describe the areas that changed and provide
   instructions for migrating 4.6 plug-ins to 4.7. Note that you only need to look
   here if you are experiencing problems running your 4.6 plug-in on 4.7.
 </p>
 <p>
 See also the list of <a href="../removals.html">deprecated API removals</a> for this release.
 </p>

 <ol>
 <li><a href="#progress-convention">New calling convention for progress monitors</a></li>
 </ol>

 <hr>

 <!-- ############################################## -->
 <h2><a name="progress-convention">1. New calling convention for progress monitors</a></h2>

 <p><strong>What is affected:</strong>
 <p>All methods which obtain their own top-level IProgressMonitor.</p>

 <p><strong>Description:</strong>
 <p>
 In order to reduce boilerplate code, Eclipse 4.7 has introduced a new calling convention for
 methods which receive an <code>org.eclipse.core.runtime.IProgressMonitor</code> as a parameter. In Eclipse 4.7 it is the
 caller's responsibility to invoke <code>done()</code> on IProgressMonitor rather than the
 receiver's. Callers can choose to use SubMonitor, which doesn't require the use of
 <code>done()</code>. This means that &mdash; in practice &mdash; most
 invocations of <code>done()</code> will be deleted along with their surrounding try/catch blocks.
 <p>
 This is not a breaking change for methods which receive a progress monitor as an argument, since
 they can tolerate callers whether or not the caller invokes done(). However, it may be a breaking
 change for methods that obtain their own top-level progress monitors.
 <p>
 Methods which obtain their own top-level progress monitors rather than receiving one as a
 parameter are now responsible for invoking done() on those monitors. Technically, they were
 always responsible for doing this, but some of them didn't do so because any method they
 passed it to would have invoked done() on their behalf. Now this will matter and the methods
 will need to be changed. For example:

 <pre>
 // Before:
 public void doSaveAs() {
   IProgressMonitor monitor= getProgressMonitor();
   performSaveAs(monitor);
 }
 </pre>

 <pre>
 // After:
 public void doSaveAs() {
   IProgressMonitor monitor= getProgressMonitor();
     try {
       performSaveAs(monitor);
     } finally {
       monitor.done();
     }
 }
 </pre>

 <p>
 Fortunately there are few of these methods and they are easy to find.
 <p>
 <strong>Action required:</strong>
 <ul>
 <li>Open the Call Hierarchy on <code>StatusLineManager#getProgressMonitor()</code>.</li>
 <li>Ensure that all callers of these methods contain a finally block that
     invokes done (as in the doSaveAs() example, above).</li>
 <li>Open the Type Hierarchy of <code>IProgressMonitor</code>. Look for progress monitors which do something in
     their done() method besides reporting work, setting a task name, or calling done on another
     monitor. SubMonitor can be ignored. Monitors which set a control's visibility or deallocate a
     resource in their done() method must not be ignored.</li>
 <li>Use the Call Hierarchy view to locate every place that instantiates or accesses an instance of
     one of those classes. Ensure that those access points contain a try/finally block that invokes done().</li>
 </ul>

 <p><strong>More Information:</strong>
 <p>
 See <a href="https://eclipse.org/articles/Article-Progress-Monitors/article.html" target="_blank">this article</a> for
 more examples of how to use progress monitors with the new calling convention. Background and discussion
 about this change <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=487372" target="_blank">can be found here.</a>


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

 <h2>2. <a name="bidi-1.0.0">javax.xml removed from org.eclipse.e4.rcp feature</a></h2>
 <p><strong>What is affected:</strong> Clients that refer to
 the <code>javax.xml</code> bundle and use the <code>org.eclipse.e4.rcp</code> feature for that dependency.
 </p>
 <p><strong>Description:</strong>

 The <code>javax.xml</code> plug-in has been removed from the <code>org.eclipse.e4.rcp</code> feature.
 The <code>javax.xml</code> package is provided by JavaSE 1.7 and the Eclipse Platform requires Java 1.8.
 </p>
 If you have a dependency to this bundle and if you are using the
 org.eclipse.e4.rcp you need to adjust require-bundle: javax.xml to
 import-package in the corresponding MANIFEST.MF.

 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	<html lang="en">
	<head>
	<meta name="copyright" content="Copyright (c) 2016, 2017 IBM Corporation and others. 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=UTF-8">
	<meta http-equiv="Content-Style-Type" content="text/css">
	<link rel="STYLESHEET" href="../../book.css" charset="ISO-8859-1" type="text/css">
	<title>Incompatibilities between Eclipse 4.6 and 4.7</title>
	</head>

	<body>

	<h1>Incompatibilities between Eclipse 4.6 and 4.7</h1>

	<p>
	Eclipse changed in incompatible ways between 4.6 and 4.7 in ways that affect
	plug-ins. The following entries describe the areas that changed and provide
	instructions for migrating 4.6 plug-ins to 4.7. Note that you only need to look
	here if you are experiencing problems running your 4.6 plug-in on 4.7.
	</p>
	<p>
	See also the list of <a href="../removals.html">deprecated API removals</a> for this release.
	</p>

	<ol>
	<li><a href="#progress-convention">New calling convention for progress monitors</a></li>
	</ol>

	<hr>

	<!-- ############################################## -->
	<h2><a name="progress-convention">1. New calling convention for progress monitors</a></h2>

	<p><strong>What is affected:</strong>
	<p>All methods which obtain their own top-level IProgressMonitor.</p>

	<p><strong>Description:</strong>
	<p>
	In order to reduce boilerplate code, Eclipse 4.7 has introduced a new calling convention for
	methods which receive an <code>org.eclipse.core.runtime.IProgressMonitor</code> as a parameter. In Eclipse 4.7 it is the
	caller's responsibility to invoke <code>done()</code> on IProgressMonitor rather than the
	receiver's. Callers can choose to use SubMonitor, which doesn't require the use of
	<code>done()</code>. This means that — in practice — most
	invocations of <code>done()</code> will be deleted along with their surrounding try/catch blocks.
	<p>
	This is not a breaking change for methods which receive a progress monitor as an argument, since
	they can tolerate callers whether or not the caller invokes done(). However, it may be a breaking
	change for methods that obtain their own top-level progress monitors.
	<p>
	Methods which obtain their own top-level progress monitors rather than receiving one as a
	parameter are now responsible for invoking done() on those monitors. Technically, they were
	always responsible for doing this, but some of them didn't do so because any method they
	passed it to would have invoked done() on their behalf. Now this will matter and the methods
	will need to be changed. For example:

	<pre>
	// Before:
	public void doSaveAs() {
	IProgressMonitor monitor= getProgressMonitor();
	performSaveAs(monitor);
	}
	</pre>

	<pre>
	// After:
	public void doSaveAs() {
	IProgressMonitor monitor= getProgressMonitor();
	try {
	performSaveAs(monitor);
	} finally {
	monitor.done();
	}
	}
	</pre>

	<p>
	Fortunately there are few of these methods and they are easy to find.
	<p>
	<strong>Action required:</strong>
	<ul>
	<li>Open the Call Hierarchy on <code>StatusLineManager#getProgressMonitor()</code>.</li>
	<li>Ensure that all callers of these methods contain a finally block that
	invokes done (as in the doSaveAs() example, above).</li>
	<li>Open the Type Hierarchy of <code>IProgressMonitor</code>. Look for progress monitors which do something in
	their done() method besides reporting work, setting a task name, or calling done on another
	monitor. SubMonitor can be ignored. Monitors which set a control's visibility or deallocate a
	resource in their done() method must not be ignored.</li>
	<li>Use the Call Hierarchy view to locate every place that instantiates or accesses an instance of
	one of those classes. Ensure that those access points contain a try/finally block that invokes done().</li>
	</ul>

	<p><strong>More Information:</strong>
	<p>
	See <a href="https://eclipse.org/articles/Article-Progress-Monitors/article.html" target="_blank">this article</a> for
	more examples of how to use progress monitors with the new calling convention. Background and discussion
	about this change <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=487372" target="_blank">can be found here.</a>


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

	<h2>2. <a name="bidi-1.0.0">javax.xml removed from org.eclipse.e4.rcp feature</a></h2>
	<p><strong>What is affected:</strong> Clients that refer to
	the <code>javax.xml</code> bundle and use the <code>org.eclipse.e4.rcp</code> feature for that dependency.
	</p>
	<p><strong>Description:</strong>

	The <code>javax.xml</code> plug-in has been removed from the <code>org.eclipse.e4.rcp</code> feature.
	The <code>javax.xml</code> package is provided by JavaSE 1.7 and the Eclipse Platform requires Java 1.8.
	</p>
	If you have a dependency to this bundle and if you are using the
	org.eclipse.e4.rcp you need to adjust require-bundle: javax.xml to
	import-package in the corresponding MANIFEST.MF.

	</body>
	</html>