org.rhq.core.util.exec
Class ProcessExecutor

java.lang.Object
  org.rhq.core.util.exec.ProcessExecutor

public class ProcessExecutor
extends Object

Executes a process using 100% Java API.

Warning: caution should be exercised when using this class - it allows any process to be started with no security restrictions.

Author:

John Mazzitelli

Constructor Summary

ProcessExecutor()

Method Summary

protected File	createOutputFile(ProcessToStart process) Creates the output file and returns its File representation.
ProcessExecutorResults	execute(ProcessToStart processToStart) This executes any operating system process as described in the given start command.
protected String[]	getCommandLine(ProcessToStart process) Builds the command line containing the full path to the program executable and any arguments that are to be passed to the program.
protected String	getFullProgramExecutablePath(ProcessToStart process) Returns the full pathname to the program executable.
protected File	getInputFile(ProcessToStart process) Gets the input file and returns its File representation.
protected File	getWorkingDirectory(ProcessToStart process) Returns the full pathname to the working directory.
protected void	redirectStreams(ProcessToStart process, Process childProcess) This method redirects the stdout/stderr streams of the child process to the output log file and pipes the contents of the input file (if one was specified) to the stdin stream of the child process.
protected Integer	startProgram(ProcessToStart process) Starts a child process.

Methods inherited from class java.lang.Object

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

Constructor Detail

ProcessExecutor

public ProcessExecutor()

Method Detail

execute

public ProcessExecutorResults execute(ProcessToStart processToStart)

This executes any operating system process as described in the given start command. When this method returns, it can be assumed that the process was launched but not necessarily finished. The caller can ask this method to block until process exits by setting ProcessToStart.setWaitForExit(Long) to a positive, non-zero timeout in milliseconds. On error, the exception will be returned in the returned results.

Parameters:

processToStart - the information on what process to start

Returns:

the results of the process execution

startProgram

protected Integer startProgram(ProcessToStart process)
                        throws Exception

Starts a child process. When this method returns, it can be assumed that the process was launched. On error, an exception is thrown. Note that this method will also wait for the process to exit if ProcessToStart.getWaitForExit() is positive, non-zero. In that case, the returned value will be the exit code of the process. If this method is told not to wait, the returned value will be null.

Parameters:

process - provides the information necessary to start the child process

Returns:

process exit code (if the method waited for it to exit) or null if this method was to only start the process but not wait or was to wait and the wait time expired before the process exited

Throws:

Exception - if any error occurs while trying to start the child process

redirectStreams

protected void redirectStreams(ProcessToStart process,
                               Process childProcess)
                        throws IOException

This method redirects the stdout/stderr streams of the child process to the output log file and pipes the contents of the input file (if one was specified) to the stdin stream of the child process.

This is done asynchronously so as to avoid deadlocking and to allow the main thread to continue its work.

Once the child process dies, so do the piping threads.

Parameters:

process - used to configure the process

childProcess - the newly spawned child process

Throws:

IOException - if failed to pipe data to/from stdin/stdout

createOutputFile

protected File createOutputFile(ProcessToStart process)
                         throws IOException

Creates the output file and returns its File representation. This is the location where the child process' stdout/stderr output streams get redirected to. Note that if the file does not exist, it will be created; if it does exist, the original will be renamed with a timestamp before a new file is created only if the backup output file flag is Boolean.TRUE; otherwise it will be overwritten.

If the output directory was not specified, a temporary location will be used (i.e. the System property java.io.tmpdir). If the output file name was not specified, one will be generated automatically - using the title if one was specified.

If we are not to capture the output, this method returns null.

Parameters:

process - the process to start

Returns:

output log file (may be null)

Throws:

IOException - if the output file could not be created

FileNotFoundException - the output directory does not exist or is not a valid directory

getInputFile

protected File getInputFile(ProcessToStart process)
                     throws IOException

Gets the input file and returns its File representation. This is the file whose data will be sent to the child process' stdin input stream. Note that if the input file that was specified in the command does not exist, an exception is thrown. If the command does not specify an input file, null is returned.

Parameters:

process - the start command

Returns:

input file (may be null)

Throws:

IOException - if the input file could not be found

FileNotFoundException - the input directory does not exist or is not a valid directory

getFullProgramExecutablePath

protected String getFullProgramExecutablePath(ProcessToStart process)
                                       throws FileNotFoundException

Returns the full pathname to the program executable. If the program executable does not exist, an exception is thrown.

Parameters:

process - the process to start

Returns:

full path name to the program executable file

Throws:

FileNotFoundException - if the program executable does not exist

getWorkingDirectory

protected File getWorkingDirectory(ProcessToStart process)
                            throws FileNotFoundException

Returns the full pathname to the working directory. An exception is thrown if the directory does not exist. If the working directory is null, child process inherits the parent process's current working directory.

Parameters:

process - the process to start

Returns:

the working directory where the program should "start in" - its starting or current directory in other words

Throws:

FileNotFoundException - if the working directory does not exist

getCommandLine

protected String[] getCommandLine(ProcessToStart process)
                           throws FileNotFoundException

Builds the command line containing the full path to the program executable and any arguments that are to be passed to the program.

Parameters:

process - the process to start

Returns:

array of command line arguments (the first of which is the full path to the program executable file)

Throws:

FileNotFoundException - if the program executable file does not exist