Package com.norconex.commons.lang.exec

# Class SystemCommand

java.lang.Object
com.norconex.commons.lang.exec.SystemCommand

public class SystemCommand extends Object
Represents a program to be executed by the underlying system (on the "command line"). This class attempts to be system-independent, which means given an executable path should be sufficient to run programs on any systems (e.g. it handles prefixing an executable with OS specific commands as well as preventing process hanging on some OS when there is nowhere to display the output).

Since:
  1.13.0 (previously part of now deprecated JEF API)

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SystemCommand(File workdir, String... command)`
  Creates a command.
  `SystemCommand(String... command)`
  Creates a command for which the execution will be in the working directory of the current process.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `abort()`
  Aborts the running command.
  `void`
  `addErrorListener(InputStreamListener listener)`
  Adds an error (STDERR) listener to this system command.
  `void`
  `addOutputListener(InputStreamListener listener)`
  Adds an output (STDOUT) listener to this system command.
  `static String[]`
  `escape(String... command)`
  Escapes spaces in each parts of the command as well as special characters in some operating systems, if they are not already escaped.
  `static void`
  `escape(List<String> command)`
  Escapes spaces in each parts of the command as well as special characters in some operating systems, if they are not already escaped.
  `int`
  `execute()`
  Executes this system command and returns only when the underlying process stopped running.
  `int`
  `execute(boolean runInBackground)`
  Executes this system command.
  `int`
  `execute(InputStream input)`
  Executes this system command with the given input and returns only when the underlying process stopped running.
  `int`
  `execute(InputStream input, boolean runInBackground)`
  Executes this system command with the given input.
  `String[]`
  `getCommand()`
  Gets the command to be run.
  `Map<String,String>`
  `getEnvironmentVariables()`
  Gets environment variables.
  `List<InputStreamListener>`
  `getErrorListeners()`
  Gets an unmodifiable list of error (STDERR) listeners.
  `List<InputStreamListener>`
  `getOutputListeners()`
  Gets an unmodifiable list of output (STDOUT) listeners.
  `File`
  `getWorkdir()`
  Gets the command working directory.
  `boolean`
  `isRunning()`
  Returns whether the command is currently running.
  `void`
  `removeErrorListener(InputStreamListener listener)`
  Removes an error (STDERR) listener.
  `void`
  `removeOutputListener(InputStreamListener listener)`
  Removes an output (STDOUT) listener.
  `void`
  `setEnvironmentVariables(Map<String,String> environmentVariables)`
  Sets environment variables.
  `String`
  `toString()`
  Returns the command to be executed.

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### SystemCommand

    public SystemCommand(String... command)
    Creates a command for which the execution will be in the working directory of the current process. If more than one command values are passed, the first element of the array is the command and subsequent elements are arguments. If your command or arguments contain spaces, they will be escaped according to your operating sytem (surrounding with double-quotes on Windows and backslash on other operating systems).
    Parameters:
      `command` - the command to run

  - ### SystemCommand

    public SystemCommand(File workdir, String... command)
    Creates a command. If more than one command values are passed, the first element of the array is the command and subsequent elements are arguments. If your command or arguments contain spaces, they will be escaped according to your operating sytem (surrounding with double-quotes on Windows and backslash on other operating systems).
    Parameters:
      `workdir` - command working directory.
      `command` - the command to run

- ## Method Details

  - ### getCommand

    public String[] getCommand()
    Gets the command to be run.
    Returns:
      the command

  - ### getWorkdir

    public File getWorkdir()
    Gets the command working directory.
    Returns:
      command working directory.

  - ### addErrorListener

    public void addErrorListener(InputStreamListener listener)
    Adds an error (STDERR) listener to this system command.
    Parameters:
      `listener` - command error listener

  - ### removeErrorListener

    public void removeErrorListener(InputStreamListener listener)
    Removes an error (STDERR) listener.
    Parameters:
      `listener` - command error listener

  - ### getErrorListeners

    public List<InputStreamListener> getErrorListeners()
    Gets an unmodifiable list of error (STDERR) listeners.
    Returns:
      error listeners
    Since:
      3.0.0

  - ### addOutputListener

    public void addOutputListener(InputStreamListener listener)
    Adds an output (STDOUT) listener to this system command.
    Parameters:
      `listener` - command output listener

  - ### removeOutputListener

    public void removeOutputListener(InputStreamListener listener)
    Removes an output (STDOUT) listener.
    Parameters:
      `listener` - command output listener

  - ### getOutputListeners

    public List<InputStreamListener> getOutputListeners()
    Gets an unmodifiable list of output (STDOUT) listeners.
    Returns:
      output listeners
    Since:
      3.0.0

  - ### getEnvironmentVariables

    public Map<String,String> getEnvironmentVariables()
    Gets environment variables.
    Returns:
      environment variables

  - ### setEnvironmentVariables

    public void setEnvironmentVariables(Map<String,String> environmentVariables)
    Sets environment variables. Set to `null` (default) for the command to inherit the environment of the current process.
    Parameters:
      `environmentVariables` - environment variables

  - ### isRunning

    public boolean isRunning()
    Returns whether the command is currently running.
    Returns:
      `true` if running

  - ### abort

    public void abort()
    Aborts the running command. If the command is not currently running, aborting it will have no effect.

  - ### execute

    public int execute() throws SystemCommandException
    Executes this system command and returns only when the underlying process stopped running.
    Returns:
      process exit value
    Throws:
      `SystemCommandException` - problem executing command

  - ### execute

    public int execute(boolean runInBackground) throws SystemCommandException
    Executes this system command. When run in the background, this method does not wait for the process to complete before returning. In such case the status code should always be 0 unless it terminated abruptly (may not reflect the process termination status). When NOT run in the background, this method waits and returns only when the underlying process stopped running. Alternatively, to run a command asynchronously, you can wrap it in its own thread.
    Parameters:
      `runInBackground` - `true` to runs the system command in background.
    Returns:
      process exit value
    Throws:
      `SystemCommandException` - problem executing command
      `IllegalStateException` - when command is already running

  - ### execute

    public int execute(InputStream input) throws SystemCommandException
    Executes this system command with the given input and returns only when the underlying process stopped running.
    Parameters:
      `input` - process input (fed to STDIN)
    Returns:
      process exit value
    Throws:
      `SystemCommandException` - problem executing command

  - ### execute

    public int execute(InputStream input, boolean runInBackground) throws SystemCommandException
    Executes this system command with the given input. When run in the background, this method does not wait for the process to complete before returning. In such case the status code should always be 0 unless it terminated abruptly (may not reflect the process termination status). When NOT run in the background, this method waits and returns only when the underlying process stopped running. Alternatively, to run a command asynchronously, you can wrap it in its own thread.
    Parameters:
      `input` - process input (fed to STDIN)
      `runInBackground` - `true` to runs the system command in background.
    Returns:
      process exit value
    Throws:
      `SystemCommandException` - problem executing command
      `IllegalStateException` - when command is already running

  - ### toString

    public String toString()
    Returns the command to be executed.
    Overrides:
      `toString` in class `Object`

  - ### escape

    public static String[] escape(String... command)
    Escapes spaces in each parts of the command as well as special characters in some operating systems, if they are not already escaped. Escapes according to operating system escape mechanism. If there is only one part to the command (size-one array), it can be the entire command with arguments passed as one string. In such case, there are little ways to tell if spaces are part of an argument or separates two arguments, so no escaping is performed.
    Parameters:
      `command` - the command to escape.
    Returns:
      escaped command

  - ### escape

    public static void escape(List<String> command)
    Escapes spaces in each parts of the command as well as special characters in some operating systems, if they are not already escaped. Escapes according to operating system escape mechanism. If there is only one part to the command (size-one list), it can be the entire command with arguments passed as one string. In such case, there are little ways to tell if spaces are part of an argument or separates two arguments, so no escaping is performed.
    Parameters:
      `command` - the command to escape.