de.esprit.appsuite.task

## Class RunStateFlag

- java.lang.Object
- - de.esprit.common.util.DumpableObject
  - - de.esprit.common.util.TransferableObject
    - - de.esprit.appsuite.task.RunStateFlag

- All Implemented Interfaces:
    TaskIdHolder, Renderable, DeepCloneable, Dumpable, java.io.Serializable, java.lang.Cloneable
  Direct Known Subclasses:
    RemoteRunStateFlag

      public class RunStateFlag
      extends TransferableObject
      implements Renderable, TaskIdHolder

  This flag is used to track the `RunState` of a running `AsyncTask`. Note that the current `RunState` is not necessarily consistent to the persistent states returned by wasCancelled(), isSucceeded(), isFailed(). A task is typically cancelled from outside which puts it into the wasCancelled() state. But in fact it will actually continue running until it detects the state change by itself in which case it throws a `CancellationException`.
  Author:
    Rainer Buesch
  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `RunStateFlag(RunStateFlag flag)` Copy constructor for FAST copy of a `RunStateFlag`
    `RunStateFlag(java.lang.String taskName, TaskType taskType)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addChild(TaskId taskId)` Adds a child taskId during execution
    `void` | `checkCancelled()` Throws a `CancellationException` if this flag was ever cancelled
    `<T> T` | `deepClone()` Overridden to create a FAST deep clone of this `RunStateFlag` by copy constructor.
    `boolean` | `equals(java.lang.Object obj)` Compares by `TaskId`.
    `java.util.List<TaskId>` | `getCancellableTaskIds()` Returns the list of `TaskId`s of child-tasks in reverse order as they should be cancelled.
    `int` | `getChildCount()` Returns the number of child- or sub-tasks that yet have been started within this task.
    `int` | `getChildNestingDepth()`
    `TaskId` | `getCurrentChild()` Returns the `TaskId` of the currently executing child/sub-task.
    `java.lang.Exception` | `getError()`
    `java.lang.String` | `getFullName()` Returns the full name of the task which generally is a path starting with main-task name followed by the child/sub-tasknames whereas a child/sub-taskname is concatenated with '+' or a '-' sign respectively.
    `java.lang.String` | `getMainTaskName()`
    `TaskType` | `getMainTaskType()`
    `int` | `getMaxChildTasks()`
    `java.awt.Color` | `getRenderColor()`
    `javax.swing.Icon` | `getRenderIcon()`
    `java.lang.String` | `getRenderText()`
    `RunState` | `getRunState()`
    `TaskId` | `getTaskId()` Returns the unique identifier for this task.
    `boolean` | `hasChildTasks()` Tells whether a child/sub-task is being executed currently.
    `boolean` | `hasCurrentChildTask()`
    `boolean` | `hasError()` Tells whether this stateFlag contains an Exception raised during execution.
    `int` | `hashCode()`
    `boolean` | `isCancellable()`
    `boolean` | `isCancelled()`
    `boolean` | `isChildFinished()`
    `boolean` | `isChildRunning()`
    `boolean` | `isChildStarted()`
    `boolean` | `isChildSucceeded()`
    `boolean` | `isFailed()`
    `boolean` | `isFinished()`
    `boolean` | `isProgress()`
    `boolean` | `isRunning()`
    `boolean` | `isRunningAsChildTask()`
    `boolean` | `isStarted()`
    `boolean` | `isSucceeded()`
    `boolean` | `isSyncMode()`
    `void` | `removeLastChild()`
    `protected void` | `reset()`
    `void` | `setCancellable(boolean isCancellable)`
    `void` | `setCancelled()` Sets the cancelled state and marks it persistently as cancelled
    `protected void` | `setCancelRequested()` Sets the wasCancelled flag in order to indicate that this task should not run any further.
    `void` | `setChildFinished()`
    `void` | `setChildSucceeded()`
    `void` | `setFailed(java.lang.Exception error)` Sets the FAILED state and stores the error
    `void` | `setFinished()`
    `java.lang.String` | `setMainTaskName(java.lang.String taskName)` Sets the name of this task.
    `TaskType` | `setMainTaskType(TaskType taskType)` Sets the type of this task.
    `void` | `setMaxChildTasks(int maxChildTasks)` Tells the number of child-tasks that are expected to run.
    `void` | `setProgress()`
    `void` | `setRunning(boolean isRunning)`
    `void` | `setStarted()`
    `void` | `setSucceeded()` Sets the SUCCEEDED state and marks it persistently as succeeded
    `void` | `setSyncMode(boolean isSyncMode)` Sets the task into synchronous execution mode.
    `void` | `setTaskId(TaskId taskId)` Setting a new `TaskId` means restarting this task as a main-task.
    `DumpString` | `toDumpString(DumpString s)` This method allows subclasses to add values to the existing DumpString of the superclass.
    `ToString` | `toString(ToString s)` This method allows subclasses to add values to the existing ToString of the superclass.
    `boolean` | `wasCancelled()` Tells whether the persistent wasCancelled flag has yet been set.
    `boolean` | `wasFailed()` Tells whether this stateFlag contains an Exception raised during execution.
    `boolean` | `wasSucceeded()` Tells whether the persistent wasSucceeded flag yet has been set.

    - ### Methods inherited from class de.esprit.common.util.TransferableObject

      `clone`

    - ### Methods inherited from class de.esprit.common.util.DumpableObject

      `configureDumpHeadlineLength, configureDumpMaxElementsPrinted, copyDumpStringValues, copyToStringValues, createDumpHeader, toDumpString, toString`

    - ### Methods inherited from class java.lang.Object

      `finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### RunStateFlag

          public RunStateFlag(java.lang.String taskName,
                      TaskType taskType)

    - #### RunStateFlag

          public RunStateFlag(RunStateFlag flag)

      Copy constructor for FAST copy of a `RunStateFlag`

  - ### Method Detail

    - #### setRunning

          public void setRunning(boolean isRunning)

    - #### isRunning

          public boolean isRunning()

    - #### setMainTaskName

          public java.lang.String setMainTaskName(java.lang.String taskName)

      Sets the name of this task. Note that this name is just for rendering a name for the task. During execution this name always reflects the name of the main task.
      See Also:
        `getFullName()`

    - #### setMainTaskType

          public TaskType setMainTaskType(TaskType taskType)

      Sets the type of this task. Note that this type is just for rendering the task type icon. During execution this name always reflects the type of the main task although a running sub- or child task may have a different type.

    - #### setMaxChildTasks

          public void setMaxChildTasks(int maxChildTasks)

      Tells the number of child-tasks that are expected to run. This info is mainly used to drive a double ProgressBar.

    - #### getMaxChildTasks

          public int getMaxChildTasks()

    - #### setSyncMode

          public void setSyncMode(boolean isSyncMode)

      Sets the task into synchronous execution mode. In this mode the task will not be registered at the `TaskManager` and it won't generate any progress events.

    - #### isSyncMode

          public boolean isSyncMode()

      See Also:
        `setSyncMode(boolean)`

    - #### getChildCount

          public int getChildCount()

      Returns the number of child- or sub-tasks that yet have been started within this task.

    - #### getChildNestingDepth

          public int getChildNestingDepth()

    - #### getMainTaskName

          public java.lang.String getMainTaskName()

    - #### getMainTaskType

          public TaskType getMainTaskType()

    - #### getTaskId

          public TaskId getTaskId()

      Description copied from interface: `TaskIdHolder`
      Returns the unique identifier for this task. This identifier is only valid for a single task execution. When the same task instance executes another time then it will have a new `TaskId`.
      Specified by:
        `getTaskId` in interface `TaskIdHolder`

    - #### setTaskId

          public void setTaskId(TaskId taskId)

      Setting a new `TaskId` means restarting this task as a main-task. Thus we must reset the `RunStateFlag` here! As the new `TaskId` is created by the same task both taskName and taskType must match in `TaskId` and `RunStateFlag`

    - #### reset

          protected void reset()

    - #### getRunState

          public RunState getRunState()

    - #### setStarted

          public void setStarted()

    - #### setFailed

          public void setFailed(java.lang.Exception error)

      Sets the FAILED state and stores the error

    - #### setCancelRequested

          protected void setCancelRequested()

      Sets the wasCancelled flag in order to indicate that this task should not run any further. Note that once a cancel is requested the state will remain persistent until the next reset() call.
      See Also:
        `wasCancelled()`

    - #### setCancelled

          public void setCancelled()

      Sets the cancelled state and marks it persistently as cancelled
      See Also:
        `wasCancelled()`

    - #### setSucceeded

          public void setSucceeded()

      Sets the SUCCEEDED state and marks it persistently as succeeded
      See Also:
        `wasSucceeded()`

    - #### setFinished

          public void setFinished()

    - #### setProgress

          public void setProgress()

    - #### isRunningAsChildTask

          public boolean isRunningAsChildTask()

    - #### setChildSucceeded

          public void setChildSucceeded()

    - #### setChildFinished

          public void setChildFinished()

    - #### hasCurrentChildTask

          public boolean hasCurrentChildTask()

    - #### isChildRunning

          public boolean isChildRunning()

    - #### isSucceeded

          public boolean isSucceeded()

    - #### isChildStarted

          public boolean isChildStarted()

    - #### isChildSucceeded

          public boolean isChildSucceeded()

    - #### isChildFinished

          public boolean isChildFinished()

    - #### isStarted

          public boolean isStarted()

    - #### isProgress

          public boolean isProgress()

    - #### isFinished

          public boolean isFinished()

    - #### isCancelled

          public boolean isCancelled()

    - #### isFailed

          public boolean isFailed()

    - #### wasCancelled

          public boolean wasCancelled()

      Tells whether the persistent wasCancelled flag has yet been set. This flag is valid until the next reset() call. Note: this is NOT identical to the cancelled state. It may happen, that a task is being cancelled after it has finished already. In this case the wasCancelled flag is set, but the task never ran through the cancelled state.
      See Also:
        `setCancelRequested()`

    - #### checkCancelled

          public void checkCancelled()

      Throws a `CancellationException` if this flag was ever cancelled

    - #### hasError

          public boolean hasError()

      Tells whether this stateFlag contains an Exception raised during execution.

    - #### wasFailed

          public boolean wasFailed()

      Tells whether this stateFlag contains an Exception raised during execution.

    - #### wasSucceeded

          public boolean wasSucceeded()

      Tells whether the persistent wasSucceeded flag yet has been set. This flag is valid until the next reset() call. Note: this is NOT identical to the SUCCEEDED state.

    - #### getError

          public java.lang.Exception getError()

    - #### setCancellable

          public void setCancellable(boolean isCancellable)

    - #### isCancellable

          public boolean isCancellable()

    - #### getRenderColor

          public java.awt.Color getRenderColor()

      Specified by:
        `getRenderColor` in interface `Renderable`

    - #### getRenderIcon

          public javax.swing.Icon getRenderIcon()

      Specified by:
        `getRenderIcon` in interface `Renderable`

    - #### getRenderText

          public java.lang.String getRenderText()

      Specified by:
        `getRenderText` in interface `Renderable`

    - #### getFullName

          public java.lang.String getFullName()

      Returns the full name of the task which generally is a path starting with main-task name followed by the child/sub-tasknames whereas a child/sub-taskname is concatenated with '+' or a '-' sign respectively.

    - #### equals

          public boolean equals(java.lang.Object obj)

      Compares by `TaskId`. Note that RunStateFlags are considered to be equal if they contain the same `TaskId`, independent of their current RunState!
      Overrides:
        `equals` in class `java.lang.Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### addChild

          public void addChild(TaskId taskId)

      Adds a child taskId during execution

    - #### removeLastChild

          public void removeLastChild()

    - #### hasChildTasks

          public boolean hasChildTasks()

      Tells whether a child/sub-task is being executed currently.

    - #### getCurrentChild

          public TaskId getCurrentChild()

      Returns the `TaskId` of the currently executing child/sub-task.

    - #### getCancellableTaskIds

          public java.util.List<TaskId> getCancellableTaskIds()

      Returns the list of `TaskId`s of child-tasks in reverse order as they should be cancelled.

    - #### deepClone

          public <T> T deepClone()

      Overridden to create a FAST deep clone of this `RunStateFlag` by copy constructor.
      Specified by:
        `deepClone` in interface `DeepCloneable`
      Overrides:
        `deepClone` in class `TransferableObject`

    - #### toString

          public ToString toString(ToString s)

      Description copied from interface: `Dumpable`
      This method allows subclasses to add values to the existing ToString of the superclass. Usually subclasses only need to override this method.
      Specified by:
        `toString` in interface `Dumpable`
      Overrides:
        `toString` in class `DumpableObject`

    - #### toDumpString

          public DumpString toDumpString(DumpString s)

      Description copied from interface: `Dumpable`
      This method allows subclasses to add values to the existing DumpString of the superclass. Usually subclasses only need to override this method.
      Specified by:
        `toDumpString` in interface `Dumpable`
      Overrides:
        `toDumpString` in class `DumpableObject`

Copyright © 2014 EsprIT-Systems. All Rights Reserved.