verinec.util
Class AbstractProgramExec

java.lang.Object
  verinec.util.AbstractProgramExec

Direct Known Subclasses:

ProgramExec, SshProgramExec

public abstract class AbstractProgramExec
extends Object

Wrapper methods for execution of native programs.

These methods provide for simpler program execution, allowing to redirect program output or input to files (the < / > parameters in a shell), or retrieving the output as a stream. They allow to set a timeout after which program execution is interrupted.

You can execute a program and wait for its result, or execute it asynchronous, that is in a separate thread without waiting for it to finish.

Version:

$Revision: 761 $

Author:

david.buchmann at unifr.ch

Nested Class Summary

static class	AbstractProgramExec.StreamGobbler Class to read the input stream asynchonously.
class	AbstractProgramExec.TimeoutWatcher A TimerTask that will call timeout() when invoked if the ProgramExec instance has not finished.

Field Summary

private String	commandline
protected File	cwd The current working directory for the process.
private AbstractProgramExec.StreamGobbler	errG
private OutputStream	errStream
private InputStream	inStream
private AbstractProgramExec.StreamGobbler	outG
private OutputStream	outStream
private Process	process
(package private) boolean	timedOut

Constructor Summary

AbstractProgramExec(String commandline, File cwd, InputStream stdin, OutputStream stdout, OutputStream stderr)
Prepare a program execution.

Method Summary

void	abortExecution() Stop the program execution.
void	execAsync() Start the program execution and return immediately.
int	execSync(int timeout) Execute the command line and wait for it to terminate.
int	exitValue() Get the exit value of the program after asynchronous execution.
boolean	hasFinished() Use in asynchronous execution to check if program has terminated.
protected abstract Process	startProcess(String cmdline, File cwd) Factory method to instantiate a process.
private void	timeout() For the TimeoutWatcher to notify that process has run too long if not yet finished.

Methods inherited from class java.lang.Object

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

Field Detail

inStream

private InputStream inStream

outStream

private OutputStream outStream

errStream

private OutputStream errStream

cwd

protected File cwd

The current working directory for the process.

commandline

private String commandline

process

private Process process

errG

private AbstractProgramExec.StreamGobbler errG

outG

private AbstractProgramExec.StreamGobbler outG

timedOut

boolean timedOut

Constructor Detail

AbstractProgramExec

public AbstractProgramExec(String commandline,
                           File cwd,
                           InputStream stdin,
                           OutputStream stdout,
                           OutputStream stderr)

Prepare a program execution. Afterwards, you can either run the program synchronous or asynchronous.

The input for the program can be given as an InputStream that will be piped to the program as stdin. If you have a file as input, you can use java.io.FileInputStream. stdin can be null, in which case no input is given to the program.

The output can be pushed into OutputStreams for later treatment. If both streams are null, output is discarded. If the stdout stream is null only, errors are written into stderr, if stderr is null, both out and err written into stdout. Again, you can use FileOutputStream to write into files. The streams will be closed when the program execution is finished.

It is recommended to wrap the output streams with a BufferedOutputStream to avoid delays.

Parameters:

commandline - Name of the executable with all parameters. (Do not forget full path if executable is not in the path for programs).

cwd - The current working directory directory for the new process (defaults to the system property user.dir if null).

stdin - A Stream that will be fed to the process as input (ignored if null).

stdout - A Stream to write the program output into (discarded if null).

stderr - A Stream to write the program error output into (redirected to stdout if null).

Method Detail

startProcess

protected abstract Process startProcess(String cmdline,
                                        File cwd)
                                 throws VerinecException

Factory method to instantiate a process. cwd must be used as path to current working directory for the new process. If the user did not specify cwd, the property value of user.dir is used.

Parameters:

cmdline - The command line to execute.

cwd - The current working directory to execute the cmdline in.

Returns:

A process instance for the current implementation.

Throws:

VerinecException - if the specified command can not be executed.

execSync

public int execSync(int timeout)
             throws InterruptedException,
                    VerinecException

Execute the command line and wait for it to terminate.

Parameters:

timeout - The time in seconds after which the execution should be interrupted (0 for no timeout).

Returns:

The exit code of the program.

Throws:

InterruptedException - If the timeout occurs or the process is otherwise interrupted. (If after a timeout, the output streams do not close, a VerinecException is thrown.)

VerinecException - If other errors occur.

execAsync

public void execAsync()
               throws VerinecException

Start the program execution and return immediately. To know if execution has terminated, use hasFinished(), to get the exit value of program execution exitValue(), to abort execution abortExecution(). There is no timeout, but you can use the TimeoutWatcher to set a Timer.

Throws:

VerinecException - When the program can not be launched.

hasFinished

public boolean hasFinished()

Use in asynchronous execution to check if program has terminated.

Returns:

True if the program is terminated, false otherwise.

exitValue

public int exitValue()
              throws InterruptedException

Get the exit value of the program after asynchronous execution. If the program has not yet finished or timed out, exceptions are thrown.

Returns:

The exit code of the finished program execution.

Throws:

IllegalStateException - If the execution has not yet begun.

IllegalThreadStateException - If execution of the program has not yet terminated.

InterruptedException - If program execution was aborted after timeout.

abortExecution

public void abortExecution()
                    throws VerinecException

Stop the program execution.

Waits at maximum 5 seconds for the program to finish. If it is still not finished after waiting for the error or output streams, throws an exception. Tries to wait at most for 10 seconds for the output and error streams to finish being read. If that fails, throws a VerinecException so you know the streams are not yet ready.

It is well possible that you get a stack trace from the stream redirectors. This should not be harmful, however.

Throws:

VerinecException - If the program did not terminate or result streams do not finish within 10 seconds.

timeout

private void timeout()

For the TimeoutWatcher to notify that process has run too long if not yet finished. Does nothing if process execution has been terminated.

See Also:

exitValue()