org.rhq.core.util.exec
Class ProcessToStart

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

public class ProcessToStart
extends Object

Data describing a process to start.

Author:

John Mazzitelli

Constructor Summary

ProcessToStart()

Method Summary

String[]	getArguments() Returns an array of strings that are the argument values passed on the command line to the program executable.
String[]	getEnvironment() Returns environment variable name/value pairs that define the environment to be passed to the started process.
String[]	getEnvironment(Properties properties) Convenience method that not only returns the environment variables as a String array, but the environment variables are also populated in the given Properties map so the caller can more easily look up environment variables by name.
String	getInputDirectory() Returns the directory where the input file is located.
String	getInputFile() Returns the name of the file that contains data to be input to the program.
String	getOutputDirectory() Returns the directory where the program's output log file will be written.
String	getOutputFile() The file (to be placed in the output directory) where the program's output will be written.
OutputStream	getOutputStream() The output stream where the program's output will be written.
String	getProgramDirectory() Returns the full path to the program executable.
String	getProgramExecutable() Returns the name of the program to execute.
String	getProgramTitle() Returns the title for this program.
Long	getWaitForExit() If 0 or less, the process executor will not wait for the process to exit before returning control.
String	getWorkingDirectory() Returns the working directory of the new process (known also as the current directory or the startup directory).
Boolean	isBackupOutputFile() If true, any previously existing output file will be backed up by renaming it with a date/timestamp.
Boolean	isCaptureOutput() If true, the started process' output will be captured and written to the output file or stream.
Boolean	isCheckExecutableExists() If true, then the executable will first be checked for its existance.
Boolean	isKillOnTimeout() If true, then the process will be forcibly killed if it doesn't exit within the wait time.
void	setArguments(String[] value) Sets the argument values that are to be passed on the command line to the program executable.
void	setBackupOutputFile(Boolean value) Sets the flag to indicate if any previously existing output file should be backed up.
void	setCaptureOutput(Boolean value) Sets the flag to indicate if the process' output should be captured in the output file.
void	setCheckExecutableExists(Boolean value) Sets the flag to indicate if the executable should be checked for existence first.
void	setEnvironment(Properties value) Convienence method that takes a Properties object containing the environment variables, as opposed to an array of strings (see setEnvironment(String[]).
void	setEnvironment(String[] value) Sets the environment variable name/value pairs that define the environment to be passed to the started process.
void	setInputDirectory(String value) Sets the directory where the input file is located.
void	setInputFile(String value) Sets the name of the file that contains data to be input to the program.
void	setKillOnTimeout(Boolean value) Sets the flag to indicate if the process should be killed after the wait timeout expires.
void	setOutputDirectory(String value) Sets the directory where the program's output log file will be written.
void	setOutputFile(String value) Sets the file (to be placed in the output directory) where the program's output will be written.
void	setOutputStream(OutputStream value) The output stream where the program's output will be written.
void	setProgramDirectory(String value) Sets the full path to the program executable.
void	setProgramExecutable(String value) Sets the name of the program to execute.
void	setProgramTitle(String value) Sets the title for this program.
void	setWaitForExit(Long value) If null or is 0 or less, the process executor will not wait for the process to exit before returning control.
void	setWorkingDirectory(String value) Sets the working directory of the new process

Methods inherited from class java.lang.Object

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

Constructor Detail

ProcessToStart

public ProcessToStart()

Method Detail

getProgramTitle

public String getProgramTitle()

Returns the title for this program. This is a simple name to help identify this start command configuration or to just help identify the program being launched.

This is useful when, for example, a Java JVM needs to be started and you want to set the title to describe the main class being launched (since all Java executables that are launched typically have the same executable name, that of "java.exe").

If the title was never set, this will return getProgramExecutable() .

Returns:

the title of the program

setProgramTitle

public void setProgramTitle(String value)

Sets the title for this program.

Parameters:

value - the title of the program (may be null)

See Also:

getProgramTitle()

getProgramExecutable

public String getProgramExecutable()

Returns the name of the program to execute. This is usually just the executable file name without any path information - for that information, see getProgramDirectory(). If, however, getProgramDirectory() returns null, the full path to the executable may be returned by this method.

Returns:

program executable name

setProgramExecutable

public void setProgramExecutable(String value)

Sets the name of the program to execute.

Parameters:

value - program executable name

See Also:

getProgramExecutable()

getProgramDirectory

public String getProgramDirectory()

Returns the full path to the program executable. This is just the directory where the executable file is located without the name of the executable itself - for that information, see getProgramExecutable(). If this returns null, then the full path may be included in the executable name itself.

Returns:

program executable directory location

setProgramDirectory

public void setProgramDirectory(String value)

Sets the full path to the program executable.

Parameters:

value - program executable directory location

See Also:

getProgramExecutable()

getArguments

public String[] getArguments()

Returns an array of strings that are the argument values passed on the command line to the program executable. If null or empty, no arguments will be passed to the program.

Returns:

array of program arguments

setArguments

public void setArguments(String[] value)

Sets the argument values that are to be passed on the command line to the program executable. If null or empty, no arguments will be passed to the program.

Parameters:

value - array of program arguments (may be null or empty)

getEnvironment

public String[] getEnvironment()

Returns environment variable name/value pairs that define the environment to be passed to the started process. A null will allow the subprocess to inherit the parent process environment. Each string must be in the format: name=value.

Returns:

environment variables (may be null or empty)

getEnvironment

public String[] getEnvironment(Properties properties)
                        throws IllegalArgumentException

Convenience method that not only returns the environment variables as a String array, but the environment variables are also populated in the given Properties map so the caller can more easily look up environment variables by name. Note that any properties in the properties object will be cleared out - only the environment variables in this object will populate the properties object once this method returns.

Note that the returned array should still be examined - at the least to see if it is null - even if the caller only wants to use the Properties object for retrieval of the environment variables. This is because a null return value has special semantics, as opposed to a non- null but empty array. See getEnvironment() for more.

Parameters:

properties - a Properties object where the environment variables can be stored (must not be null)

Returns:

environment variables (may be null or empty)

Throws:

IllegalArgumentException - if an environment variable string doesn't conform to the format: name=value or properties is null

setEnvironment

public void setEnvironment(String[] value)

Sets the environment variable name/value pairs that define the environment to be passed to the started process. A null will allow the subprocess to inherit the parent process environment. Each string must be in the format: name=value.

Parameters:

value - environment variables (may be null or empty)

setEnvironment

public void setEnvironment(Properties value)

Convienence method that takes a Properties object containing the environment variables, as opposed to an array of strings (see setEnvironment(String[]). Sets the environment variable name/value pairs that define the environment to be passed to the started process. A null will allow the subprocess to inherit the parent process environment.

Parameters:

value - property name/values stored in a Properties object

See Also:

setEnvironment(String[])

getWorkingDirectory

public String getWorkingDirectory()

Returns the working directory of the new process (known also as the current directory or the startup directory). A null allows the subprocess to inherit the current working directory of the parent process.

Returns:

the working directory path (may be null)

setWorkingDirectory

public void setWorkingDirectory(String value)

Sets the working directory of the new process

Parameters:

value - the working directory path (may be null)

See Also:

getWorkingDirectory()

getOutputDirectory

public String getOutputDirectory()

Returns the directory where the program's output log file will be written. If null, a directory will be assigned (typically the java.io.tmpdir directory).

If getOutputStream() is not null, it overrides this (that is, the stream will get the output, not the output file).

Regardless of this return value, output will not be captured unless explicitly told to do so.

Returns:

the directory where the output log will be written to (may be null)

setOutputDirectory

public void setOutputDirectory(String value)

Sets the directory where the program's output log file will be written.

Parameters:

value - the directory where the output log will be written to (may be null)

See Also:

getOutputDirectory()

getOutputFile

public String getOutputFile()

The file (to be placed in the output directory) where the program's output will be written. This should just be the filename; its full path will be specified by the output directory.

It is in this file where you can view the program's stdout/stderr output stream data.

If null, an auto-generated filename will be used.

If getOutputStream() is not null, it overrides this (that is, the stream will get the output, not the output file).

Regardless of this return value, output will not be captured unless explicitly told to do so.

Returns:

the program's output log file (may be null)

setOutputFile

public void setOutputFile(String value)

Sets the file (to be placed in the output directory) where the program's output will be written.

Parameters:

value - the program's output log file (may be null)

See Also:

getOutputFile()

getOutputStream

public OutputStream getOutputStream()

The output stream where the program's output will be written. If this is null, then getOutputDirectory()/getOutputFile() will be examined if the output should be written to a file.

Regardless of this return value, output will not be captured unless explicitly told to do so.

Returns:

the program's output stream (may be null)

setOutputStream

public void setOutputStream(OutputStream value)

The output stream where the program's output will be written.

Parameters:

value - the program's output stream (may be null)

See Also:

getOutputStream()

getInputDirectory

public String getInputDirectory()

Returns the directory where the input file is located.

If this is specified, the input file must also be specified.

Returns:

directory where the input file is located (may be null)

setInputDirectory

public void setInputDirectory(String value)

Sets the directory where the input file is located.

Parameters:

value - directory where the input file is located (may be null)

See Also:

getInputDirectory()

getInputFile

public String getInputFile()

Returns the name of the file that contains data to be input to the program. The data found in this file will be passed into the started program via the stdin input stream.

If this is specified, the input directory must also be specified.

Returns:

name of the input file (may be null)

setInputFile

public void setInputFile(String value)

Sets the name of the file that contains data to be input to the program.

Parameters:

value - name of the input file (may be null)

See Also:

getInputFile()

getWaitForExit

public Long getWaitForExit()

If 0 or less, the process executor will not wait for the process to exit before returning control. Otherwise, this is the number of milliseconds the process executor will wait for the process to exit. If the time expires, control will return but the process will continue to run (an attempt to kill the process will not be made).

Returns:

wait time (will never be null)

setWaitForExit

public void setWaitForExit(Long value)

If null or is 0 or less, the process executor will not wait for the process to exit before returning control. Otherwise, this is the number of milliseconds the process executor will wait for the process to exit. If the time expires, control will return but the process will continue to run (an attempt to kill the process will not be made).

Parameters:

value - time

isCaptureOutput

public Boolean isCaptureOutput()

If true, the started process' output will be captured and written to the output file or stream. If false, no output file is created and the process' output is simply consumed and ignored even if a non-null output file or stream has been set.

Returns:

capture output flag (default is false, this will never be null)

setCaptureOutput

public void setCaptureOutput(Boolean value)

Sets the flag to indicate if the process' output should be captured in the output file.

Parameters:

value - capture output flag

See Also:

isCaptureOutput()

isBackupOutputFile

public Boolean isBackupOutputFile()

If true, any previously existing output file will be backed up by renaming it with a date/timestamp. If false, any previously existing output file will be overwritten.

Returns:

backup output file flag

setBackupOutputFile

public void setBackupOutputFile(Boolean value)

Sets the flag to indicate if any previously existing output file should be backed up.

Parameters:

value - the backup flag

See Also:

isBackupOutputFile()

isKillOnTimeout

public Boolean isKillOnTimeout()

If true, then the process will be forcibly killed if it doesn't exit within the wait time. If false, the process will be allowed to continue to run for as long as it needs - getWaitForExit() will only force the caller to "wake up" and not block waiting for the process to finish.

Returns:

kill flag (default is false, will never be null)

setKillOnTimeout

public void setKillOnTimeout(Boolean value)

Sets the flag to indicate if the process should be killed after the wait timeout expires.

Parameters:

value - the kill flag

See Also:

isKillOnTimeout()

isCheckExecutableExists

public Boolean isCheckExecutableExists()

If true, then the executable will first be checked for its existance. If the executable does not exist, the execution should fail-fast. If false, the process will attempt to be executed no matter what. This will allow the operating system to check its executable PATH to find the executable if required.

Returns:

check flag (default is true, will never be null)

setCheckExecutableExists

public void setCheckExecutableExists(Boolean value)

Sets the flag to indicate if the executable should be checked for existence first.

Parameters:

value - the check flag

See Also:

isCheckExecutableExists()