com.segue.tm.published.api.testlaunch

Class ExtProcessTestLaunchBean

java.lang.Object

com.segue.tm.published.api.testlaunch.AbstractTestLaunchBean

com.segue.tm.published.api.testlaunch.ExtProcessTestLaunchBean

All Implemented Interfaces:

TestLaunchBean

public abstract class ExtProcessTestLaunchBean
extends AbstractTestLaunchBean

Convenience class for test launch plugin subclasses to launch an external process. Plugins may derive from this class instead of implementing TestLaunchBean if the plugin needs to launch an external process. This class provides a runExternalProcess(java.lang.String[], java.lang.String[], java.io.File, java.io.PrintStream) method accomplishing starting an arbitrary external executable. Beside providing the stdout, stderr log info, the process is automatically killed when the framework demands termination. This is typically if the user aborts the execution manually, a specified timeout expired, or the execution server shuts down.

Constructor Summary

Constructors

Constructor and Description
ExtProcessTestLaunchBean()

Method Summary

Modifier and Type	Method and Description
protected void	asyncRunExternalProcess(java.lang.String[] commandLine, java.util.Map<java.lang.String,java.lang.String> envVariables, java.io.File workingDir, java.io.PrintStream log) Asynchronously executes an arbitrary executable as external process.
protected int	runExternalProcess(java.lang.String[] commandLine, java.lang.String[] envVariables, java.io.File workingDir, java.io.PrintStream log) Executes an arbitrary executable as external process.
java.lang.String	stdErrReport() Returns the current stderr output of the process.
java.lang.String	stdOutReport() Returns the current stdout output of the process.
void	terminate() Called to demand immediate termination while an execution takes currently place.
java.lang.Integer	waitForCompletion(int timeout) Waits the timespan passed as parameter for an asynchronously executing process to complete.

Methods inherited from class com.segue.tm.published.api.testlaunch.AbstractTestLaunchBean

context, getTestDefDescription, getTestDefName, initialize, setTestDefName, sourceAccess

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.segue.tm.published.api.testlaunch.TestLaunchBean

execute

Constructor Detail

ExtProcessTestLaunchBean

public ExtProcessTestLaunchBean()

Method Detail

runExternalProcess

protected final int runExternalProcess(java.lang.String[] commandLine,
                                       java.lang.String[] envVariables,
                                       java.io.File workingDir,
                                       java.io.PrintStream log)
                                throws java.io.IOException,
                                       java.lang.InterruptedException

Executes an arbitrary executable as external process. Note that the stdout and stderr log is stored in any case, the passed log stream is optional in addition. The typical usecase for the passed log stream is to use the stream returned by TestLaunchResultDrain.getLog() to keep the log output in a logfile and display it as online run info.

Parameters:

commandLine - an array where the first element is path to the executable and following elements the parameters passed.

envVariables - null or environment variables to be set, where each string in form "name=value"

workingDir - the working directory (current directory) for the external process

log - an optional additional stream to which the process's stdout and stderr is printed

Returns:

the exit code of the process

Throws:

java.io.IOException - if the process failed to start

java.lang.InterruptedException - if the framework demanded termination calling terminate()

asyncRunExternalProcess

protected final void asyncRunExternalProcess(java.lang.String[] commandLine,
                                             java.util.Map<java.lang.String,java.lang.String> envVariables,
                                             java.io.File workingDir,
                                             java.io.PrintStream log)
                                      throws java.io.IOException

Asynchronously executes an arbitrary executable as external process. The call immediately returns while the external process is launched. Note that the stdout and stderr log is stored in any case, the passed log stream is optional in addition. The typical usecase for the passed log stream is to use the stream returned by TestLaunchResultDrain.getLog() to keep the log output in a logfile and display it as online run info. Note, if environment variables are set, the process will only have these variables defined, but no global system variables. Use System.getenv() and include global variables on demand in the passed parameter.

Parameters:

commandLine - an array where the first element is path to the executable and following elements the parameters passed.

envVariables - environment variable definitions, may be null

workingDir - the working directory (current directory) for the external process

log - an optional additional stream to which the process's stdout and stderr is printed

Throws:

java.io.IOException - if the process failed to start

terminate

public void terminate()

Called to demand immediate termination while an execution takes currently place. This method is called concurrently to the TestLaunchBean.execute(long, com.segue.tm.published.api.testlaunch.TestLaunchResultDrain) method, which on reaction should throw an InterruptedException. This is typically if the user aborts the execution manually, a specified timeout has expired, or the execution server is shut down.

waitForCompletion

public final java.lang.Integer waitForCompletion(int timeout)
                                          throws java.lang.InterruptedException,
                                                 java.io.IOException

Waits the timespan passed as parameter for an asynchronously executing process to complete.

Parameters:

timeout - the time in milliseconds how long to wait for the process.

Returns:

the exit value of the process if it has finished, null otherwise

Throws:

java.lang.InterruptedException - if the calling thread has been interrupted.

java.io.IOException

stdOutReport

public final java.lang.String stdOutReport()

Returns the current stdout output of the process. This may be called also during execution as snapshot of so far printed output.

Returns:

the current stdout output of the process.

stdErrReport

public final java.lang.String stdErrReport()

Returns the current stderr output of the process. This may be called also during execution as snapshot of so far printed output.

Returns:

the current stderr output of the process.