mirror of
https://gitflic.ru/project/openide/openide.git
synced 2026-09-27 10:03:11 +07:00
IJPL-384 IJPL-773 clarify obsolete progress-indicator-based APIs
GitOrigin-RevId: 0fac85862339c8612b12d2c5827683c0f9950c2c
This commit is contained in:
Daniil Ovchinnikov
committed by
intellij-monorepo-bot
intellij-monorepo-bot
parent
9665e1707a
commit
be49f04479
@@ -10,6 +10,53 @@ import static com.intellij.openapi.util.NlsContexts.ProgressDetails;
|
||||
import static com.intellij.openapi.util.NlsContexts.ProgressText;
|
||||
|
||||
/**
|
||||
* <h3>Obsolescence notice</h3>
|
||||
* <p>
|
||||
* This interface and its implementation are effectively obsolete.
|
||||
* More info <a href="https://youtrack.jetbrains.com/issue/IJPL-10">in the issue and linked issues</a> and
|
||||
* <a href="https://youtrack.jetbrains.com/articles/IJPL-A-6/Execution-Contexts">in the Knowledge Base</a>.
|
||||
* It's not marked with {@link ApiStatus.Obsolete} at the moment to avoid excessive highlighting everywhere.
|
||||
* <ul>
|
||||
* <li>
|
||||
* For cancellation use coroutines and their cancellation capabilities.
|
||||
* See <a href="https://youtrack.jetbrains.com/articles/IJPL-A-10">how to start a coroutine</a>.
|
||||
* </li>
|
||||
* <li>
|
||||
* To switch to the blocking context and back to coroutine use:
|
||||
* <ul>
|
||||
* <li>{@link CoroutinesKt#blockingContext}</li>
|
||||
* <li>{@link CoroutinesKt#coroutineToIndicator}</li>
|
||||
* <li>{@link CoroutinesKt#blockingContextToIndicator}</li>
|
||||
* <li>{@link CoroutinesKt#runBlockingCancellable}</li>
|
||||
* </ul>
|
||||
* </li>
|
||||
* <li>
|
||||
* To show a modal or status-bar progress in the UI use:
|
||||
* <ul>
|
||||
* <li>{@link com.intellij.platform.ide.progress.TasksKt#withBackgroundProgress}</li>
|
||||
* <li>{@link com.intellij.platform.ide.progress.TasksKt#withModalProgress}</li>
|
||||
* <li>{@link com.intellij.platform.ide.progress.TasksKt#runWithModalProgressBlocking}</li>
|
||||
* </ul>
|
||||
* </li>
|
||||
* <li>
|
||||
* To report progress use:
|
||||
* <ul>
|
||||
* <li>{@link com.intellij.platform.util.progress.StepsKt#reportSequentialProgress}</li>
|
||||
* <li>{@link com.intellij.platform.util.progress.StepsKt#reportProgress}</li>
|
||||
* <li>{@link com.intellij.platform.util.progress.StepsKt#reportRawProgress}</li>
|
||||
* </ul>
|
||||
* </li>
|
||||
* <li>
|
||||
* To collect progress reported elsewhere, for example, to relay updates to custom UI, use:
|
||||
* <ul>
|
||||
* <li>{@link com.intellij.platform.util.progress.ProgressPipeKt#createProgressPipe},</li>
|
||||
* <li>{@link com.intellij.platform.util.progress.ProgressPipe#collectProgressUpdates},</li>
|
||||
* <li>and {@link com.intellij.platform.util.progress.ProgressPipe#progressUpdates}</li>
|
||||
* </ul>
|
||||
* </li>
|
||||
* </ul>
|
||||
* </p>
|
||||
*
|
||||
* <p>An object accompanying a computation, usually in a background thread. It allows displaying process status to the user
|
||||
* ({@link #setText}, {@link #setText2}, {@link #setFraction}, {@link #setIndeterminate}) and
|
||||
* interrupt if the computation is canceled ({@link #checkCanceled()}).</p>
|
||||
|
||||
@@ -11,7 +11,12 @@ import com.intellij.openapi.util.NlsContexts.ProgressText;
|
||||
import com.intellij.openapi.util.NlsContexts.ProgressTitle;
|
||||
import com.intellij.openapi.util.Ref;
|
||||
import com.intellij.openapi.util.ThrowableComputable;
|
||||
import com.intellij.platform.util.progress.StepsKt;
|
||||
import com.intellij.util.concurrency.annotations.RequiresBlockingContext;
|
||||
import kotlin.coroutines.Continuation;
|
||||
import kotlin.jvm.functions.Function0;
|
||||
import kotlin.jvm.functions.Function1;
|
||||
import kotlin.jvm.functions.Function2;
|
||||
import org.jetbrains.annotations.ApiStatus;
|
||||
import org.jetbrains.annotations.ApiStatus.Obsolete;
|
||||
import org.jetbrains.annotations.NotNull;
|
||||
@@ -48,19 +53,38 @@ public abstract class ProgressManager extends ProgressIndicatorProvider {
|
||||
public abstract boolean hasUnsafeProgressIndicator();
|
||||
|
||||
/**
|
||||
* <h3>Obsolescence notice</h3>
|
||||
* <p>
|
||||
* See {@link ProgressIndicator} notice.
|
||||
* <ul>
|
||||
* <li>
|
||||
* If only {@link ProgressManager#checkCanceled} is supposed to work inside {@code process},
|
||||
* use {@link CoroutinesKt#blockingContext} in a coroutine.
|
||||
* </li>
|
||||
* <li>
|
||||
* If {@link ProgressManager#getProgressIndicator} is expected to return a non-null value,
|
||||
* use {@link CoroutinesKt#coroutineToIndicator} in a coroutine.
|
||||
* </li>
|
||||
* </ul>
|
||||
* </p>
|
||||
*
|
||||
* Runs the given process synchronously in calling thread, associating this thread with the specified progress indicator.
|
||||
* This means that it'll be returned by {@link ProgressManager#getProgressIndicator()} inside the {@code process},
|
||||
* and {@link ProgressManager#checkCanceled()} will throw a {@link ProcessCanceledException} if the progress indicator is canceled.
|
||||
*
|
||||
* @param progress an indicator to use, {@code null} means reuse current progress.
|
||||
* The progress is {@link ProgressIndicator#start started} before running {@code process} and {@link ProgressIndicator#stop() stopped} afterward.
|
||||
*
|
||||
* @see CoroutinesKt#coroutineToIndicator
|
||||
*/
|
||||
@Obsolete
|
||||
public abstract void runProcess(@NotNull Runnable process, @Nullable ProgressIndicator progress) throws ProcessCanceledException;
|
||||
|
||||
/**
|
||||
* <h3>Obsolescence notice</h3>
|
||||
* <p>
|
||||
* See {@link ProgressIndicator} notice.
|
||||
* See {@link #runProcess(Runnable, ProgressIndicator)} notice.
|
||||
* </p>
|
||||
*
|
||||
* Performs the given computation synchronously in calling thread and returns its result, associating this thread with the specified progress indicator.
|
||||
* This means that it'll be returned by {@link ProgressManager#getProgressIndicator()} inside the {@code process},
|
||||
* and {@link ProgressManager#checkCanceled()} will throw a {@link ProcessCanceledException} if the progress indicator is canceled.
|
||||
@@ -77,6 +101,27 @@ public abstract class ProgressManager extends ProgressIndicatorProvider {
|
||||
return ref.get();
|
||||
}
|
||||
|
||||
/**
|
||||
* <h3>Obsolescence notice</h3>
|
||||
* <p>
|
||||
* See {@link ProgressIndicator} notice.
|
||||
* <ul>
|
||||
* <li>
|
||||
* If the returned indicator is used only for {@link ProgressIndicator#checkCanceled()},
|
||||
* use {@link ProgressManager#checkCanceled()} directly.
|
||||
* </li>
|
||||
* <li>
|
||||
* If the returned indicator is used to report progress, use coroutines and their progress reporting capabilities:
|
||||
* {@link StepsKt#reportProgress}, {@link StepsKt#reportSequentialProgress}, {@link StepsKt#reportRawProgress}.
|
||||
* </li>
|
||||
* <li>
|
||||
* If the returned indicator is used to create an indicator wrapper,
|
||||
* which is {@link ProgressManager#runProcess(Runnable, ProgressIndicator) installed} in another thread,
|
||||
* migrate to coroutines, and use one of approaches described in {@link ProgressManager#runProcess(Runnable, ProgressIndicator)}.
|
||||
* </li>
|
||||
* </ul>
|
||||
* </p>
|
||||
*/
|
||||
@Obsolete
|
||||
@Override
|
||||
public abstract ProgressIndicator getProgressIndicator();
|
||||
@@ -120,6 +165,16 @@ public abstract class ProgressManager extends ProgressIndicatorProvider {
|
||||
public abstract <T, E extends Exception> T computeInNonCancelableSection(@NotNull ThrowableComputable<T, E> computable) throws E;
|
||||
|
||||
/**
|
||||
* <h3>Obsolescence notice</h3>
|
||||
* <p>
|
||||
* See {@link ProgressIndicator} notice.
|
||||
* <ul>
|
||||
* <li>Consider getting rid of a modal progress altogether, for example, by using a background progress,</li>
|
||||
* <li>or use {@link com.intellij.platform.ide.progress.TasksKt#runWithModalProgressBlocking}</li>
|
||||
* <li>or {@link com.intellij.platform.ide.progress.TasksKt#withModalProgress}.</li>
|
||||
* </ul>
|
||||
*
|
||||
* </p>
|
||||
* Runs the specified operation in a background thread and shows a modal progress dialog in the
|
||||
* main thread while the operation is executing.
|
||||
* If a dialog can't be shown (e.g. under write action or in headless environment),
|
||||
@@ -138,6 +193,11 @@ public abstract class ProgressManager extends ProgressIndicatorProvider {
|
||||
@Nullable Project project);
|
||||
|
||||
/**
|
||||
* <h3>Obsolescence notice</h3>
|
||||
* <p>
|
||||
* See {@link ProgressIndicator} notice.
|
||||
* See {@link #runProcessWithProgressSynchronously(Runnable, String, boolean, Project)} notice.
|
||||
* <p/>
|
||||
* Runs the specified operation in a background thread and shows a modal progress dialog in the
|
||||
* main thread while the operation is executing.
|
||||
* If a dialog can't be shown (e.g. under write action or in headless environment),
|
||||
@@ -157,6 +217,12 @@ public abstract class ProgressManager extends ProgressIndicatorProvider {
|
||||
@Nullable Project project) throws E;
|
||||
|
||||
/**
|
||||
* <h3>Obsolescence notice</h3>
|
||||
* <p>
|
||||
* See {@link ProgressIndicator} notice.
|
||||
* See {@link #runProcessWithProgressSynchronously(Runnable, String, boolean, Project)} notice.
|
||||
* <p/>
|
||||
*
|
||||
* Runs the specified operation in a background thread and shows a modal progress dialog in the
|
||||
* main thread while the operation is executing.
|
||||
* If a dialog can't be shown (e.g. under write action or in headless environment),
|
||||
@@ -200,6 +266,16 @@ public abstract class ProgressManager extends ProgressIndicatorProvider {
|
||||
@NotNull PerformInBackgroundOption option);
|
||||
|
||||
/**
|
||||
* <h3>Obsolescence notice</h3>
|
||||
* <p>
|
||||
* See {@link ProgressIndicator} notice.
|
||||
* <br/>
|
||||
* Do not use directly!
|
||||
* Use {@link Task#queue()} instead of this method, or migrate the Task to coroutines.
|
||||
* Please find appropriate replacements in the respective Task documentation:
|
||||
* {@link Task.Backgroundable}, {@link Task.Modal}, {@link Task.WithResult}, {@link Task.ConditionalModal}.
|
||||
* <p/>
|
||||
*
|
||||
* Runs a specified {@code task} in either background/foreground thread and shows a progress dialog.
|
||||
*
|
||||
* @param task task to run (either {@link Task.Modal} or {@link Task.Backgroundable}).
|
||||
@@ -213,6 +289,12 @@ public abstract class ProgressManager extends ProgressIndicatorProvider {
|
||||
public abstract void run(@NotNull Task task);
|
||||
|
||||
/**
|
||||
* <h3>Obsolescence notice</h3>
|
||||
* <p>
|
||||
* See {@link ProgressIndicator} notice.
|
||||
* See {@link Task.WithResult} notice.
|
||||
* <p/>
|
||||
*
|
||||
* Runs a specified computation with a modal progress dialog.
|
||||
*/
|
||||
@Obsolete
|
||||
@@ -222,6 +304,13 @@ public abstract class ProgressManager extends ProgressIndicatorProvider {
|
||||
return task.getResult();
|
||||
}
|
||||
|
||||
/**
|
||||
* <h3>Obsolescence notice</h3>
|
||||
* <p>
|
||||
* See {@link ProgressIndicator} notice.
|
||||
* See {@link ProgressManager#run(Task)} notice.
|
||||
* </p>
|
||||
*/
|
||||
@Obsolete
|
||||
public abstract void runProcessWithProgressAsynchronously(@NotNull Task.Backgroundable task, @NotNull ProgressIndicator progressIndicator);
|
||||
|
||||
@@ -245,6 +334,12 @@ public abstract class ProgressManager extends ProgressIndicatorProvider {
|
||||
}
|
||||
|
||||
/**
|
||||
* <h3>Obsolescence notice</h3>
|
||||
* <p>
|
||||
* See {@link ProgressIndicator} notice.
|
||||
* See {@link #runProcess(Runnable, ProgressIndicator)} notice.
|
||||
* </p>
|
||||
*
|
||||
* @param progress an indicator to use, {@code null} means reuse current progress
|
||||
* The methods {@link ProgressIndicator#start()} or {@link ProgressIndicator#stop()} are not called because it's assumed the {@code progress} is already running.
|
||||
*/
|
||||
@@ -264,6 +359,12 @@ public abstract class ProgressManager extends ProgressIndicatorProvider {
|
||||
}
|
||||
|
||||
/**
|
||||
* <h3>Obsolescence notice</h3>
|
||||
* <p>
|
||||
* See {@link ProgressIndicator} notice.
|
||||
* Use {@link com.intellij.openapi.application.ReadAction#computeCancellable} instead.
|
||||
* </p>
|
||||
*
|
||||
* This method attempts to run provided action synchronously in a read action, so that, if possible, it wouldn't impact any pending,
|
||||
* executing or future write actions (for this to work effectively the action should invoke {@link ProgressManager#checkCanceled()} or
|
||||
* {@link ProgressIndicator#checkCanceled()} often enough).
|
||||
|
||||
@@ -15,6 +15,8 @@ import com.intellij.openapi.util.text.StringUtil;
|
||||
import com.intellij.util.ExceptionUtil;
|
||||
import com.intellij.util.ObjectUtils;
|
||||
import com.intellij.util.concurrency.annotations.RequiresBlockingContext;
|
||||
import kotlin.coroutines.Continuation;
|
||||
import kotlin.jvm.functions.Function2;
|
||||
import org.jetbrains.annotations.ApiStatus;
|
||||
import org.jetbrains.annotations.ApiStatus.Obsolete;
|
||||
import org.jetbrains.annotations.NotNull;
|
||||
@@ -24,6 +26,7 @@ import javax.swing.*;
|
||||
|
||||
/**
|
||||
* <h3>Obsolescence notice</h3>
|
||||
* See {@link ProgressIndicator} notice.
|
||||
* Use one of the following functions to run tasks:
|
||||
* <ul>
|
||||
* <li>{@link com.intellij.platform.ide.progress.TasksKt#withBackgroundProgress}</li>
|
||||
@@ -203,7 +206,11 @@ public abstract class Task implements TaskInfo, Progressive {
|
||||
}
|
||||
|
||||
/**
|
||||
* @see com.intellij.openapi.progress.TasksKt#withBackgroundProgress
|
||||
* <h3>Obsolescence notice</h3>
|
||||
* <p>
|
||||
* See {@link ProgressIndicator} notice.
|
||||
* Use {@link com.intellij.platform.ide.progress.TasksKt#withBackgroundProgress}.
|
||||
* <p/>
|
||||
*/
|
||||
@Obsolete
|
||||
public abstract static class Backgroundable extends Task implements PerformInBackgroundOption {
|
||||
@@ -257,8 +264,14 @@ public abstract class Task implements TaskInfo, Progressive {
|
||||
}
|
||||
|
||||
/**
|
||||
* @see com.intellij.openapi.progress.TasksKt#withModalProgress
|
||||
* @see com.intellij.openapi.progress.TasksKt#runWithModalProgressBlocking
|
||||
* <h3>Obsolescence notice</h3>
|
||||
* <p>
|
||||
* See {@link ProgressIndicator} notice.
|
||||
* <ul>
|
||||
* <li>Use {@link com.intellij.platform.ide.progress.TasksKt#withModalProgress},</li>
|
||||
* <li>or {@link com.intellij.platform.ide.progress.TasksKt#runWithModalProgressBlocking}.</li>
|
||||
* </ul>
|
||||
* <p/>
|
||||
*/
|
||||
@Obsolete
|
||||
public abstract static class Modal extends Task {
|
||||
@@ -278,9 +291,15 @@ public abstract class Task implements TaskInfo, Progressive {
|
||||
}
|
||||
|
||||
/**
|
||||
* @see com.intellij.openapi.progress.TasksKt#withBackgroundProgress
|
||||
* @see com.intellij.openapi.progress.TasksKt#withModalProgress
|
||||
* @see com.intellij.openapi.progress.TasksKt#runWithModalProgressBlocking
|
||||
* <h3>Obsolescence notice</h3>
|
||||
* <p>
|
||||
* See {@link ProgressIndicator} notice.
|
||||
* <ul>
|
||||
* <li>Use {@link com.intellij.platform.ide.progress.TasksKt#withBackgroundProgress},</li>
|
||||
* <li>{@link com.intellij.platform.ide.progress.TasksKt#withModalProgress},</li>
|
||||
* <li>or {@link com.intellij.platform.ide.progress.TasksKt#runWithModalProgressBlocking}.</li>
|
||||
* </ul>
|
||||
* <p/>
|
||||
*/
|
||||
@Obsolete
|
||||
public abstract static class ConditionalModal extends Backgroundable {
|
||||
@@ -345,7 +364,14 @@ public abstract class Task implements TaskInfo, Progressive {
|
||||
}
|
||||
|
||||
/**
|
||||
* @see com.intellij.openapi.progress.TasksKt#runWithModalProgressBlocking
|
||||
* <h3>Obsolescence notice</h3>
|
||||
* <p>
|
||||
* See {@link ProgressIndicator} notice.
|
||||
* <ul>
|
||||
* <li>Use {@link com.intellij.platform.ide.progress.TasksKt#runWithModalProgressBlocking},</li>
|
||||
* <li>or {@link com.intellij.platform.ide.progress.TasksKt#withModalProgress}.</li>
|
||||
* </ul>
|
||||
* <p/>
|
||||
*/
|
||||
@Obsolete
|
||||
public abstract static class WithResult<T, E extends Exception> extends Task.Modal {
|
||||
|
||||
Reference in New Issue
Block a user