de.esprit.appsuite.task

## Interface AsyncExecutable<C extends ApplicationContext>

- All Superinterfaces:
    ApplicationObject<C>, CancellableTask, Executable, SimpleLogSupport, TaskMonitorSupport
  All Known Subinterfaces:
    AsyncTask<C>, JournalTask<S>, RemoteTask<S>, RemoteTaskEventReceiver<C>, WorkflowTask<C>
  All Known Implementing Classes:
    AbstractArchiveExtractor, AbstractArchiver, AbstractAsciiDownloadTask, AbstractAsciiParser, AbstractAsciiParserWFT, AbstractAsyncExecutable, AbstractAsyncTask, AbstractBatchTask, AbstractBinaryDownloadTask, AbstractClientEDT, AbstractClientTask, AbstractClientWFT, AbstractClientWorkflow, AbstractDatabaseBatchTask, AbstractDataParserWFT, AbstractDownloadTask, AbstractEventDrivenWFT, AbstractFileStreamWFT, AbstractJavaCommandWFT, AbstractJournalOsProcessTask, AbstractJournalTask, AbstractOsProcessTask, AbstractOsProcessWFT, AbstractRemoteOsProcessTask, AbstractRemoteTask, AbstractServerTask, AbstractStreamParserWFT, AbstractSwingTask, AbstractTaskOptionDialogWFT, AbstractTaskOptionWFT, AbstractTimerTask, AbstractWFT, AbstractWorkflow, AbstractZipArchiverWFT, AgentExecutorTask, AgentWatchDogTask, AppLaunchPrefsWriter, AppLaunchTask, AppLaunchTask.MyNativeProcessTask, ArchiveConfigDialogWFT, ArchiveExtractTask, ArchiveExtractWFT, ArchiveExtractWorkflow, ArchiveListTask, ArchiveListWFT, ArchiveListWorkflow, AsciiParser, AsciiParserTask, AsciiWriter, AsyncAgentExecutorAdapter, BatchTaskConfigWriter, CheckWorkingDirectoryWFT, CleanupWorkingDirectoryWFT, ClientCommandTask, CoClientReconnectorTask, CoServerBindTask, CreateZipArchiveWFT, CreateZipArchiveWorkflow, CredentialWriter, DatabaseConfigWriter, DataParser, DataParserTask, DataWriter, DBLoadTask, DBOCompiler, DBOHtmlWriter, DBOWriter, DBOXmlReader, DBOXmlWriter, ExecutorTask, FileDownloadWFT, FileDownloadWorkflow, FileNameInputWFT, FileTransferClientTask, FileTransferTask, FileTransferWFT, FileUploadWFT, FileUploadWorkflow, GroupMemberWriter, GroupWriter, GuiReconnectorTask, InputFileChooserWFT, JavaAppDescriptorWriter, JavaCommandTask, LogCleanupBatchTask, MessageReceiveTask, NdfParser, NdfWriter, NetworkConfigWriter, OutputFileChooserWFT, PermissionConfigWriter, ProgressWindowExecutorTask, RemoteArchiveExtractEDT, RemoteArchiveExtractTask, RemoteArchiveExtractWFT, RemoteArchiveExtractWorkflow, RemoteArchiveListEDT, RemoteArchiveListTask, RemoteArchiveListWFT, RemoteArchiveListWorkflow, RemoteJavaCommandTask, RequestServiceTask, SimpleAsciiParser, StdinReaderTask, StringTagWriter, SwingExecutorTask, TagWriter, TarArchiver, TarExtractor, TarGZArchiver, TarLister, TaskCollection, TestBatchTask, TimestampWriter, TransferServiceTask, UserWriter, WatchDogTask, XmlDataParser, XmlTagWriter, ZipArchiver, ZipArchiverTask, ZipExtractor, ZipLister, ZipSoftwareExtractor

      public interface AsyncExecutable<C extends ApplicationContext>
      extends ApplicationObject<C>, Executable, CancellableTask, TaskMonitorSupport, SimpleLogSupport

  Any class that implements this interface is able to be executed as a sub-task within an `AsyncTask`. Note that this interface does NOT define a cancel() method, because it can only be cancelled by canceling the `AsyncTask` in which it runs.
  Author:
    Rainer Buesch

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `checkCancelled()` Throws a `CancellationException` when cancellation has been detected.
    `void` | `checkForErrorAndRethrow(java.lang.Exception e)` Sets the caught Exception into the `RunStateFlag` and rethrows it.
    `void` | `executeAsync()` Contains the code to be executed asynchronously.
    `void` | `executeSubTask(AsyncExecutable subTask)` Runs the sub-task synchronously within the same execution thread.
    `java.lang.String` | `getName()` Return the task-name which is rendered by the RunStateFlag during run.
    `<R> R` | `getResult()` Returns the execution result of this task, if any.
    `RunStateFlag` | `getRunStateFlag()` Returns the current `RunStateFlag`.
    `TaskId` | `getTaskId()` Returns an identifier object for this task.
    `TaskType` | `getType()` Return the task-type which is rendered by the RunStateFlag during run.
    `void` | `handleCancellation()` The implementation calls doOnCancel() in a safe manner, which is supposed to do any cleanup work.
    `void` | `handleFailure(java.lang.Exception error)` The implementation calls doOnFailure(Exception) in a safe manner, which is supposed to do any cleanup work.
    `boolean` | `isCancellable()` Tells whether this task can be cancelled.
    `void` | `notifyProceeded(java.lang.Object result, int step, int maxSteps, java.lang.String message)` Notifies progress to an attached `TaskMonitor`.
    `void` | `setCancellable(boolean isCancellable)` Tells whether this task is cancellable - is true by default.
    `void` | `setName(java.lang.String name)` Sets the name of this task
    `void` | `setResult(java.lang.Object obj)` Stores the execution result of this instance
    `void` | `setRunStateFlag(RunStateFlag stateFlag)` Assigns the `RunStateFlag` of the executing `AsyncTask` to this executable.
    `void` | `sleepChecked(long millis)` Used to delay task execution.

    - ### Methods inherited from interface de.esprit.appsuite.launch.ApplicationObject

      `getApplicationContext`

    - ### Methods inherited from interface de.esprit.common.type.Executable

      `execute`

    - ### Methods inherited from interface de.esprit.appsuite.task.CancellableTask

      `wasCancelled`

    - ### Methods inherited from interface de.esprit.appsuite.task.monitor.TaskMonitorSupport

      `addMonitor, clearMonitors, getMonitorCount, getMonitors, hasMonitor, removeMonitor`

    - ### Methods inherited from interface de.esprit.common.log.SimpleLogSupport

      `getLogChannel, isLogDebug, isLogVerbose, logDebug, logDump, logError, logError, logFatal, logInfo, logVerbose, logWarning, setLogChannel`

