Package io.jmix.ui.executor

Class BackgroundTask<T,V>

java.lang.Object
io.jmix.ui.executor.BackgroundTask<T,V>
Type Parameters:
T - task progress measurement unit
V - result type
Direct Known Subclasses:
ImapMessageEdit.InitAttachmentTask, ImapMessageEdit.InitBodyTask, LocalizedTaskWrapper, MBeanOperationResultScreen.OperationBackgroundTask
public abstract class BackgroundTask<T,V> extends Object
Background task for execute by BackgroundWorker.
If the task is associated with a screen through ownerFrame constructor parameter, it will be canceled when the screen is closed.
If timeout passed to constructor is exceeded, the task is canceled by special WatchDog thread.
Simplest usage example: 

    BackgroundTask<Integer, Void> task = new BackgroundTask<Integer, Void>(10, this) {
        public Void run(TaskLifeCycle<Integer> taskLifeCycle) throws Exception {
            for (int i = 0; i < 5; i++) {
                TimeUnit.SECONDS.sleep(1);
            }
            return null;
        }
    };
    BackgroundTaskHandler taskHandler = backgroundWorker.handle(task);
    taskHandler.execute();

  • Constructor Details

    • BackgroundTask

      protected BackgroundTask(long timeout, TimeUnit timeUnit, Screen screen)
      Create a task with timeout.
      Parameters:
      timeout - timeout
      timeUnit - timeout time unit
      screen - owner frame

    • BackgroundTask

      protected BackgroundTask(long timeout, TimeUnit timeUnit)
      Create a task with timeout.
      The task will not be associated with any window.
      Parameters:
      timeout - timeout
      timeUnit - timeout time unit

    • BackgroundTask

      protected BackgroundTask(long timeoutSeconds)
      Create a task with timeout in default SECONDS unit.
      The task will not be associated with any window.
      Parameters:
      timeoutSeconds - timeout in seconds

    • BackgroundTask

      protected BackgroundTask(long timeoutSeconds, Screen screen)
      Create a task with timeout in default SECONDS unit.
      Parameters:
      timeoutSeconds - timeout in seconds
      screen - owner frame

  • Method Details

    • run

      public abstract V run(TaskLifeCycle<T> taskLifeCycle) throws Exception
      Main method that performs a task.
      Called by the execution environment in a separate working thread.
      Implementation of this method should support interruption:
      Parameters:
      taskLifeCycle - lifecycle object that allows the main method to interact with the execution environment
      Returns:
      task result
      Throws:
      Exception - exception in working thread

    • done

      public void done(V result)
      Called by the execution environment in UI thread when the task is completed.
      Parameters:
      result - result of execution returned by run(TaskLifeCycle) method

    • canceled

      public void canceled()
      Called by the execution environment in UI thread if the task is canceled by BackgroundTaskHandler.cancel() invocation.
      This method is not called in case of timeout expiration or owner window closing.

    • handleTimeoutException

      public boolean handleTimeoutException()
      Called by the execution environment in UI thread if the task timeout is exceeded.
      Returns:
      true if this method implementation actually handles this event. Used for chaining handlers.

    • handleException

      public boolean handleException(Exception ex)
      Called by the execution environment in UI thread if the task run(TaskLifeCycle) method raised an exception.
      Parameters:
      ex - exception
      Returns:
      true if this method implementation actually handles the exception. Used for chaining handlers.

    • progress

      public void progress(List<T> changes)
      Called by the execution environment in UI thread on progress change.
      Parameters:
      changes - list of changes since previous invocation

    • getParams

      @Nullable public Map<String,Object> getParams()
      Called by the execution environment in UI thread to prepare some execution parameters. These parameters can be requested by the working thread inside the run(TaskLifeCycle) method by calling TaskLifeCycle.getParams().
      Returns:
      parameters map or null if parameters are not needed

    • getOwnerFrame

      @Nullable @Deprecated public final Screen getOwnerFrame()
      Deprecated.
      Use getOwnerScreen()
      Returns:
      owner screen

    • getOwnerScreen

      @Nullable public final Screen getOwnerScreen()
      Returns:
      owner screen

    • getTimeoutMilliseconds

      public final long getTimeoutMilliseconds()
      Returns:
      timeout in ms

    • getTimeoutSeconds

      public final long getTimeoutSeconds()
      Returns:
      timeout in sec

    • addProgressListener

      public final void addProgressListener(BackgroundTask.ProgressListener<T,V> progressListener)
      Add additional progress listener.
      Parameters:
      progressListener - listener

    • getProgressListeners

      public final List<BackgroundTask.ProgressListener<T,V>> getProgressListeners()
      Additional progress listeners.
      Returns:
      copy of the progress listeners collection

    • removeProgressListener

      public final void removeProgressListener(BackgroundTask.ProgressListener<T,V> progressListener)
      Remove a progress listener.
      Parameters:
      progressListener - listener