org.rhq.enterprise.communications.command.impl.start
Class StartCommand

java.lang.Object
  org.rhq.enterprise.communications.command.AbstractCommand
      org.rhq.enterprise.communications.command.impl.start.StartCommand

All Implemented Interfaces:

Serializable, Command

public class StartCommand
extends AbstractCommand

Command used to start operating system processes.

Warning: This command has security implications - it defines any process to start. A remote service that executes this command should have some type of security restrictions in place, to avoid running rogue or unauthorized commands.

Author:

John Mazzitelli

See Also:

Serialized Form

Field Summary

static CommandType	COMMAND_TYPE command type constant identifying this command
static ParameterDefinition	PARAM_ARGS identifies the parameter whose value is an array of arguments to pass to the executable
static ParameterDefinition	PARAM_BACKUP_OUTPUT_FILE identifies the parameter whose value is the flag to determine whether to backup any previously existing output file; if false, it will be overwritten
static ParameterDefinition	PARAM_CAPTURE_OUTPUT identifies the parameter whose value is the flag to determine if the started process's output should be dumped to the output file
static ParameterDefinition	PARAM_ENV identifies the parameter whose value is an Properties object containing environment variable name/value pairs to give to the process
static ParameterDefinition	PARAM_INPUT_DIR identifies the parameter whose value is the directory location of the file that contains data to be fed into the programs' stdin input stream
static ParameterDefinition	PARAM_INPUT_FILE identifies the parameter whose value is the file name that contains data to be fed into the programs' stdin input stream
static ParameterDefinition	PARAM_OUTPUT_DIR identifies the parameter whose value is the directory where the process's output log will be written
static ParameterDefinition	PARAM_OUTPUT_FILE identifies the parameter whose value is the filename (in the output directory) where the process's stdout/stderr output log will be written
static ParameterDefinition	PARAM_PROGRAM_DIR identifies the parameter whose value is the full path to the program's executable
static ParameterDefinition	PARAM_PROGRAM_EXE identifies the parameter whose value is the name of the program to execute
static ParameterDefinition	PARAM_PROGRAM_TITLE identifies the parameter whose value is a simple title for this start command configuration (may be used for output filename)
static ParameterDefinition	PARAM_WAIT_FOR_EXIT identifies the parameter whose value is the time to wait until the process has exited
static ParameterDefinition	PARAM_WORKING_DIR identifies the parameter whose value is directory location to start the process in (the working directory).

Constructor Summary

StartCommand()
Constructor for StartCommand.

StartCommand(Command commandToTransform)
Constructor for StartCommand.

StartCommand(Map<String,Object> commandParameters)
Constructor for StartCommand.

Method Summary

protected CommandType	buildCommandType() Builds the command type of this command.
protected ParameterDefinition[]	buildParameterDefinitions() Builds the set of parameter definitions that this command will use.
void	checkParameterValidity(boolean convertIfNecessary) Ensures that if either PARAM_INPUT_DIR or PARAM_INPUT_FILE are specified, that both are specified.
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) Convienence 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.
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 null or is 0 or less, the process executor will not wait for the process to exit before returning the response.
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.
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	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	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	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) Sets the time to wait for the process to exit.
void	setWorkingDirectory(String value) Sets the working directory of the new process (known also as the current directory or the startup directory).

Methods inherited from class org.rhq.enterprise.communications.command.AbstractCommand

allowAnyParameter, convertParameters, getCommandType, getConfiguration, getParameterDefinition, getParameterDefinitions, getParameterValue, getParameterValues, getParameterValuesInternalMap, hasParameterValue, initializeMetadata, isCommandInResponse, removeParameterValue, removeParameterValues, setCommandInResponse, setParameterValue, setParameterValuesInternalMap, toString, toString

Methods inherited from class java.lang.Object

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

Field Detail

COMMAND_TYPE

public static final CommandType COMMAND_TYPE

command type constant identifying this command

PARAM_PROGRAM_TITLE

public static final ParameterDefinition PARAM_PROGRAM_TITLE

identifies the parameter whose value is a simple title for this start command configuration (may be used for output filename)

PARAM_PROGRAM_EXE

public static final ParameterDefinition PARAM_PROGRAM_EXE

identifies the parameter whose value is the name of the program to execute

PARAM_PROGRAM_DIR

public static final ParameterDefinition PARAM_PROGRAM_DIR

identifies the parameter whose value is the full path to the program's executable

PARAM_ARGS

public static final ParameterDefinition PARAM_ARGS

identifies the parameter whose value is an array of arguments to pass to the executable

PARAM_ENV

public static final ParameterDefinition PARAM_ENV

identifies the parameter whose value is an Properties object containing environment variable name/value pairs to give to the process

PARAM_WORKING_DIR

public static final ParameterDefinition PARAM_WORKING_DIR

identifies the parameter whose value is directory location to start the process in (the working directory).

PARAM_OUTPUT_DIR

public static final ParameterDefinition PARAM_OUTPUT_DIR

identifies the parameter whose value is the directory where the process's output log will be written

PARAM_OUTPUT_FILE

public static final ParameterDefinition PARAM_OUTPUT_FILE

identifies the parameter whose value is the filename (in the output directory) where the process's stdout/stderr output log will be written

PARAM_INPUT_DIR