- - ### Method Detail

    - #### executeAsync

          void executeAsync()
                            throws java.lang.Exception

      Contains the code to be executed asynchronously. WARNING: This method should never be called directly by the programmer. It rather must be called by `Runnable.run()` for async execution.
      Throws:
        `java.lang.Exception`
      See Also:
        `for synchronous execution`

    - #### setRunStateFlag

          void setRunStateFlag(RunStateFlag stateFlag)

      Assigns the `RunStateFlag` of the executing `AsyncTask` to this executable.

    - #### getRunStateFlag

          RunStateFlag getRunStateFlag()

      Returns the current `RunStateFlag`. Note that there is exactly one `RunStateFlag` per running task. Child-tasks as well as sub-tasks share it with their parents.

    - #### sleepChecked

          void sleepChecked(long millis)

      Used to delay task execution. This method may be called within loops in order to be friendly to other tasks, not making the system too busy. Note that when going to and awaking from sleep the cancel state is checked and a `CancellationException` is thrown just in case.

    - #### checkCancelled

          void checkCancelled()

      Throws a `CancellationException` when cancellation has been detected.

    - #### getName

          java.lang.String getName()

      Return the task-name which is rendered by the RunStateFlag during run.

    - #### setName

          void setName(java.lang.String name)

      Sets the name of this task

    - #### getType

          TaskType getType()

      Return the task-type which is rendered by the RunStateFlag during run.

    - #### getTaskId

          TaskId getTaskId()

      Returns an identifier object for this task. Note: The `TaskId` is used to model the task-hierarchy in a `RunStateFlag`. For `AsyncExecutable`s it's always an instance of `PseudoTaskId`.

    - #### isCancellable

          boolean isCancellable()

      Tells whether this task can be cancelled. A task may want to ignore canceling during critical phases. This flag may be set during task run in order to enable/disable canceling.
      See Also:
        `setCancellable(boolean)`

    - #### setCancellable

          void setCancellable(boolean isCancellable)

      Tells whether this task is cancellable - is true by default.

    - #### getResult

          <R> R getResult()

      Returns the execution result of this task, if any. This call does NOT block but fetches the result whatever it is at the moment.
      See Also:
        `setResult(Object)`

    - #### setResult

          void setResult(java.lang.Object obj)

      Stores the execution result of this instance
      See Also:
        `getResult()`

    - #### handleCancellation

          void handleCancellation()

      The implementation calls doOnCancel() in a safe manner, which is supposed to do any cleanup work.

    - #### handleFailure

          void handleFailure(java.lang.Exception error)

      The implementation calls doOnFailure(Exception) in a safe manner, which is supposed to do any cleanup work.

    - #### checkForErrorAndRethrow

          void checkForErrorAndRethrow(java.lang.Exception e)
                                       throws java.lang.Exception

      Sets the caught Exception into the `RunStateFlag` and rethrows it. Note that `CancellationException` and `InterruptedException` as well as `StopException` are not treated as errors.
      Throws:
        `java.lang.Exception`

    - #### notifyProceeded

          void notifyProceeded(java.lang.Object result,
                             int step,
                             int maxSteps,
                             java.lang.String message)

      Notifies progress to an attached `TaskMonitor`. This only applies when the execution is done asynchronously within an `AsyncTask`.
      Parameters:
        `result` - any intermediate result that may be achieved so far
        `step` - the count of progress steps (-1 for initializing the progressBar)
        `maxSteps` - the expected maximum number of progress steps (0 if not known)
        `message` - any textual message explaining what the progress is

    - #### executeSubTask

          void executeSubTask(AsyncExecutable subTask)
                              throws java.lang.Exception

      Runs the sub-task synchronously within the same execution thread. Note that the sub-task shares the `RunStateFlag` with the main-task. During sub-task execution the monitor will receive CHILD_STARTED CHILD_SUCCEEDED and CHILD_FINISHED notifications. Any PROGRESS notifications in between are associated to the current sub-task.
      Throws:
        `java.lang.Exception`

Copyright © 2014 EsprIT-Systems. All Rights Reserved.