Class RuntimeExec
java.lang.Process
, but
logs the system standard and error streams.
The bean can be configured to execute a command directly, or be given a map
of commands keyed by the os.name Java system property. In this map,
the default key that is used when no match is found is the
*
key.
Use the processDirectory
property to change the default location
from which the command executes. The process's environment can be configured using the
processProperties
property.
Commands may use placeholders, e.g.
find
-name
${filename}
The filename property will be substituted for any supplied value prior to
each execution of the command. Currently, no checks are made to get or check the
properties contained within the command string. It is up to the client code to
dynamically extract the properties required if the required properties are not
known up front.
Sometimes, a variable may contain several arguments. . In this case, the arguments need to be tokenized using a standard StringTokenizer. To force tokenization of a value, use:
SPLIT:${userArgs}
You should not use this just to split up arguments that are known to require tokenization
up front. The SPLIT: directive works for the entire argument and will not do anything
if it is not at the beginning of the argument. Do not use SPLIT: to break up arguments
that are fixed, so avoid doing this:
SPLIT:ls -lih
Instead, break the command up explicitly:
ls
-lih
Tokenization of quoted parameter values is handled by ExecParameterTokenizer
, which
describes the support in more detail.- Author:
- Derek Hulley
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic class
Object to carry the results of an execution to the caller.static class
Gobbles anInputStream
and writes it into aStringBuffer
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final String
the key to use when specifying a command for any other OS: * -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionexecute()
Executes the command using the default propertiesExecutes the statement that this instance was constructed with.Executes the statement that this instance was constructed with an optional timeout after which the command is asked toString[]
String[]
getCommand
(Map<String, String> properties) Get the command that will be executed post substitution.void
setCharset
(String charsetCode) Sets the assumed charset of OUT and ERR streams generated by the executed command.void
setCommand
(String[] command) Set the command to execute regardless of operating systemvoid
setCommandMap
(Map<String, String> commandsByOS) Deprecated.void
setCommandsAndArguments
(Map<String, String[]> commandsByOS) Supply a choice of commands to execute based on a mapping from the os.name system property to the command to execute.void
setDefaultProperties
(Map<String, String> defaultProperties) Set the default command-line properties to use when executing the command.void
setErrorCodes
(String errCodesStr) A comma or space separated list of values that, if returned by the executed command, indicate an error value.void
setProcessDirectory
(String processDirectory) Set the runtime location from which the command is executed.void
setProcessProperties
(Map<String, String> processProperties) Set additional runtime properties (environment properties) that will used by the executing process.void
setProcessProperty
(String name, String value) Adds a property to existed processProperties.void
setWaitForCompletion
(boolean waitForCompletion) Set whether to wait for completion of the command or not.toString()
-
Field Details
-
KEY_OS_DEFAULT
the key to use when specifying a command for any other OS: *- See Also:
-
-
Constructor Details
-
RuntimeExec
public RuntimeExec()Default constructor. Initialize this instance by setting individual properties.
-
-
Method Details
-
toString
-
setCommand
Set the command to execute regardless of operating system- Parameters:
command
- an array of strings representing the command (first entry) and arguments- Since:
- 3.0
-
setCharset
Sets the assumed charset of OUT and ERR streams generated by the executed command. This defaults to the system default charset:Charset.defaultCharset()
.- Parameters:
charsetCode
- a supported character set code- Throws:
UnsupportedCharsetException
- if the characterset code is not recognised by Java
-
setWaitForCompletion
public void setWaitForCompletion(boolean waitForCompletion) Set whether to wait for completion of the command or not. If there is no wait for completion, then the return value of out and err buffers cannot be relied upon as the command may still be in progress. Failure is therefore not possible unless the calling thread waits for execution.- Parameters:
waitForCompletion
- true (default) is to wait for the command to exit, or false to just return an exit code of 0 and whatever output is available at that point.- Since:
- 2.1
-
setCommandsAndArguments
Supply a choice of commands to execute based on a mapping from the os.name system property to the command to execute. The*
key can be used to get a command where there is not direct match to the operating system key.Each command is an array of strings, the first of which represents the command and all subsequent entries in the array represent the arguments. All elements of the array will be checked for the presence of any substitution parameters (e.g. '{dir}'). The parameters can be set using the
defaults
or by passing the substitution values into theexecute(Map)
command.If parameters passed may be multiple arguments, or if the values provided in the map are themselves collections of arguments (not recommended), then prefix the value with SPLIT: to ensure that the value is tokenized before being passed to the command. Any values that are not split, will be passed to the command as single arguments. For example:
'SPLIT: dir . ..' becomes 'dir', '.' and '..'.
'SPLIT: dir ${path}' (if path is '. ..') becomes 'dir', '.' and '..'.
The splitting occurs post-subtitution. Where the arguments are known, it is advisable to avoid SPLIT:.- Parameters:
commandsByOS
- a map of command string arrays, keyed by operating system names- Since:
- 3.0
- See Also:
-
setCommandMap
Deprecated.Supply a choice of commands to execute based on a mapping from the os.name system property to the command to execute. The*
key can be used to get a command where there is not direct match to the operating system key.- Parameters:
commandsByOS
- a map of command string keyed by operating system names
-
setDefaultProperties
Set the default command-line properties to use when executing the command. These are properties that substitute variables defined in the command string itself. Properties supplied during execution will overwrite the default properties.null
properties will be treated as an empty string for substitution purposes.- Parameters:
defaultProperties
- property values
-
setProcessProperties
Set additional runtime properties (environment properties) that will used by the executing process.Any keys or properties that start and end with ${...} will be removed on the assumption that these are unset properties. null values are translated to empty strings. All keys and values are trimmed of leading and trailing whitespace.
- Parameters:
processProperties
- Runtime process properties- See Also:
-
setProcessProperty
Adds a property to existed processProperties. Property should not be null or empty. If property with the same value already exists then no change is made. If property exists with a different value then old value is replaced with the new one.- Parameters:
name
- - property namevalue
- - property value
-
setProcessDirectory
Set the runtime location from which the command is executed.If the value is an unsubsititued variable (${...}) then it is ignored. If the location is not visible at the time of setting, a warning is issued only.
- Parameters:
processDirectory
- the runtime location from which to execute the command
-
setErrorCodes
A comma or space separated list of values that, if returned by the executed command, indicate an error value. This defaults to "1, 2".- Parameters:
errCodesStr
- the error codes for the execution
-
execute
Executes the command using the default properties- See Also:
-
execute
Executes the statement that this instance was constructed with.- Parameters:
properties
- the properties that the command might be executed with.null
properties will be treated as an empty string for substitution purposes.- Returns:
- Returns the full execution results
-
execute
Executes the statement that this instance was constructed with an optional timeout after which the command is asked to- Parameters:
properties
- the properties that the command might be executed with.null
properties will be treated as an empty string for substitution purposes.timeoutMs
- a timeout after whichProcess.destroy()
is called. ignored if less than or equal to zero. Note this method does not guarantee to terminate the process (it is not a kill -9).- Returns:
- Returns the full execution results
-
getCommand
- Returns:
- Returns the command that will be executed if no additional properties were to be supplied
-
getCommand
Get the command that will be executed post substitution.null
properties will be treated as an empty string for substitution purposes.- Parameters:
properties
- the properties that the command might be executed with- Returns:
- Returns the command that will be executed should the additional properties be supplied
-
setCommandsAndArguments(Map)