public static final ParameterDefinition PARAM_INPUT_DIR

identifies the parameter whose value is the directory location of the file that contains data to be fed into the programs' stdin input stream

PARAM_INPUT_FILE

public static final ParameterDefinition PARAM_INPUT_FILE

identifies the parameter whose value is the file name that contains data to be fed into the programs' stdin input stream

PARAM_WAIT_FOR_EXIT

public static final ParameterDefinition PARAM_WAIT_FOR_EXIT

identifies the parameter whose value is the time to wait until the process has exited

PARAM_CAPTURE_OUTPUT

public static final ParameterDefinition PARAM_CAPTURE_OUTPUT

identifies the parameter whose value is the flag to determine if the started process's output should be dumped to the output file

PARAM_BACKUP_OUTPUT_FILE

public static final ParameterDefinition PARAM_BACKUP_OUTPUT_FILE

identifies the parameter whose value is the flag to determine whether to backup any previously existing output file; if false, it will be overwritten

Constructor Detail

StartCommand

public StartCommand()
             throws IllegalArgumentException,
                    InvalidParameterDefinitionException

Constructor for StartCommand.

Throws:

IllegalArgumentException

InvalidParameterDefinitionException

See Also:

AbstractCommand.AbstractCommand()

StartCommand

public StartCommand(Map<String,Object> commandParameters)
             throws IllegalArgumentException,
                    InvalidParameterDefinitionException

Constructor for StartCommand.

Throws:

IllegalArgumentException

InvalidParameterDefinitionException

See Also:

AbstractCommand.AbstractCommand(Map)

StartCommand

public StartCommand(Command commandToTransform)

Constructor for StartCommand.

See Also:

AbstractCommand.AbstractCommand(Command)

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").

Returns:

the title of the program

setProgramTitle

public void setProgramTitle(String value)

Sets 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").

Parameters:

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

getProgramExecutable

public String getProgramExecutable()

Returns the name of the program to execute. This is just the executable file name without any path information (for that information, see getProgramDirectory()).

Returns:

program executable name

setProgramExecutable

public void setProgramExecutable(String value)

Sets the name of the program to execute. This is just the executable file name without any path information (for setting that information, see setProgramDirectory(String)).

Parameters:

value - program executable name

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()).

Returns:

program executable directory location

setProgramDirectory

public void setProgramDirectory(String value)

Sets 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 setting that information, see getProgramExecutable()).

Parameters:

value - program executable directory location

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 InvalidParameterValueException,
                               IllegalArgumentException

Convienence 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:

InvalidParameterValueException - if an environment variable string doesn't conform to the format: name=value

IllegalArgumentException - if 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 (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.

Parameters:

value - the working directory path (may be null)

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).

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. If null, a directory will be assigned (typically the java.io.tmpdir directory).

Parameters:

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

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.

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. 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.

Parameters:

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

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.

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

Parameters:

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

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. 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.

Parameters:

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

getWaitForExit

public Long getWaitForExit()

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

Returns:

wait time in milliseconds

setWaitForExit

public void setWaitForExit(Long value)

Sets the time to wait for the process to exit.

Parameters:

value - wait time in milliseconds

See Also:

getWaitForExit()

isCaptureOutput

public Boolean isCaptureOutput()

If true, the started process' output will be captured and written to the output file. If false, no output file is created and the process' output is simply consumed and ignored.

Returns:

capture output flag

setCaptureOutput

public void setCaptureOutput(Boolean value)

Sets the flag to indicate if the process' output should be captured in the output file. If true, the started process' output will be captured and written to the output file. If false, no output file is created and the process' output is simply consumed and ignored.

Parameters:

value - capture output flag

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. 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.

Parameters:

value - the backup flag

checkParameterValidity

public void checkParameterValidity(boolean convertIfNecessary)
                            throws InvalidParameterValueException

Ensures that if either PARAM_INPUT_DIR or PARAM_INPUT_FILE are specified, that both are specified. In other words, you can't specify one without specifying the other.

Specified by:

checkParameterValidity in interface Command

Overrides:

checkParameterValidity in class AbstractCommand

Parameters:

convertIfNecessary - if true, then attempt to convert any invalid parameter values

Throws:

InvalidParameterValueException - if one or more parameters are invalid

See Also:

Command.checkParameterValidity(boolean)

buildCommandType

protected CommandType buildCommandType()

Description copied from class: AbstractCommand

Builds the command type of this command. It must not be null.

This method is called by the command's constructors.

Specified by:

buildCommandType in class AbstractCommand

Returns:

the command's type definition; must not be null

See Also:

AbstractCommand.buildCommandType()

buildParameterDefinitions

protected ParameterDefinition[] buildParameterDefinitions()

Description copied from class: AbstractCommand

Builds the set of parameter definitions that this command will use. Parameter definitions define what parameters this command accepts. Implementors must return one of the following:

• An array of one or more definitions if the command accepts required and/or optional parameters
• An empty array if the command does not accept any parameters (i.e. a no-arg command)
• null if the command accepts any and all parameters, regardless of name or type

This method is called by the command's constructors.

Specified by:

buildParameterDefinitions in class AbstractCommand

Returns:

an array of parameter definitions or null

See Also:

AbstractCommand.buildParameterDefinitions()