public class RuntimeExec extends Object
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.Modifier and Type | Class and Description |
---|---|
static class |
RuntimeExec.ExecutionResult
Object to carry the results of an execution to the caller.
|
static class |
RuntimeExec.InputStreamReaderThread
Gobbles an
InputStream and writes it into a
StringBuffer |
Modifier and Type | Field and Description |
---|---|
static String |
KEY_OS_DEFAULT
the key to use when specifying a command for any other OS: *
|
Constructor and Description |
---|
RuntimeExec()
Default constructor.
|
Modifier and Type | Method and Description |
---|---|
RuntimeExec.ExecutionResult |
execute()
Executes the command using the default properties
|
RuntimeExec.ExecutionResult |
execute(Map<String,String> properties)
Executes the statement that this instance was constructed with.
|
RuntimeExec.ExecutionResult |
execute(Map<String,String> properties,
long timeoutMs)
Executes the statement that this instance was constructed with an optional
timeout after which the command is asked to
|
String[] |
getCommand() |
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 system
|
void |
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.
|
String |
toString() |
public static final String KEY_OS_DEFAULT
public RuntimeExec()
public void setCommand(String[] command)
command
- an array of strings representing the command (first entry) and argumentspublic void setCharset(String charsetCode)
Charset.defaultCharset()
.charsetCode
- a supported character set codeUnsupportedCharsetException
- if the characterset code is not recognised by Javapublic void setWaitForCompletion(boolean waitForCompletion)
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.public void setCommandsAndArguments(Map<String,String[]> commandsByOS)
*
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 the
execute(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:.
commandsByOS
- a map of command string arrays, keyed by operating system namessetDefaultProperties(Map)
public void setCommandMap(Map<String,String> commandsByOS)
setCommandsAndArguments(Map)
*
key can be used
to get a command where there is not direct match to the operating system key.commandsByOS
- a map of command string keyed by operating system namespublic void setDefaultProperties(Map<String,String> defaultProperties)
null
properties will be treated as an empty string for substitution
purposes.
defaultProperties
- property valuespublic void setProcessProperties(Map<String,String> processProperties)
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.
processProperties
- Runtime process propertiesRuntime.exec(String, String[], java.io.File)
public void setProcessProperty(String name, String value)
name
- - property namevalue
- - property valuepublic void setProcessDirectory(String processDirectory)
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.
processDirectory
- the runtime location from which to execute the commandpublic void setErrorCodes(String errCodesStr)
errCodesStr
- the error codes for the executionpublic RuntimeExec.ExecutionResult execute()
execute(Map)
public RuntimeExec.ExecutionResult execute(Map<String,String> properties)
properties
- the properties that the command might be executed with.
null
properties will be treated as an empty string for substitution
purposes.public RuntimeExec.ExecutionResult execute(Map<String,String> properties, long timeoutMs)
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 which Process.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).public String[] getCommand()
public String[] getCommand(Map<String,String> properties)
null
properties will be treated as an empty string for substitution
purposes.
properties
- the properties that the command might be executed withCopyright © 2005–2020 Alfresco Software. All rights reserved.