Package de.gebit.integrity.runner.forking

## Class DefaultForker

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

- All Implemented Interfaces:
    `Forker`

      public class DefaultForker
      extends Object
      implements Forker

  A default forking implementation. This should be suitable for most execution environments. If not, it is designed to be easily extensible, or alternatively you can of course create an entirely own `Forker` implementation.

  This default forker does effectively create a "mirror" of the current process, runnning the same main class with the same arguments as the main process. It therefore does not accept any parameters (= it does not have a constructor with parameters), since there is no need to do that. However, if you want to create a forker that modifies this behavior, you may very well subclass this one or create one from scratch. You may also use a constructor with parameters (use `ForkerParameter` just like you would for fixture methods) if you want to parameterize your forker in the test scripts.

  Author:
    Rene Schneider - initial API and implementation

- - ### Field Summary

    - ### Fields inherited from interface de.gebit.integrity.runner.forking.Forker

      `SYSPARAM_FORK_NAME, SYSPARAM_FORK_REMOTING_HOST, SYSPARAM_FORK_REMOTING_PORT, SYSPARAM_FORK_SEED, SYSPARAM_FORK_TIMESTATE`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DefaultForker()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected void` | `addApplicationArguments​(List<String> anArgumentList, String[] someCommandLineArguments)` | Adds the application-specific arguments to the argument list.
    `protected void` | `addClassName​(List<String> anArgumentList)` | Adds the name of the main class to the argument list.
    `protected void` | `addClassPath​(List<String> anArgumentList)` | Adds the classpath parameter to the argument list.
    `protected void` | `addForkInformation​(List<String> anArgumentList, String aForkName, long aRandomSeed, TimeSyncState aTimeSyncState)` | Adds the system property definitions telling the fork on which port it should listen and which name it has.
    `protected void` | `addJavaExecutable​(List<String> anArgumentList)` | Adds the name of the java executable to the argument list provided.
    `protected void` | `addJVMArguments​(List<String> anArgumentList)` | Adds any random JVM configuration arguments to the argument list.
    `protected void` | `addTimeSyncInformation​(List<String> anArgumentList, TimeSyncState aTimeSyncState)` | Adds time sync information, if provided for this fork.
    `protected List<String>` | `createArgumentList​(String[] someCommandLineArguments, String aForkName, long aRandomSeed, TimeSyncState aTimeSyncState)` | Creates the argument list used to fork the process.
    `protected LocalForkedProcess` | `createProcess​(List<String> anArgumentList)` | Create a process using the given argument list.
    `ForkedProcess` | `fork​(String[] someCommandLineArguments, String aForkName, long aRandomSeed, TimeSyncState aTimeSyncState)` | Performs the actual forking.
    `protected String` | `getForkHost()` | The host name / IP to which the fork should be bound.
    `protected Integer` | `getForkPort()` | The port to which the fork should be bound.
    `protected String` | `guessMainClassName()` | Tries to determine the fully qualified name of the main class, since you cannot ask the JVM for it unfortunately.

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

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

- - ### Constructor Detail

    - #### DefaultForker

          public DefaultForker()

  - ### Method Detail

    - #### fork

          public ForkedProcess fork​(String[] someCommandLineArguments,
                                    String aForkName,
                                    long aRandomSeed,
                                    TimeSyncState aTimeSyncState)
                             throws ForkException

      Description copied from interface: `Forker`
      Performs the actual forking.
      Specified by:
        `fork` in interface `Forker`
      Parameters:
        `someCommandLineArguments` - the original command line arguments given to the JVM of the parent process
        `aForkName` - the name of the fork
        `aRandomSeed` - the seed for the RNG of the fork
        `aTimeSyncState` - time synchronization state info for this particular fork (will be provided just in case the forker 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
      Returns:
        the newly created process
      Throws:
        `ForkException` - if something goes wrong

    - #### createArgumentList

          protected List<String> createArgumentList​(String[] someCommandLineArguments,
                                                    String aForkName,
                                                    long aRandomSeed,
                                                    TimeSyncState aTimeSyncState)

      Creates the argument list used to fork the process.
      Parameters:
        `someCommandLineArguments` - the command line arguments provided to `#fork(String[], int, String)`.
        `aForkName` - the name for the new fork
        `aRandomSeed` - the seed for the RNG of the fork
        `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
      Returns:
        the argument list

    - #### addJavaExecutable

          protected void addJavaExecutable​(List<String> anArgumentList)

      Adds the name of the java executable to the argument list provided. Default implementation tries to determine this using the system property "java.home".
      Parameters:
        `anArgumentList` - the argument list to extend

    - #### addClassPath

          protected void addClassPath​(List<String> anArgumentList)

      Adds the classpath parameter to the argument list. Default implementation uses the system property "java.class.path".
      Parameters:
        `anArgumentList` - the argument list to extend

    - #### addForkInformation

          protected void addForkInformation​(List<String> anArgumentList,
                                            String aForkName,
                                            long aRandomSeed,
                                            TimeSyncState aTimeSyncState)

      Adds the system property definitions telling the fork on which port it should listen and which name it has.
      Parameters:
        `anArgumentList` - the argument list to extend
        `aForkName` - the name for the fork
        `aRandomSeed` - the seed for the RNG of the fork
        `aTimeSyncState` - time synchronization state info for this particular fork (will be provided just in case the 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 provided

    - #### addTimeSyncInformation

          protected void addTimeSyncInformation​(List<String> anArgumentList,
                                                TimeSyncState aTimeSyncState)

      Adds time sync information, if provided for this fork.
      Parameters:
        `anArgumentList` - the argument list to extend
        `aTimeSyncState` - time synchronization state info for this particular fork (will be provided just in case the 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 provided

    - #### getForkHost

          protected String getForkHost()

      The host name / IP to which the fork should be bound.
      Returns:

    - #### getForkPort

          protected Integer getForkPort()

      The port to which the fork should be bound.
      Returns:

    - #### addJVMArguments

          protected void addJVMArguments​(List<String> anArgumentList)

      Adds any random JVM configuration arguments to the argument list. Default implementation asks the `RuntimeMXBean`.
      Parameters:
        `anArgumentList` - the argument list to extend

    - #### addClassName

          protected void addClassName​(List<String> anArgumentList)

      Adds the name of the main class to the argument list. Default implementation uses `guessMainClassName()` to search stack traces for the class.
      Parameters:
        `anArgumentList` - the argument list to extend

    - #### addApplicationArguments

          protected void addApplicationArguments​(List<String> anArgumentList,
                                                 String[] someCommandLineArguments)

      Adds the application-specific arguments to the argument list.
      Parameters:
        `anArgumentList` - the argument list to extend
        `someCommandLineArguments` - the applications' arguments, as provided to Integrity

    - #### createProcess

          protected LocalForkedProcess createProcess​(List<String> anArgumentList)
                                              throws ForkException

      Create a process using the given argument list.
      Parameters:
        `anArgumentList` - the arguments
      Returns:
        the forked process
      Throws:
        `ForkException`

    - #### guessMainClassName

          protected String guessMainClassName()

      Tries to determine the fully qualified name of the main class, since you cannot ask the JVM for it unfortunately.
      Returns:
        the name of the main class