de.esprit.appsuite.task.osproc

## Class AbstractOsProcessTask<C extends ApplicationContext>

- java.lang.Object
- - de.esprit.common.util.DumpableObject
  - - de.esprit.appsuite.launch.AbstractApplicationObject<C>
    - - de.esprit.appsuite.task.AbstractAsyncExecutable<C>
      - - de.esprit.appsuite.task.AbstractAsyncTask<C>
        - - de.esprit.appsuite.task.osproc.AbstractOsProcessTask<C>

- All Implemented Interfaces:
    ApplicationObject<C>, AsyncExecutable<C>, AsyncTask<C>, CancellableTask, LocalCancellableTask, TaskMonitorSupport, TaskIdHolder, SimpleLogSupport, Dumpable, Executable, java.lang.Runnable
  Direct Known Subclasses:
    AbstractOsProcessWFT, AbstractRemoteOsProcessTask, AppLaunchTask.MyNativeProcessTask, JavaCommandTask

      public abstract class AbstractOsProcessTask<C extends ApplicationContext>
      extends AbstractAsyncTask<C>

  This Task encapsulates a running OS-process on the local system. Note that the task must have a command as well as a working-directory defined. An OS-process exit status other than 0 is treated as an error. You may be notified about actions of the running OS-process in two ways:
  - Console output
    Use `setNotifyConsoleOutput(boolean)` to enable `doOnConsoleOutput(String)` being called for each output line.
  - File system changes
    Use `setNotifyFileSystemChange(boolean)` to enable `doOnFileSystemChange(ChangeType, File)` being called for each file system change discovered in the working directory.
  Author:
    Rainer Buesch

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `OUTPUT_TYPE_CONSOLE`

    - ### Fields inherited from class de.esprit.appsuite.task.AbstractAsyncExecutable

      `childTaskRef, isTestMode, monitorController, resultRef, stateFlag`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractOsProcessTask(C ctx, LogChannel logCh, java.lang.String taskName)`
    `AbstractOsProcessTask(C ctx, LogChannel logCh, java.lang.String taskName, TaskType taskType)`
    `AbstractOsProcessTask(C ctx, java.lang.String taskName)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `cancel()` Flags the task as being cancelled.
    `protected void` | `checkExitStatus(int status)` Checks whether the process exit status is OK, a 0 is considered to be successful
    `protected java.io.InputStream` | `createStandardInput()` May be overridden to provide an input stream that is passed to the process via stdin (if for instance the process needs to read an input file).
    `protected java.io.PrintWriter` | `createStandardOutput()` Create an output channel where the process console output is written to.
    `protected java.io.File` | `createStandardOutputFile()` Creates a File in the process working directory for logging the process console output.
    `protected void` | `doOnConsoleOutput(java.lang.String outputLine)` Is called whenever the OS-process prints an output line to the system console.
    `protected void` | `doOnFileSystemChange(ChangeType changeType, java.io.File file)` Is called whenever a file system change is discovered.
    `protected void` | `doOnFinish()` Is called in ANY CASE when the task has finished.
    `void` | `executeAsync()` Must be overridden to perform the async part.
    `java.lang.String` | `getCommandBaseName()` Returns the first argument of the command string.
    `java.lang.String` | `getCommandString()`
    `java.lang.ProcessBuilder` | `getProcessBuilder()`
    `java.io.File` | `getStandardOutputFile()`
    `java.io.File` | `getWorkingDir()`
    `boolean` | `isNotifyConsoleOutput()` Tells whether a progress should be sent for each process console output line.
    `void` | `putEnv(java.lang.String key, java.lang.String value)`
    `void` | `setCommand(java.lang.String... command)`
    `void` | `setNotifyConsoleOutput(boolean isNotify)` If set to true, then this task calls `doOnConsoleOutput(String)` for text line which the OS-process prints to the system console.
    `void` | `setNotifyFileSystemChange(boolean isNotify)` If set to true, then the process starts a watch-service on the working-directory in order to detect file system changes.
    `void` | `setStandardOutputFile(java.io.File standardOutputFile)` Sets the file to be used for standard output.
    `void` | `setWorkingDir(java.io.File workingDir)`
    `TaskId` | `submit()` Submits this task for execution to the default application thread pool
    `TaskId` | `submit(java.util.concurrent.ExecutorService pool)` Submits this task for execution to the given thread pool
    `DumpString` | `toDumpString(DumpString s)` This method allows subclasses to add values to the existing DumpString of the superclass.

    - ### Methods inherited from class de.esprit.appsuite.task.AbstractAsyncTask

      `awaitFinished, awaitFinished, awaitStarted, createTaskId, deregisterTask, doOnStart, doOnSuccess, executeChildTask, executeChildTask, getCurrentFuture, getMaxChildTasks, getPriority, getProcessingDuration, getStartTime, getStopWatch, handleFinish, handleStart, handleSuccess, isRegisterForCancel, isRunning, notifyProceeded, registerTask, releaseStart, run, setCurrentFuture, setMaxChildTasks, setPriority, setRegisterForCancel, setReleaseTimeout, submitInternal, toString, wasSucceeded`

    - ### Methods inherited from class de.esprit.appsuite.task.AbstractAsyncExecutable

      `addMonitor, checkCancelled, checkForErrorAndRethrow, clearMonitors, createRunStateFlag, doOnCancel, doOnFailure, execute, executeSubTask, getError, getMaxProgressSteps, getMonitorCount, getMonitors, getName, getProgressStepCount, getResult, getRunStateFlag, getTaskId, getType, handleCancellation, handleFailure, hasError, hasMonitor, isCancellable, registerTaskStateChange, removeMonitor, resetProgress, setCancellable, setLogLevel, setMaxProgressSteps, setMonitor, setName, setName, setResult, setRunStateFlag, setTaskId, setType, shouldFireMonitor, sleepChecked, wasCancelled`

    - ### Methods inherited from class de.esprit.appsuite.launch.AbstractApplicationObject

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

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

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

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

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

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

      `getError, hasError, setName`

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

      `checkCancelled, checkForErrorAndRethrow, executeSubTask, getName, getResult, getRunStateFlag, getTaskId, getType, handleCancellation, handleFailure, isCancellable, setCancellable, setName, setResult, setRunStateFlag, sleepChecked`

    - ### 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.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`

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

      `wasCancelled`

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

      `getTaskId`

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

      `toDumpString, toString`

