Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorStefan Xenos2016-06-08 18:43:23 +0000
committerStefan Xenos2016-06-13 18:35:05 +0000
commit182a723b0c41ce847efe570fd29fb831a4ab542e (patch)
treec9f84b3355168501798be993e8961601e139119c /bundles/org.eclipse.equinox.common
parenteed5c82c9713528979c3a5a781e0e887add5a573 (diff)
downloadrt.equinox.bundles-182a723b0c41ce847efe570fd29fb831a4ab542e.tar.gz
rt.equinox.bundles-182a723b0c41ce847efe570fd29fb831a4ab542e.tar.xz
rt.equinox.bundles-182a723b0c41ce847efe570fd29fb831a4ab542e.zip
Bug 495737 - Update the JavaDoc on SubMonitor and IProgressMonitor to
reflect the 4.7 calling conventions. Change-Id: If7a5a3d5bfa8de4bcb625b0face6172d01bacdf2 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/IProgressMonitor.java31
-rw-r--r--bundles/org.eclipse.equinox.common/src/org/eclipse/core/runtime/SubMonitor.java54
2 files changed, 30 insertions, 55 deletions
diff --git a/bundles/org.eclipse.equinox.common/src/org/eclipse/core/runtime/IProgressMonitor.java b/bundles/org.eclipse.equinox.common/src/org/eclipse/core/runtime/IProgressMonitor.java
index 12a9dd62..bc601b23 100644
--- a/bundles/org.eclipse.equinox.common/src/org/eclipse/core/runtime/IProgressMonitor.java
+++ b/bundles/org.eclipse.equinox.common/src/org/eclipse/core/runtime/IProgressMonitor.java
@@ -38,7 +38,36 @@ package org.eclipse.core.runtime;
* involve blocking operations, or operations which might throw uncaught exceptions,
* the notifications should be queued, and the actual processing deferred (or perhaps
* delegated to a separate thread).
- * </p><p>
+ * </p>
+ * <p><b>CALLER/CALLEE RESPONSIBILITIES:</b></p>
+ * <p>
+ * Methods that receive an {@link IProgressMonitor} must either obey the following
+ * conventions or include JavaDoc explaining how it differs from these rules.
+ * The called method:
+ * <ul>
+ * <li>Will call {@link #beginTask} on the argument 0 or 1 times, at its option.</li>
+ * <li>Will not promise to invoke {@link #done()} on the monitor.</li>
+ * <li>Will not call {@link #setCanceled} on the monitor.</li>
+ * <li>May rely on the monitor not being null.</li>
+ * <li>May rely on the monitor ignoring the string passed to {@link #beginTask}.</li>
+ * </ul>
+ * <p>
+ * The caller:
+ * <ul>
+ * <li>Will either pass in a fresh instance of {@link IProgressMonitor} that has
+ * not had {@link #beginTask} invoked on it yet, or will select an
+ * implementation of {@link IProgressMonitor} that explicitly permits multiple calls
+ * to {@link #beginTask}.</li>
+ * <li>Will not rely on the callee to invoke {@link #done()} on the monitor.
+ * It must either select an implementation of {@link IProgressMonitor} that
+ * does not require {@link #done()} to be called, for example {@link SubMonitor},
+ * or it must invoke {@link #done()} itself after the method returns.</li>
+ * <li>Will not pass in a null monitor unless the JavaDoc of the callee says that it
+ * accepts null.</li>
+ * <li>Will pass in a monitor that ignores the name argument to {@link #beginTask}
+ * unless the JavaDoc for the callee states otherwise.
+ * </ul>
+ *
* This interface can be used without OSGi running.
* </p><p>
* Clients may implement this interface.
diff --git a/bundles/org.eclipse.equinox.common/src/org/eclipse/core/runtime/SubMonitor.java b/bundles/org.eclipse.equinox.common/src/org/eclipse/core/runtime/SubMonitor.java
index 47500fd6..02bb70da 100644
--- a/bundles/org.eclipse.equinox.common/src/org/eclipse/core/runtime/SubMonitor.java
+++ b/bundles/org.eclipse.equinox.common/src/org/eclipse/core/runtime/SubMonitor.java
@@ -45,31 +45,7 @@ import org.eclipse.core.internal.runtime.TracingOptions;
* <li>Use <code>SubMonitor.split(...)</code> whenever you need to call another method that
* accepts an IProgressMonitor.</li>
* </ul>
- * <p></p>
- * <p><b>DEFAULT BEHAVIOR:</b></p>
*
- * <p>When writing JavaDoc for a method that accepts an IProgressMonitor, you should assume the
- * following default behavior unless the method's JavaDoc says otherwise:</p>
- * <ul>
- * <li>It WILL call beginTask on the IProgressMonitor.</li>
- * <li>It WILL NOT accept a null argument.</li>
- * <li>It WILL call done on the IProgressMonitor.</li>
- * </ul>
- * <p></p>
- * <p><b>BEST PRACTISES:</b></p>
- *
- * <p>We recommend that newly-written methods follow the given contract:</p>
- * <ul>
- * <li>It WILL call beginTask on the IProgressMonitor.</li>
- * <li>It WILL accept a null argument, indicating that no progress should be reported and the operation cannot be cancelled.</li>
- * <li>It WILL NOT call done on the IProgressMonitor, leaving this responsibility up to the caller.</li>
- * </ul>
- * <p>If you wish to follow these conventions, you may copy and paste the following text into your method's JavaDoc:</p>
- *
- * <pre>@param monitor the progress monitor to use for reporting progress to the user. It is the caller's responsibility
- * to call done() on the given monitor. Accepts <code>null</code>, indicating that no progress should be
- * reported and that the operation cannot be cancelled.</pre>
- *
* <p></p>
* <p><b>Example: Recommended usage</b></p>
*
@@ -99,36 +75,6 @@ import org.eclipse.core.internal.runtime.TracingOptions;
* doSomeWork(progress.split(40));
* }
* </pre>
- *
- *
- * <p></p>
- * <p><b>Example: Default usage</b></p>
- *
- * <p>You will often need to implement a method that does not explicitly stipulate that calling done() is the responsibility
- * of the caller. In this case, you should use the following pattern:</p>
- *
- * <pre>
- * // param monitor the progress monitor to use for reporting progress to the user, or <code>null</code> indicating
- * // that no progress should be reported and the operation cannot be cancelled.
- * //
- * void doSomething(IProgressMonitor monitor) {
- * // Convert the given monitor into a progress instance
- * SubMonitor progress = SubMonitor.convert(monitor, 100);
- * try {
- * // Use 30% of the progress to do some work
- * doSomeWork(progress.split(30));
- *
- * // Advance the monitor by another 30%
- * progress.worked(30);
- *
- * // Use the remaining 40% of the progress to do some more work
- * doSomeWork(progress.split(40));
- *
- * } finally {
- * SubMonitor.done(monitor);
- * }
- * }
- * </pre>
*
* <p></p>
* <p><b>Example: Branches</b></p>

Back to the top