StartCommand (RHQ Enterprise Agent-Server Communications Layer 4.10.0 API)

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

Fields
Modifier and Type	Field and Description
`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

Constructors
Constructor and Description
`StartCommand()` Constructor for `StartCommand`.
`StartCommand(Command commandToTransform)` Constructor for `StartCommand`.
`StartCommand(Map<String,Object> commandParameters)` Constructor for `StartCommand`.

Method Summary

Methods
Modifier and Type	Method and Description
`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()

Class StartCommand

Field Summary

Constructor Summary

Method Summary

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

Methods inherited from class java.lang.Object

Field Detail

COMMAND_TYPE

PARAM_PROGRAM_TITLE

PARAM_PROGRAM_EXE

PARAM_PROGRAM_DIR

PARAM_ARGS

PARAM_ENV

PARAM_WORKING_DIR

PARAM_OUTPUT_DIR

PARAM_OUTPUT_FILE

PARAM_INPUT_DIR

PARAM_INPUT_FILE

PARAM_WAIT_FOR_EXIT

PARAM_CAPTURE_OUTPUT

PARAM_BACKUP_OUTPUT_FILE

Constructor Detail

StartCommand

StartCommand

StartCommand

Method Detail

getProgramTitle

setProgramTitle

getProgramExecutable

setProgramExecutable

getProgramDirectory

setProgramDirectory

getArguments

setArguments

getEnvironment

getEnvironment

setEnvironment

setEnvironment

getWorkingDirectory

setWorkingDirectory

getOutputDirectory

setOutputDirectory

getOutputFile

setOutputFile

getInputDirectory

setInputDirectory

getInputFile

setInputFile

getWaitForExit

setWaitForExit

isCaptureOutput

setCaptureOutput

isBackupOutputFile

setBackupOutputFile

checkParameterValidity

buildCommandType

buildParameterDefinitions