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