- - ### Field Detail

    - #### OUTPUT_TYPE_CONSOLE

          public static final java.lang.String OUTPUT_TYPE_CONSOLE

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### AbstractOsProcessTask

          public AbstractOsProcessTask(C ctx,
                               java.lang.String taskName)

    - #### AbstractOsProcessTask

          public AbstractOsProcessTask(C ctx,
                               LogChannel logCh,
                               java.lang.String taskName)

    - #### AbstractOsProcessTask

          public AbstractOsProcessTask(C ctx,
                               LogChannel logCh,
                               java.lang.String taskName,
                               TaskType taskType)

  - ### Method Detail

    - #### submit

          public TaskId submit()
                        throws java.lang.Exception

      Description copied from interface: `AsyncTask`
      Submits this task for execution to the default application thread pool
      Specified by:
        `submit` in interface `AsyncTask<C extends ApplicationContext>`
      Overrides:
        `submit` in class `AbstractAsyncTask<C extends ApplicationContext>`
      Throws:
        `java.lang.Exception` - if the pool is busy

    - #### submit

          public TaskId submit(java.util.concurrent.ExecutorService pool)
                        throws java.lang.Exception

      Description copied from interface: `AsyncTask`
      Submits this task for execution to the given thread pool
      Specified by:
        `submit` in interface `AsyncTask<C extends ApplicationContext>`
      Overrides:
        `submit` in class `AbstractAsyncTask<C extends ApplicationContext>`
      Throws:
        `java.lang.Exception` - if the pool is busy

    - #### setNotifyFileSystemChange

          public void setNotifyFileSystemChange(boolean isNotify)

      If set to true, then the process starts a watch-service on the working-directory in order to detect file system changes.

    - #### setNotifyConsoleOutput

          public final void setNotifyConsoleOutput(boolean isNotify)

      If set to true, then this task calls `doOnConsoleOutput(String)` for text line which the OS-process prints to the system console.

    - #### isNotifyConsoleOutput

          public final boolean isNotifyConsoleOutput()

      Tells whether a progress should be sent for each process console output line.
      Returns:
        true by default

    - #### setWorkingDir

          public final void setWorkingDir(java.io.File workingDir)

    - #### getWorkingDir

          public final java.io.File getWorkingDir()

    - #### setCommand

          public final void setCommand(java.lang.String... command)

    - #### getCommandString

          public java.lang.String getCommandString()

    - #### getCommandBaseName

          public final java.lang.String getCommandBaseName()

      Returns the first argument of the command string. If it is a pathname it is stripped down to the last part name of the path without .exe file extension.

    - #### getProcessBuilder

          public final java.lang.ProcessBuilder getProcessBuilder()

    - #### putEnv

          public final void putEnv(java.lang.String key,
                    java.lang.String value)

    - #### executeAsync

          public void executeAsync()
                            throws java.lang.Exception

      Description copied from class: `AbstractAsyncTask`
      Must be overridden to perform the async part. From within this method you may directly call `AbstractAsyncTask.notifyProceeded(Object, int, int, String)` in order to notify about task progress. Note: the running task should periodically call `AbstractAsyncExecutable.checkCancelled()` in order to detect cancellation.
      Specified by:
        `executeAsync` in interface `AsyncExecutable<C extends ApplicationContext>`
      Specified by:
        `executeAsync` in class `AbstractAsyncTask<C extends ApplicationContext>`
      Throws:
        `java.lang.Exception`
      See Also:
        `for synchronous execution`

    - #### doOnFinish

          protected void doOnFinish()

      Description copied from class: `AbstractAsyncTask`
      Is called in ANY CASE when the task has finished. Maybe overridden to perform any task finalization. Note that any Exceptions thrown are caught and just logged but do NOT affect the task.
      Overrides:
        `doOnFinish` in class `AbstractAsyncTask<C extends ApplicationContext>`

    - #### doOnConsoleOutput

          protected void doOnConsoleOutput(java.lang.String outputLine)
                                    throws java.lang.Exception

      Is called whenever the OS-process prints an output line to the system console. This feature only works when notification for output printing is activated. By default the output is logged and a PROGRESS is sent for it.
      Throws:
        `java.lang.Exception`
      See Also:
        `setNotifyConsoleOutput(boolean)`

    - #### doOnFileSystemChange

          protected void doOnFileSystemChange(ChangeType changeType,
                                  java.io.File file)

      Is called whenever a file system change is discovered. This feature only works when a watch service has been activated on the work-directory of the process.
      See Also:
        `setNotifyFileSystemChange(boolean)`

    - #### checkExitStatus

          protected void checkExitStatus(int status)
                                  throws ErroneousExitStatusException

      Checks whether the process exit status is OK, a 0 is considered to be successful
      Throws:
        `ErroneousExitStatusException`

    - #### getStandardOutputFile

          public final java.io.File getStandardOutputFile()

    - #### setStandardOutputFile

          public void setStandardOutputFile(java.io.File standardOutputFile)

      Sets the file to be used for standard output. Note that a default is always created. If this file is set to null no output will be written.
      Parameters:
        `standardOutputFile` - the standardOutputFile to set

    - #### createStandardInput

          protected java.io.InputStream createStandardInput()
                                                     throws java.lang.Exception

      May be overridden to provide an input stream that is passed to the process via stdin (if for instance the process needs to read an input file).
      Throws:
        `java.lang.Exception`

    - #### createStandardOutput

          protected java.io.PrintWriter createStandardOutput()
                                                      throws java.lang.Exception

      Create an output channel where the process console output is written to. This default implementation returns a PrintWriter to the file created by `createStandardOutputFile()`.
      Throws:
        `java.lang.Exception`

    - #### createStandardOutputFile

          protected java.io.File createStandardOutputFile()

      Creates a File in the process working directory for logging the process console output. The file is named `proc__.log`. May be overridden to provide a different output filename. If null is returned, then the output is not written to a file.

    - #### cancel

          public void cancel()

      Description copied from class: `AbstractAsyncTask`
      Flags the task as being cancelled. The next call to `AbstractAsyncExecutable.checkCancelled()` will result a `CancellationException` being thrown. As a result `AbstractAsyncExecutable.doOnCancel()` is being called on the task.
      Specified by:
        `cancel` in interface `LocalCancellableTask`
      Overrides:
        `cancel` in class `AbstractAsyncTask<C extends ApplicationContext>`

    - #### 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.