Package org.apache.commons.exec

Class DefaultExecutor

  • All Implemented Interfaces:
    Executor
    Direct Known Subclasses:
    DaemonExecutor
    public class DefaultExecutor
extends java.lang.Object
implements Executor
    The default class to start a subprocess. The implementation 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 = DefaultExecutor.builder().get();
 CommandLine cl = new CommandLine("ls -l");
 int exitValue = exec.execute(cl);

    • Field Detail

      • exceptionCaught

        private java.io.IOException exceptionCaught
        The first exception being caught to be thrown to the caller.

      • executeStreamHandler

        private ExecuteStreamHandler executeStreamHandler
        Taking care of output and error stream.

      • executorThread

        private java.lang.Thread executorThread
        Worker thread for asynchronous execution.

      • exitValues

        private int[] exitValues
        The exit values considered to be successful.

      • launcher

        private final CommandLauncher launcher
        Launches the command in a new process.

      • processDestroyer

        private ProcessDestroyer processDestroyer
        Optional cleanup of started processes.

      • threadFactory

        private final java.util.concurrent.ThreadFactory threadFactory
        The thread factory.

      • watchdog

        private ExecuteWatchdog watchdog
        Monitoring of long-running processes.

      • workingDirectory

        private java.nio.file.Path workingDirectory
        The working directory of the process.

    • Constructor Detail

      • DefaultExecutor

        @Deprecated
public DefaultExecutor()
        Deprecated.
        Use DefaultExecutor.Builder.get().
        Constructs a default PumpStreamHandler and sets the working directory of the subprocess to the current working directory. The PumpStreamHandler pumps the output of the subprocess into our System.out and System.err to avoid into our System.out and System.err to avoid a blocked or deadlocked subprocess (see Process).

    • Method Detail

      • builder

        public static DefaultExecutor.Builder<?> builder()
        Creates a new builder.
        Returns:
        a new builder.
        Since:
        1.4.0

      • checkWorkingDirectory

        private void checkWorkingDirectory()
                            throws java.io.IOException
        Throws:
        java.io.IOException

      • checkWorkingDirectory

        private void checkWorkingDirectory​(java.io.File directory)
                            throws java.io.IOException
        Throws:
        java.io.IOException

      • checkWorkingDirectory

        private void checkWorkingDirectory​(java.nio.file.Path directory)
                            throws java.io.IOException
        Throws:
        java.io.IOException

      • closeCatch

        private void closeCatch​(java.io.Closeable closeable)
        Closes the Closeable, remembering any exception.
        Parameters:
        closeable - the Closeable to close.

      • closeProcessStreams

        private void closeProcessStreams​(java.lang.Process process)
        Closes the streams belonging to the given Process.
        Parameters:
        process - the Process.

      • createThread

        protected java.lang.Thread createThread​(java.lang.Runnable runnable,
                                        java.lang.String name)
        Creates a thread waiting for the result of an asynchronous execution.
        Parameters:
        runnable - the runnable passed to the thread.
        name - the name of the thread.
        Returns:
        the thread

      • execute

        public int execute​(CommandLine command)
            throws ExecuteException,
                   java.io.IOException
        Description copied from interface: Executor
        Executes a command synchronously. The child process inherits all environment variables of the parent process.
        Specified by:
        execute in interface Executor
        Parameters:
        command - the command to execute.
        Returns:
        process exit value.
        Throws:
        ExecuteException - execution of subprocess failed or the subprocess returned an exit value indicating a failure Executor.setExitValue(int).
        java.io.IOException - If an I/O error occurs.
        See Also:
        Executor.execute(CommandLine)

      • execute

        public int execute​(CommandLine command,
                   java.util.Map<java.lang.String,​java.lang.String> environment)
            throws ExecuteException,
                   java.io.IOException
        Description copied from interface: Executor
        Executes a command synchronously.
        Specified by:
        execute in interface Executor
        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 an exit value indicating a failure Executor.setExitValue(int).
        java.io.IOException - If an I/O error occurs.
        See Also:
        Executor.execute(CommandLine, java.util.Map)

      • executeInternal

        private int executeInternal​(CommandLine command,
                            java.util.Map<java.lang.String,​java.lang.String> environment,
                            java.nio.file.Path workingDirectory,
                            ExecuteStreamHandler streams)
                     throws java.io.IOException
        Execute an internal process. If the executing thread is interrupted while waiting for the child process to return the child process will be killed.
        Parameters:
        command - the command to execute.
        environment - the execution environment.
        workingDirectory - the working directory.
        streams - process the streams (in, out, err) of the process.
        Returns:
        the exit code of the process.
        Throws:
        java.io.IOException - executing the process failed.

      • getExceptionCaught

        private java.io.IOException getExceptionCaught()
        Gets the first IOException being thrown.
        Returns:
        the first IOException being caught.

      • getExecutorThread

        protected java.lang.Thread getExecutorThread()
        Gets the worker thread being used for asynchronous execution.
        Returns:
        the worker thread.

      • getThreadFactory

        java.util.concurrent.ThreadFactory getThreadFactory()
        Gets the thread factory. Z
        Returns:
        the thread factory.

      • isFailure

        public boolean isFailure​(int exitValue)
        Description copied from interface: Executor
        Tests 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.
        Specified by:
        isFailure in interface Executor
        Parameters:
        exitValue - the exit value (return code) to be checked.
        Returns:
        true if exitValue signals a failure.
        See Also:
        Executor.isFailure(int)

      • launch

        protected java.lang.Process launch​(CommandLine command,
                                   java.util.Map<java.lang.String,​java.lang.String> env,
                                   java.io.File workingDirectory)
                            throws java.io.IOException
        Creates a process that runs a command.
        Parameters:
        command - the command to run.
        env - the environment for the command.
        workingDirectory - the working directory for the command.
        Returns:
        the process started.
        Throws:
        java.io.IOException - forwarded from the particular launcher used.

      • launch

        protected java.lang.Process launch​(CommandLine command,
                                   java.util.Map<java.lang.String,​java.lang.String> env,
                                   java.nio.file.Path workingDirectory)
                            throws java.io.IOException
        Creates a process that runs a command.
        Parameters:
        command - the command to run.
        env - the environment for the command.
        workingDirectory - the working directory for the command.
        Returns:
        the process started.
        Throws:
        java.io.IOException - forwarded from the particular launcher used.
        Since:
        1.5.0

      • setExceptionCaught

        private void setExceptionCaught​(java.io.IOException e)
        Sets the first IOException thrown.
        Parameters:
        e - the IOException.

      • setExitValues

        public void setExitValues​(int[] values)
        Description copied from interface: Executor
        Sets 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 Executor.isFailure(int)
        • null to indicate to skip checking of exit codes
        If an undefined exit value is returned by the process then Executor.execute(CommandLine) will throw an ExecuteException.
        Specified by:
        setExitValues in interface Executor
        Parameters:
        values - a list of the exit codes.
        See Also:
        Executor.setExitValues(int[])

      • setStreams

        private void setStreams​(ExecuteStreamHandler streams,
                        java.lang.Process process)
                 throws java.io.IOException
        Throws:
        java.io.IOException