Package org.apache.commons.exec

Interface Executor

  • All Known Implementing Classes:
    DaemonExecutor, DefaultExecutor
    public interface Executor
    The main abstraction to start an external process. The interface allows to
    • set a current working directory for the subprocess
    • provide a set of environment variables passed to the subprocess
    • capture the subprocess output of stdout and stderr using an ExecuteStreamHandler
    • kill long-running processes using an ExecuteWatchdog
    • define a set of expected exit values
    • terminate any started processes when the main process is terminating using a ProcessDestroyer
    The following example shows the basic usage: 
     Executor exec = new DefaultExecutor();
 CommandLine cl = new CommandLine("ls -l");
 int exitvalue = exec.execute(cl);

    • Field Detail

      • INVALID_EXITVALUE

        static final int INVALID_EXITVALUE
        Invalid exit code.
        See Also:
        Constant Field Values

    • Method Detail

      • setExitValue

        void setExitValue​(int value)
        Define the exitValue of the process to be considered successful. If a different exit value is returned by the process then execute(CommandLine) will throw an ExecuteException
        Parameters:
        value - the exit code representing successful execution

      • setExitValues

        void setExitValues​(int[] values)
        Define a list of exitValue of the process to be considered successful. The caller can pass one of the following values
        • an array of exit values to be considered successful
        • an empty array for auto-detect of successful exit codes relying on isFailure(int)
        • null to indicate to skip checking of exit codes
        If an undefined exit value is returned by the process then execute(CommandLine) will throw an ExecuteException.
        Parameters:
        values - a list of the exit codes

      • isFailure

        boolean isFailure​(int exitValue)
        Checks whether exitValue signals a failure. If no exit values are set than the default conventions of the OS is used. e.g. most OS regard an exit code of '0' as successful execution and everything else as failure.
        Parameters:
        exitValue - the exit value (return code) to be checked
        Returns:
        true if exitValue signals a failure

      • getStreamHandler

        ExecuteStreamHandler getStreamHandler()
        Get the StreamHandler used for providing input and retrieving the output.
        Returns:
        the StreamHandler

      • setStreamHandler

        void setStreamHandler​(ExecuteStreamHandler streamHandler)
        Set a custom the StreamHandler used for providing input and retrieving the output. If you don't provide a proper stream handler the executed process might block when writing to stdout and/or stderr (see Process).
        Parameters:
        streamHandler - the stream handler

      • getWatchdog

        ExecuteWatchdog getWatchdog()
        Get the watchdog used to kill of processes running, typically, too long time.
        Returns:
        the watchdog

      • setWatchdog

        void setWatchdog​(ExecuteWatchdog watchDog)
        Set the watchdog used to kill of processes running, typically, too long time.
        Parameters:
        watchDog - the watchdog

      • getProcessDestroyer

        ProcessDestroyer getProcessDestroyer()
        Set the handler for cleanup of started processes if the main process is going to terminate.
        Returns:
        the ProcessDestroyer

      • setProcessDestroyer

        void setProcessDestroyer​(ProcessDestroyer processDestroyer)
        Get the handler for cleanup of started processes if the main process is going to terminate.
        Parameters:
        processDestroyer - the ProcessDestroyer

      • getWorkingDirectory

        java.io.File getWorkingDirectory()
        Get the working directory of the created process.
        Returns:
        the working directory

      • setWorkingDirectory

        void setWorkingDirectory​(java.io.File dir)
        Set the working directory of the created process. The working directory must exist when you start the process.
        Parameters:
        dir - the working directory

      • execute

        int execute​(CommandLine command)
     throws ExecuteException,
            java.io.IOException
        Methods for starting synchronous execution. The child process inherits all environment variables of the parent process.
        Parameters:
        command - the command to execute
        Returns:
        process exit value
        Throws:
        ExecuteException - execution of subprocess failed or the subprocess returned a exit value indicating a failure setExitValue(int).
        java.io.IOException

      • execute

        int execute​(CommandLine command,
            java.util.Map<java.lang.String,​java.lang.String> environment)
     throws ExecuteException,
            java.io.IOException
        Methods for starting synchronous execution.
        Parameters:
        command - the command to execute
        environment - The environment for the new process. If null, the environment of the current process is used.
        Returns:
        process exit value
        Throws:
        ExecuteException - execution of subprocess failed or the subprocess returned a exit value indicating a failure setExitValue(int).
        java.io.IOException

      • execute

        void execute​(CommandLine command,
             ExecuteResultHandler handler)
      throws ExecuteException,
             java.io.IOException
        Methods for starting asynchronous execution. The child process inherits all environment variables of the parent process. Result provided to callback handler.
        Parameters:
        command - the command to execute
        handler - capture process termination and exit code
        Throws:
        ExecuteException - execution of subprocess failed
        java.io.IOException

      • execute

        void execute​(CommandLine command,
             java.util.Map<java.lang.String,​java.lang.String> environment,
             ExecuteResultHandler handler)
      throws ExecuteException,
             java.io.IOException
        Methods for starting asynchronous execution. The child process inherits all environment variables of the parent process. Result provided to callback handler.
        Parameters:
        command - the command to execute
        environment - The environment for the new process. If null, the environment of the current process is used.
        handler - capture process termination and exit code
        Throws:
        ExecuteException - execution of subprocess failed
        java.io.IOException