Add documentation for BackgroundTask (and improve code) (#11346)

* Add documentation for BackgroundTask (and improve code)

Co-authored-by: Carl Christian Snethlage <[email protected]>
Co-authored-by: Loay Ghreeb <[email protected]>

* Use <pre> tag for code example

* another useless wrap

---------

Co-authored-by: Carl Christian Snethlage <[email protected]>
Co-authored-by: Loay Ghreeb <[email protected]>
Co-authored-by: Loay Ghreeb <[email protected]>
Co-authored-by: Siedlerchr <[email protected]>

Author: 4 people

src/main/java/org/jabref/gui/util/BackgroundTask.java

@@ -30,7 +30,21 @@
  * We cannot use {@link Task} directly since it runs certain update notifications on the JavaFX thread,
  * and so makes testing harder.
  * We take the opportunity and implement a fluid interface.
- *
+ * <p>
+ * A task created here is to be submitted to {@link org.jabref.gui.Globals#TASK_EXECUTOR}: Use {@link TaskExecutor#execute(BackgroundTask)} to submit.
+ * <p>
+ * Example (for using the fluent interface)
+ * <pre>{@code
+ * BackgroundTask
+ *     .wrap(() -> ...)
+ *     .showToUser(true)
+ *     .onRunning(() -> ...)
+ *     .onSuccess(() -> ...)
+ *     .onFailure(() -> ...)
+ *     .executeWith(taskExecutor);
+ * }</pre>
+ * Background: The task executor one takes care to show it in the UI. See {@link org.jabref.gui.StateManager#addBackgroundTask(BackgroundTask, Task)} for details.
+ * <p>
  * TODO: Think of migrating to <a href="https://github.com/ReactiveX/RxJava#simple-background-computation">RxJava</a>;
  *       <a href="https://www.baeldung.com/java-completablefuture">CompletableFuture</a> do not seem to support everything.
  *       If this is not possible, add an @implNote why.
@@ -136,8 +150,9 @@ public boolean showToUser() {
         return showToUser.get();
     }
 
-    public void showToUser(boolean show) {
+    public BackgroundTask<V> showToUser(boolean show) {
         showToUser.set(show);
+        return this;
     }
 
     public boolean willBeRecoveredAutomatically() {

src/main/java/org/jabref/gui/util/DefaultTaskExecutor.java

@@ -41,9 +41,6 @@ public DefaultTaskExecutor(StateManager stateManager) {
         this.stateManager = stateManager;
     }
 
-    /**
-     *
-     */
     public static <V> V runInJavaFXThread(Callable<V> callable) {
         if (Platform.isFxApplicationThread()) {
             try {
@@ -140,6 +137,13 @@ public DelayTaskThrottler createThrottler(int delay) {
         return throttler;
     }
 
+    /**
+     * Generates a wrapper JavaFX {@link Task} monitoring the progress based on the data given from the task.
+     * <code>call</code> is routed to the given task object.
+     *
+     * @param task the BackgroundTask to wrap
+     * @return a new Task object
+     */
     private <V> Task<V> getJavaFXTask(BackgroundTask<V> task) {
         Task<V> javaTask = new Task<>() {
             {

src/main/java/org/jabref/logic/pdf/search/IndexingTaskManager.java

@@ -32,10 +32,9 @@ public IndexingTaskManager(TaskExecutor taskExecutor) {
         this.taskExecutor = taskExecutor;
         showToUser(true);
         willBeRecoveredAutomatically(true);
-        DefaultTaskExecutor.runInJavaFXThread(() -> {
-            this.updateProgress(1, 1);
-            this.titleProperty().set(Localization.lang("Indexing pdf files"));
-        });
+        // runs on fx thread, no need to wrap
+        this.updateProgress(1, 1);
+        this.titleProperty().set(Localization.lang("Indexing pdf files"));
     }
 
     @Override
@@ -56,10 +55,8 @@ protected Void call() throws Exception {
     }
 
     private void updateProgress() {
-        DefaultTaskExecutor.runInJavaFXThread(() -> {
-            updateMessage(Localization.lang("%0 of %1 linked files added to the index", numOfIndexedFiles, numOfIndexedFiles + taskQueue.size()));
-            updateProgress(numOfIndexedFiles, numOfIndexedFiles + taskQueue.size());
-        });
+        updateMessage(Localization.lang("%0 of %1 linked files added to the index", numOfIndexedFiles, numOfIndexedFiles + taskQueue.size()));
+        updateProgress(numOfIndexedFiles, numOfIndexedFiles + taskQueue.size());
     }
 
     private void enqueueTask(Runnable indexingTask) {