Package io.jmix.flowui.backgroundtask

Class BackgroundTask<T,V>

java.lang.Object
io.jmix.flowui.backgroundtask.BackgroundTask<T,V>
Type Parameters:
T - task progress measurement unit
V - result type
Direct Known Subclasses:
LocalizedTaskWrapper, MBeanOperationResultView.OperationBackgroundTask, NotificationsIndicator.ReloadCountTask, ResetPasswordView.ResetPasswordBackgroundTask, SupersetDashboard.FetchGuestTokenTask
public abstract class BackgroundTask<T,V> extends Object
Background task for execute by BackgroundWorker.

If the task is associated with a view through "view" constructor parameter, it will be canceled when the view is closed.

If timeout passed to constructor is exceeded, the task is canceled by special BackgroundTaskWatchDog 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, View<?> view)
      Creates a task with timeout.
      Parameters:
      timeout - timeout
      timeUnit - timeout time unit
      view - owner view

    • BackgroundTask

      protected BackgroundTask(long timeout, TimeUnit timeUnit)
      Creates a task with timeout.

      The task will not be associated with any View.

      Parameters:
      timeout - timeout
      timeUnit - timeout time unit

    • BackgroundTask

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

    • BackgroundTask

      protected BackgroundTask(long timeoutSeconds, View<?> view)
      Create a task with timeout in default TimeUnit.SECONDS unit.
      Parameters:
      timeoutSeconds - timeout in seconds
      view - owner view

  • 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 a working thread

    • done

      public void done(V result)
      Provides exclusive access to this UI from outside a request handling thread when the task is completed.

      Please note that the command might be invoked on a different thread or later on the current thread, which means that custom thread locals might not have the expected values when the command is executed. UI.getCurrent(), VaadinSession.getCurrent() and VaadinService.getCurrent() are set according to this UI before executing the command. Other standard CurrentInstance values such as VaadinService.getCurrentRequest() and VaadinService.getCurrentResponse() will not be defined.

      Parameters:
      result - result of execution returned by run(TaskLifeCycle) method
      See Also:
      • UI.access(Command)

    • canceled

      public void canceled()
      Provides exclusive access to this UI from outside a request handling thread when the task is canceled by BackgroundTaskHandler.cancel() invocation.

      This method is not called in case of timeout expiration or owner view closing.

      Please note that the command might be invoked on a different thread or later on the current thread, which means that custom thread locals might not have the expected values when the command is executed. UI.getCurrent(), VaadinSession.getCurrent() and VaadinService.getCurrent() are set according to this UI before executing the command. Other standard CurrentInstance values such as VaadinService.getCurrentRequest() and VaadinService.getCurrentResponse() will not be defined.

      See Also:
      • UI.access(Command)

    • handleTimeoutException

      public boolean handleTimeoutException()
      Provides exclusive access to this UI from outside a request handling thread if the task timeout is exceeded.

      Please note that the command might be invoked on a different thread or later on the current thread, which means that custom thread locals might not have the expected values when the command is executed. UI.getCurrent(), VaadinSession.getCurrent() and VaadinService.getCurrent() are set according to this UI before executing the command. Other standard CurrentInstance values such as VaadinService.getCurrentRequest() and VaadinService.getCurrentResponse() will not be defined.

      Returns:
      true if this method implementation actually handles this event. Used for chaining handlers.
      See Also:
      • UI.access(Command)

    • handleException

      public boolean handleException(Exception ex)
      Provides exclusive access to this UI from outside a request handling thread if the task run(TaskLifeCycle) method raised an exception.

      Please note that the command might be invoked on a different thread or later on the current thread, which means that custom thread locals might not have the expected values when the command is executed. UI.getCurrent(), VaadinSession.getCurrent() and VaadinService.getCurrent() are set according to this UI before executing the command. Other standard CurrentInstance values such as VaadinService.getCurrentRequest() and VaadinService.getCurrentResponse() will not be defined.

      Parameters:
      ex - exception
      Returns:
      true if this method implementation actually handles the exception. Used for chaining handlers.
      See Also:
      • UI.access(Command)

    • progress

      public void progress(List<T> changes)
      Provides exclusive access to this UI from outside a request handling thread on progress change.

      Please note that the command might be invoked on a different thread or later on the current thread, which means that custom thread locals might not have the expected values when the command is executed. UI.getCurrent(), VaadinSession.getCurrent() and VaadinService.getCurrent() are set according to this UI before executing the command. Other standard CurrentInstance values such as VaadinService.getCurrentRequest() and VaadinService.getCurrentResponse() will not be defined.

      Parameters:
      changes - list of changes since previous invocation
      See Also:
      • UI.access(Command)

    • 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

    • getOwnerView

      @Nullable public final View<?> getOwnerView()
      Returns:
      owner view

    • 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)
      Removes a progress listener.
      Parameters:
      progressListener - listener