Class RuntimeExec

java.lang.Object
org.alfresco.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
  • Field Details

    • KEY_OS_DEFAULT

      public static final String 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

      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:
    • 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:
    • 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()
      Executes the command using the default properties
      See Also:
    • 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