org.gytheio.util.exec

Class RuntimeExec

java.lang.Object

org.gytheio.util.exec.RuntimeExec

public class RuntimeExec
extends Object

This acts as a session similar to the 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 Classes

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
static class	RuntimeExec.InputStreamReaderThreadFactory Class for instantiating InputStreamReaderThreads

Field Summary

Fields

Modifier and Type	Field and Description
static String	KEY_OS_DEFAULT the key to use when specifying a command for any other OS: *

Constructor Summary

Constructors

Constructor and Description
RuntimeExec() Default constructor.

Method Summary

Methods

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
RuntimeExec.ExecutionResult	execute(Map<String,String> properties, RuntimeExec.InputStreamReaderThreadFactory stdOutGobblerFactory, RuntimeExec.InputStreamReaderThreadFactory stdErrGobblerFactory, 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. Use setCommandsAndArguments(Map)
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	setDefaultInputStreamReaderThreadFactory(RuntimeExec.InputStreamReaderThreadFactory defaultInputStreamReaderThreadFactory)
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()

Methods inherited from class java.lang.Object

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

Field Detail

KEY_OS_DEFAULT

public static final String KEY_OS_DEFAULT

the key to use when specifying a command for any other OS: *

See Also:

Constant Field Values

Constructor Detail

RuntimeExec

public RuntimeExec()

Default constructor. Initialize this instance by setting individual properties.

Method Detail

toString

public String toString()

Overrides:

toString in class Object

setCommand

public void setCommand(String[] command)

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

public void setCharset(String charsetCode)

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

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

Parameters:

commandsByOS - a map of command string arrays, keyed by operating system names

Since:

3.0

See Also:

setDefaultProperties(Map)

setCommandMap

public void setCommandMap(Map<String,String> commandsByOS)

Deprecated. Use setCommandsAndArguments(Map)

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

public void setDefaultProperties(Map<String,String> defaultProperties)

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

public void setProcessProperties(Map<String,String> processProperties)

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:

Runtime.exec(String, String[], java.io.File)

setProcessProperty

public void setProcessProperty(String name,
                      String value)

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 name

value - - property value

setProcessDirectory

public void setProcessDirectory(String processDirectory)

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

public void setErrorCodes(String errCodesStr)

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

setDefaultInputStreamReaderThreadFactory

public void setDefaultInputStreamReaderThreadFactory(RuntimeExec.InputStreamReaderThreadFactory defaultInputStreamReaderThreadFactory)

execute

public RuntimeExec.ExecutionResult execute()

Executes the command using the default properties

See Also:

execute(Map)

execute

public RuntimeExec.ExecutionResult execute(Map<String,String> properties)

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

public 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

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

Returns:

Returns the full execution results

execute

public RuntimeExec.ExecutionResult execute(Map<String,String> properties,
                                  RuntimeExec.InputStreamReaderThreadFactory stdOutGobblerFactory,
                                  RuntimeExec.InputStreamReaderThreadFactory stdErrGobblerFactory,
                                  long timeoutMs)

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

stdOutGobblerFactory - the object used to create the output input stream reader If null the defaultInputStreamReaderThreadFactory will be used

stdErrGobblerFactory - the object used to create the error input stream reader If null the defaultInputStreamReaderThreadFactory will be used

Returns:

Returns the full execution results

getCommand

public String[] getCommand()

Returns:

Returns the command that will be executed if no additional properties were to be supplied

getCommand

public String[] getCommand(Map<String,String> properties)

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