Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorStefan Xenos2015-09-15 22:30:55 +0000
committerStefan Xenos2015-10-13 15:20:56 +0000
commit91df8028994f2a13f609073217720268ce35e393 (patch)
tree9c1113ad5f9751cc549b6f5523433f10e0267acc /bundles/org.eclipse.equinox.common
parent62e50f08890d7a52a95f0a18bcb227baea8434d3 (diff)
downloadrt.equinox.bundles-91df8028994f2a13f609073217720268ce35e393.tar.gz
rt.equinox.bundles-91df8028994f2a13f609073217720268ce35e393.tar.xz
rt.equinox.bundles-91df8028994f2a13f609073217720268ce35e393.zip
Bug 477501 - Add JavaDoc to SubProgressMonitor explaining how to deal with the deprecation
Change-Id: Ic3c1d9835b6eaab44f7e94fc0bab2b8240bc4aba Signed-off-by: Stefan Xenos <sxenos@gmail.com>
Diffstat (limited to 'bundles/org.eclipse.equinox.common')
-rw-r--r--bundles/org.eclipse.equinox.common/src/org/eclipse/core/runtime/SubProgressMonitor.java60
1 files changed, 42 insertions, 18 deletions
diff --git a/bundles/org.eclipse.equinox.common/src/org/eclipse/core/runtime/SubProgressMonitor.java b/bundles/org.eclipse.equinox.common/src/org/eclipse/core/runtime/SubProgressMonitor.java
index 9fd52362..0be34139 100644
--- a/bundles/org.eclipse.equinox.common/src/org/eclipse/core/runtime/SubProgressMonitor.java
+++ b/bundles/org.eclipse.equinox.common/src/org/eclipse/core/runtime/SubProgressMonitor.java
@@ -11,27 +11,51 @@
package org.eclipse.core.runtime;
/**
- * For new implementations consider using {@link SubMonitor}.
- *
- * A progress monitor that uses a given amount of work ticks
- * from a parent monitor. It can be used as follows:
+ * A progress monitor that uses a given amount of work ticks from a parent monitor. Code that
+ * currently uses this utility should be rewritten to use {@link SubMonitor} instead.
+ * Consider the following example:
* <pre>
- * try {
- * pm.beginTask("Main Task", 100);
- * doSomeWork(pm, 30);
- * SubProgressMonitor subMonitor= new SubProgressMonitor(pm, 40);
- * try {
- * subMonitor.beginTask("", 300);
- * doSomeWork(subMonitor, 300);
- * } finally {
- * subMonitor.done();
- * }
- * doSomeWork(pm, 30);
- * } finally {
- * pm.done();
+ * void someMethod(IProgressMonitor pm) {
+ * pm.beginTask("Main Task", 100);
+ * SubProgressMonitor subMonitor1= new SubProgressMonitor(pm, 60);
+ * try {
+ * doSomeWork(subMonitor1);
+ * } finally {
+ * subMonitor1.done();
+ * }
+ * SubProgressMonitor subMonitor2= new SubProgressMonitor(pm, 40);
+ * try {
+ * doSomeMoreWork(subMonitor2);
+ * } finally {
+ * subMonitor2.done();
+ * }
* }
* </pre>
* <p>
+ * The above code should be refactored to this:
+ * <pre>
+ * void someMethod(IProgressMonitor pm) {
+ * SubMonitor subMonitor = SubMonitor.convert(pm, "Main Task", 100);
+ * doSomeWork(subMonitor.newChild(60));
+ * doSomeMoreWork(subMonitor.newChild(40));
+ * }
+ * </pre>
+ * <p>
+ * The process for converting code which used SubProgressMonitor into SubMonitor is:
+ * <ul>
+ * <li>Calls to {@link IProgressMonitor#beginTask} on the root monitor should be replaced by a call
+ * to {@link SubMonitor#convert}. Keep the returned SubMonitor around as a local variable and refer
+ * to it instead of the root monitor for the remainder of the method.</li>
+ * <li>All calls to {@link #SubProgressMonitor(IProgressMonitor, int)} should be replaced by calls to
+ * {@link SubMonitor#newChild(int)}.</li>
+ * <li>If a SubProgressMonitor is constructed using the SUPPRESS_SUBTASK_LABEL flag, replace it with the
+ * two-argument version of {@link SubMonitor#newChild(int, int)} using {@link SubMonitor#SUPPRESS_SUBTASK}
+ * as the second argument.</li>
+ * <li>It is not necessary to call done on an instance of {@link SubMonitor}.</li>
+ * </ul>
+ * <p>
+ * Please see the {@link SubMonitor} documentation for further examples.
+ * <p>
* This class can be used without OSGi running.
* </p><p>
* This class may be instantiated or subclassed by clients.
@@ -44,7 +68,7 @@ public class SubProgressMonitor extends ProgressMonitorWrapper {
/**
* Style constant indicating that calls to <code>subTask</code>
- * should not have any effect.
+ * should not have any effect. This is equivalent to {@link SubMonitor#SUPPRESS_SUBTASK}
*
* @see #SubProgressMonitor(IProgressMonitor,int,int)
*/

Back to the top