Package de.gebit.integrity.runner.forking

## Class Fork

- java.lang.Object
- - de.gebit.integrity.runner.forking.Fork

-     public class Fork
      extends Object

  A fork is the result of the test runner forking during test execution.
  Author:
    Rene Schneider - initial API and implementation

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected ConsoleOutputInterceptor` | `consoleInterceptor` | The console interceptor.
    `protected com.google.inject.Provider<ConversionContext>` | `conversionContextProvider` | The conversion context provider.
    `protected ProcessTerminator` | `processWatchdog` | The process watchdog, used to govern other processes started by the test runner.
    `protected TestTimeAdapter` | `testTimeAdapter` | The test time adapter.
    `protected ValueConverter` | `valueConverter` | The value converter, which is used to resolve and convert values before sending them to forks.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Fork​(ForkDefinition aDefinition, Forker aForker, String[] someCommandLineArguments, int aMainPortNumber, TestRunnerCallback aCallback, SetList aSetList, IntegrityRemotingServer aServer, ForkCallback aForkCallback)` | Creates a new fork.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `cleanup()` | Cleans up internal state before reattempting another fork startup.
    `boolean` | `connect​(long aTimeout, ClassLoader aClassLoader)` | Connects to the successfully started fork process.
    `void` | `deliverTimeSyncResult​(TimeSyncResultMessage aResult)` | Delivers the result of a timesync orchestrated by the master process to a fork, who originally requested it.
    `ForkResultSummary` | `executeNextSegment​(boolean aWaitForForkDisconnect)` | Triggers execution of the next segment on the fork.
    `IntegrityRemotingClient` | `getClient()` |
    `ForkDefinition` | `getDefinition()` |
    `ExecutionStates` | `getExecutionState()` |
    `static int` | `getForkTimesyncTimeout()` | The fork timesync timeout, in seconds.
    `ForkedProcess` | `getProcess()` |
    `boolean` | `hasAborted()` | Returns true if the fork was aborted due to an `AbortExecutionException`.
    `TimeSyncResultMessage` | `injectTestTimeState​(long aRealtimeOffset, long aRealtimeDecouplingTime, double aProgressionFactor)` | Injects the state variables for test time calculation into the fork.
    `boolean` | `isAlive()` | Checks whether a fork is still alive.
    `boolean` | `isConnected()` |
    `void` | `kill()` | Destroy a fork.
    `void` | `start​(TimeSyncState aTimeSyncState)` | Actually start the fork.
    `protected void` | `transmitVariableUpdates()` | Transmits the buffered variable updates.
    `void` | `unsetVariableValue​(VariableOrConstantEntity aVariable)` | Unsets a variables' value.
    `void` | `updateVariableValue​(VariableOrConstantEntity aVariable, Object aValue)` | Updates a variable value.

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

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

