src/javajs/async/AsyncSwingWorker.java

   1 package javajs.async;
   2
   3 import java.awt.Component;
   4
   5 import javax.swing.ProgressMonitor;
   6 import javax.swing.SwingUtilities;
   7 import javax.swing.SwingWorker;
   8
   9 import javajs.async.SwingJSUtils.StateHelper;
  10 import javajs.async.SwingJSUtils.StateMachine;
  11
  12 /**
  13  * v. 2020.06.03
  14  *
  15  * Executes synchronous or asynchronous tasks using a SwingWorker in Java or
  16  * JavaScript, equivalently.
  17  *
  18  * Unlike a standard SwingWorker, AsyncSwingWorker may itself be asynchronous.
  19  * For example, it might load a file asynchronously, or carry out a background
  20  * process in JavaScript much like one might be done in Java, but with only a
  21  * single thread.
  22  *
  23  * Whereas a standard SwingWorker would execute done() long before the
  24  * asynchronous task completed, this class will wait until progress has been
  25  * asynchronously set greater or equal to its max value or the task is canceled
  26  * before executing that method.
  27  *
  28  * Three methods must be supplied by the subclass:
  29  *
  30  * void initAsync()
  31  *
  32  * int doInBackgroundAsync(int progress)
  33  *
  34  * void doneAsync()
  35  *
  36  * Both initAsync() and doneAsync() are technically optional - they may be
  37  * empty. doInBackgroundAsync(), however, is the key method where, like
  38  * SwingWorker's doInBackground, the main work is done. The supplied progress
  39  * parameter reminds the subclass of where it is at, and the return value allows
  40  * the subclass to update the progress field in both the SwingWorker and the
  41  * ProgressMonitor.
  42  *
  43  * If it is desired to run the AsyncSwingWorker synchronously, call the
  44  * executeSynchronously() method rather than execute(). Never call
  45  * SwingWorker.run().
  46  *
  47  * Note that doInBackgroundAsync runs on the Java AWT event queue. This means
  48  * that, unlike a true SwingWorker, it will run in event-queue sequence, after
  49  * anything that that method itself adds to the queue. This is what SwingWorker itself
  50  * does with its done() signal.
  51  *
  52  * If doInBackgroundAsync has tasks that are time intensive, the thing to do is to
  53  *
  54  * (a) pause this worker by setting the value of progress for the NEXT step:
  55  *
  56  *    setProgressAsync(n);
  57  *
  58  * (b) pause the timer so that when doInBackgroundAsync returns, the timer is not fired:
  59  *
  60  *    setPaused(true);
  61  *
  62  * (c) start your process as new Thread, which bypasses the AWT EventQueue:
  63  *
  64  *    new Thread(Runnable).start();
  65  *
  66  * (d) have your thread, when it is done, return control to this worker:
  67  *
  68  *    setPaused(false);
  69  *
  70  * This final call restarts the worker with the currently specified progress value.
  71  *
  72  * @author hansonr
  73  *
  74  */
  75 public abstract class AsyncSwingWorker extends SwingWorker<Void, Void> implements StateMachine {
  76
  77
  78         // PropertyChangeEvent getPropertyName()
  79
  80         private static final String PROPERTY_STATE = "state";
  81         private static final String PROPERTY_PAUSE = "pause";
  82
  83         // PropertyChangeEvent getNewValue()
  84
  85         public static final String STARTED_ASYNC = "STARTED_ASYNC";
  86         public static final String STARTED_SYNC = "STARTED_SYNC";
  87
  88         public static final String DONE_ASYNC = "DONE_ASYNC";
  89         public static final String CANCELED_ASYNC = "CANCELED_ASYNC";
  90
  91         public static final String PAUSED = "PAUSED";
  92         public static final String RESUMED = "RESUMED";
  93
  94         protected int progressAsync;
  95
  96         /**
  97          * Override to provide initial tasks.
  98          */
  99         abstract public void initAsync();
 100
 101         /**
 102          * Given the last progress, do some portion of the task that the SwingWorker
 103          * would do in the background, and return the new progress. returning max or
 104          * above will complete the task.
 105          *
 106          * @param progress
 107          * @return new progress
 108          */
 109         abstract public int doInBackgroundAsync(int progress);
 110
 111         /**
 112          * Do something when the task is finished or canceled.
 113          *
 114          */
 115         abstract public void doneAsync();
 116
 117         protected ProgressMonitor progressMonitor;
 118
 119         protected int delayMillis;
 120         protected String note;
 121         protected int min;
 122         protected int max;
 123         protected int progressPercent;
 124
 125         protected boolean isAsync;
 126         private Exception exception;
 127
 128         /**
 129          * Construct an asynchronous SwingWorker task that optionally will display a
 130          * ProgressMonitor. Progress also can be monitored by adding a
 131          * PropertyChangeListener to the AsyncSwingWorker and looking for the "progress"
 132          * event, just the same as for a standard SwingWorker.
 133          *
 134          * @param owner       optional owner for the ProgressMonitor, typically a JFrame
 135          *                    or JDialog.
 136          *
 137          * @param title       A non-null title indicates we want to use a
 138          *                    ProgressMonitor with that title line.
 139          *
 140          * @param delayMillis A positive number indicating the delay we want before
 141          *                    executions, during which progress will be reported.
 142          *
 143          * @param min         The first progress value. No range limit.
 144          *
 145          * @param max         The last progress value. No range limit; may be greater
 146          *                    than min.
 147          *
 148          */
 149         public AsyncSwingWorker(Component owner, String title, int delayMillis, int min, int max) {
 150                 if (title != null && delayMillis > 0) {
 151                         progressMonitor = new ProgressMonitor(owner, title, "", Math.min(min, max), Math.max(min, max));
 152                         progressMonitor.setProgress(Math.min(min, max)); // displays monitor
 153                 }
 154                 this.delayMillis = Math.max(0, delayMillis);
 155                 this.isAsync = (delayMillis > 0);
 156
 157                 this.min = min;
 158                 this.max = max;
 159         }
 160
 161         public void executeAsync() {
 162                 firePropertyChange(PROPERTY_STATE, null, STARTED_ASYNC);
 163                 super.execute();
 164         }
 165
 166         public void executeSynchronously() {
 167                 firePropertyChange(PROPERTY_STATE, null, STARTED_SYNC);
 168                 isAsync = false;
 169                 delayMillis = 0;
 170                 try {
 171                         doInBackground();
 172                 } catch (Exception e) {
 173                         exception = e;
 174                         e.printStackTrace();
 175                         cancelAsync();
 176                 }
 177         }
 178
 179         public Exception getException() {
 180                 return exception;
 181         }
 182
 183         public int getMinimum() {
 184                 return min;
 185         }
 186
 187         public void setMinimum(int min) {
 188                 this.min = min;
 189                 if (progressMonitor != null) {
 190                         progressMonitor.setMinimum(min);
 191                 }
 192         }
 193
 194         public int getMaximum() {
 195                 return max;
 196         }
 197
 198         public void setMaximum(int max) {
 199                 if (progressMonitor != null) {
 200                         progressMonitor.setMaximum(max);
 201                 }
 202                 this.max = max;
 203         }
 204
 205         public int getProgressPercent() {
 206                 return progressPercent;
 207         }
 208
 209         public void setNote(String note) {
 210                 this.note = note;
 211                 if (progressMonitor != null) {
 212                         progressMonitor.setNote(note);
 213                 }
 214         }
 215
 216         /**
 217          * Cancel the asynchronous process.
 218          *
 219          */
 220         public void cancelAsync() {
 221                 helper.interrupt();
 222         }
 223
 224         /**
 225          * Check to see if the asynchronous process has been canceled.
 226          *
 227          * @return true if StateHelper is not alive anymore
 228          *
 229          */
 230         public boolean isCanceledAsync() {
 231                 return !helper.isAlive();
 232         }
 233
 234         /**
 235          * Check to see if the asynchronous process is completely done.
 236          *
 237          * @return true only if the StateMachine is at STATE_DONE
 238          *
 239          */
 240         public boolean isDoneAsync() {
 241                 return helper.getState() == STATE_DONE;
 242         }
 243
 244         /**
 245          * Override to set a more informed note for the ProcessMonitor.
 246          *
 247          * @param progress
 248          * @return
 249          */
 250         public String getNote(int progress) {
 251                 return String.format("Completed %d%%.\n", progress);
 252         }
 253
 254         /**
 255          * Retrieve the last note delivered by the ProcessMonitor.
 256          *
 257          * @return
 258          */
 259         public String getNote() {
 260                 return note;
 261         }
 262
 263         public int getProgressAsync() {
 264                 return progressAsync;
 265         }
 266
 267         /**
 268          * Set the [min,max] progress safely.
 269          *
 270          * SwingWorker only allows progress between 0 and 100. This method safely
 271          * translates [min,max] to [0,100].
 272          *
 273          * @param n
 274          */
 275         public void setProgressAsync(int n) {
 276                 n = (max > min ? Math.max(min, Math.min(n, max)) : Math.max(max, Math.min(n, min)));
 277                 progressAsync = n;
 278                 n = (n - min) * 100 / (max - min);
 279                 n = (n < 0 ? 0 : n > 100 ? 100 : n);
 280                 progressPercent = n;
 281         }
 282
 283         ///// the StateMachine /////
 284
 285         private final static int STATE_INIT = 0;
 286         private final static int STATE_LOOP = 1;
 287         private final static int STATE_WAIT = 2;
 288         private final static int STATE_DONE = 99;
 289
 290         private StateHelper helper;
 291
 292         protected StateHelper getHelper() {
 293                 return helper;
 294         }
 295
 296         private boolean isPaused;
 297
 298         protected void setPaused(boolean tf) {
 299                 isPaused = tf;
 300                 firePropertyChange(PROPERTY_PAUSE, null, (tf ? PAUSED : RESUMED));
 301                 if (!tf)
 302                         stateLoop();
 303         }
 304
 305         protected boolean isPaused() {
 306                 return isPaused;
 307         }
 308
 309         /**
 310          * The StateMachine's main loop.
 311          *
 312          * Note that a return from this method will exit doInBackground, trigger the
 313          * isDone() state on the underying worker, and scheduling its done() for
 314          * execution on the AWTEventQueue.
 315          *
 316          * Since this happens essentially immediately, it is unlikely that
 317          * SwingWorker.isCancelled() will ever be true. Thus, the SwingWorker task
 318          * itself won't be cancelable in Java or in JavaScript, since its
 319          * doInBackground() method is officially complete, and isDone() is true well
 320          * before we are "really" done. FutureTask will not set isCancelled() true once
 321          * the task has run.
 322          *
 323          * We are using an asynchronous task specifically because we want to have the
 324          * opportunity for the ProgressMonitor to report in JavaScript. We will have to
 325          * cancel our task and report progress explicitly using our own methods.
 326          *
 327          */
 328         @Override
 329         public boolean stateLoop() {
 330                 while (helper.isAlive() && !isPaused) {
 331                         switch (helper.getState()) {
 332                         case STATE_INIT:
 333                                 setProgressAsync(min);
 334                                 initAsync();
 335                                 helper.setState(STATE_WAIT);
 336                                 continue;
 337                         case STATE_LOOP:
 338                                 if (checkCanceled()) {
 339                                         helper.setState(STATE_DONE);
 340                                         firePropertyChange(PROPERTY_STATE, null, CANCELED_ASYNC);
 341                                 } else {
 342                                         int ret = doInBackgroundAsync(progressAsync);
 343                                         if (!helper.isAlive() || isPaused) {
 344                                                 continue;
 345                                         }
 346                                         progressAsync = ret;
 347                                         setProgressAsync(progressAsync);
 348                                         setNote(getNote(progressAsync));
 349                                         setProgress(progressPercent);
 350                                         if (progressMonitor != null) {
 351                                                 progressMonitor.setProgress(max > min ? progressAsync : max + min - progressAsync);
 352                                         }
 353                                         helper.setState(progressAsync == max ? STATE_DONE : STATE_WAIT);
 354                                 }
 355                                 continue;
 356                         case STATE_WAIT:
 357                                 // meaning "sleep" and then "loop"
 358                                 helper.setState(STATE_LOOP);
 359                                 helper.sleep(delayMillis);
 360                                 return true;
 361                         default:
 362                         case STATE_DONE:
 363                                 stopProgressMonitor();
 364                                 // Put the doneAsync() method on the AWTEventQueue
 365                                 // just as for SwingWorker.done().
 366                                 if (isAsync) {
 367                                         SwingUtilities.invokeLater(doneRunnable);
 368                                 } else {
 369                                         doneRunnable.run();
 370                                 }
 371
 372                                 return false;
 373                         }
 374                 }
 375                 if (!helper.isAlive()) {
 376                         stopProgressMonitor();
 377                 }
 378                 return false;
 379         }
 380
 381         private void stopProgressMonitor() {
 382                 if (progressMonitor != null) {
 383                         progressMonitor.close();
 384                         progressMonitor = null;
 385                 }
 386         }
 387
 388         private Runnable doneRunnable = new Runnable() {
 389                 @Override
 390                 public void run() {
 391                         doneAsync();
 392                         firePropertyChange(PROPERTY_STATE, null, DONE_ASYNC);
 393                 }
 394
 395         };
 396
 397         private boolean checkCanceled() {
 398                 if (isMonitorCanceled() || isCancelled()) {
 399                         helper.interrupt();
 400                         return true;
 401                 }
 402                 return false;
 403         }
 404
 405         //// final SwingWorker methods not to be used by subclasses ////
 406
 407         private boolean isMonitorCanceled() {
 408                 return (progressMonitor != null && progressMonitor.isCanceled());
 409         }
 410
 411         /**
 412          * see SwingWorker, made final here.
 413          *
 414          */
 415         @Override
 416         final protected Void doInBackground() throws Exception {
 417                 helper = new StateHelper(this);
 418                 setProgressAsync(min);
 419                 helper.next(STATE_INIT);
 420                 return null;
 421         }
 422
 423         /**
 424          * see SwingWorker, made final here. Nothing to do.
 425          *
 426          */
 427         @Override
 428         final public void done() {
 429         }
 430
 431 }