Class 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
    • 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

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