- - ### Field Detail

    - #### processWatchdog

          @Inject
          protected ProcessTerminator processWatchdog

      The process watchdog, used to govern other processes started by the test runner.

    - #### consoleInterceptor

          @Inject
          protected ConsoleOutputInterceptor consoleInterceptor

      The console interceptor. Used to output strings to the console, which prevents them from being intercepted by the interceptor!

    - #### valueConverter

          @Inject
          protected ValueConverter valueConverter

      The value converter, which is used to resolve and convert values before sending them to forks.

    - #### conversionContextProvider

          @Inject
          protected com.google.inject.Provider<ConversionContext> conversionContextProvider

      The conversion context provider.

    - #### testTimeAdapter

          @Inject
          protected TestTimeAdapter testTimeAdapter

      The test time adapter.

  - ### Constructor Detail

    - #### Fork

          public Fork​(ForkDefinition aDefinition,
                      Forker aForker,
                      String[] someCommandLineArguments,
                      int aMainPortNumber,
                      TestRunnerCallback aCallback,
                      SetList aSetList,
                      IntegrityRemotingServer aServer,
                      ForkCallback aForkCallback)

      Creates a new fork. Calling this constructor triggers the creation of the actual forked process implicitly.
      Parameters:
        `aDefinition` - the fork definition
        `aForker` - the forker is a kind of factory for forked processes
        `someCommandLineArguments` - the complete and original command line arguments with which the current test runner was started
        `aMainPortNumber` - the port number used for the remoting server in the current test runner
        `aCallback` - the test runner callback
        `aSetList` - the setlist
        `aServer` - the remoting server of the parent test runner
        `aForkCallback` - the fork callback to use

  - ### Method Detail

    - #### getForkTimesyncTimeout

          public static int getForkTimesyncTimeout()

      The fork timesync timeout, in seconds.

    - #### start

          public void start​(TimeSyncState aTimeSyncState)
                     throws ForkException

      Actually start the fork. This can be run more than once in case of multiple fork startup attempts, but only if the forked process has died and/or been killed properly before. This is ensured by calling cleanup().
      Parameters:
        `aTimeSyncState` - time synchronization state info for this particular fork (will be provided just in case the forker or fork wants to do something with it - time synchronization also happens right after the connection to the fork was established by the master) or null if no test time sync state is to be set
      Throws:
        `ForkException` - in case of errors

    - #### kill

          public void kill()
                    throws InterruptedException

      Destroy a fork.
      Throws:
        `InterruptedException`

    - #### cleanup

          public void cleanup()
                       throws InterruptedException

      Cleans up internal state before reattempting another fork startup.
      Throws:
        `InterruptedException`

    - #### getDefinition

          public ForkDefinition getDefinition()

    - #### getProcess

          public ForkedProcess getProcess()

    - #### getClient

          public IntegrityRemotingClient getClient()

    - #### getExecutionState

          public ExecutionStates getExecutionState()

    - #### hasAborted

          public boolean hasAborted()

      Returns true if the fork was aborted due to an `AbortExecutionException`.
      Returns:
        true if test execution was aborted on the fork

    - #### isAlive

          public boolean isAlive()

      Checks whether a fork is still alive.
      Returns:
        true if the fork is running

    - #### isConnected

          public boolean isConnected()

    - #### connect

          public boolean connect​(long aTimeout,
                                 ClassLoader aClassLoader)
                          throws IOException

      Connects to the successfully started fork process.
      Parameters:
        `aTimeout` - the timeout after which the method shall return in milliseconds
        `aClassLoader` - the classloader to use when deserializing objects
      Returns:
        true if successful, false if the timeout was hit or if the process cannot be connected to yet (in this case this method will return immediately)
      Throws:
        `IOException`

    - #### executeNextSegment

          public ForkResultSummary executeNextSegment​(boolean aWaitForForkDisconnect)

      Triggers execution of the next segment on the fork. Will block until the fork has finished executing the segment.

    - #### transmitVariableUpdates

          protected void transmitVariableUpdates()

      Transmits the buffered variable updates.

    - #### updateVariableValue

          public void updateVariableValue​(VariableOrConstantEntity aVariable,
                                          Object aValue)

      Updates a variable value. This does not immediately update the variable, but buffers the update until it's being transmitted to the fork.
      Parameters:
        `aVariable` - the variable entity to update
        `aValue` - the new value

    - #### unsetVariableValue

          public void unsetVariableValue​(VariableOrConstantEntity aVariable)

      Unsets a variables' value. Similar to `updateVariableValue(VariableOrConstantEntity, Object)`, but for variable clearing.
      Parameters:
        `aVariable` - the variable entity to unset

    - #### injectTestTimeState

          public TimeSyncResultMessage injectTestTimeState​(long aRealtimeOffset,
                                                           long aRealtimeDecouplingTime,
                                                           double aProgressionFactor)

      Injects the state variables for test time calculation into the fork. Waits for the result object to be retrieved and returns it. In case of a timeout, a runtime exception is thrown.
      Parameters:
        `aStartTime` -
        `aProgressionFactor` -

    - #### deliverTimeSyncResult

          public void deliverTimeSyncResult​(TimeSyncResultMessage aResult)

      Delivers the result of a timesync orchestrated by the master process to a fork, who originally requested it.
      Parameters:
        `aResult` - the result message to send