    001    /*
    002     * Licensed to the Apache Software Foundation (ASF) under one or more
    003     *  contributor license agreements.  See the NOTICE file distributed with
    004     *  this work for additional information regarding copyright ownership.
    005     *  The ASF licenses this file to You under the Apache License, Version 2.0
    006     *  (the "License"); you may not use this file except in compliance with
    007     *  the License.  You may obtain a copy of the License at
    008     *
    009     *      http://www.apache.org/licenses/LICENSE-2.0
    010     *
    011     *  Unless required by applicable law or agreed to in writing, software
    012     *  distributed under the License is distributed on an "AS IS" BASIS,
    013     *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014     *  See the License for the specific language governing permissions and
    015     *  limitations under the License.
    016     *
    017     */
    018
    019    package org.apache.commons.exec;
    020
    021    import java.io.File;
    022    import java.io.IOException;
    023    import java.util.Map;
    024
    025    /**
    026     * The main abstraction to start an external process.
    027     *
    028     * The interface allows to
    029     * <ul>
    030     *  <li>set a current working directory for the subprocess</li>
    031     *  <li>provide a set of environment variables passed to the subprocess</li>
    032     *  <li>capture the subprocess output of stdout and stderr using an ExecuteStreamHandler</li>
    033     *  <li>kill long-running processes using an ExecuteWatchdog</li>
    034     *  <li>define a set of expected exit values</li>
    035     *  <li>terminate any started processes when the main process is terminating using a ProcessDestroyer</li>
    036     * </ul>
    037     *
    038     * The following example shows the basic usage:
    039     *
    040     * <pre>
    041     * Executor exec = new DefaultExecutor();
    042     * CommandLine cl = new CommandLine("ls -l");
    043     * int exitvalue = exec.execute(cl);
    044     * </pre>
    045     */
    046
    047    public interface Executor {
    048
    049        /** Invalid exit code. */
    050        int INVALID_EXITVALUE = 0xdeadbeef;
    051
    052        /**
    053         * Define the exit code of the process to considered
    054         * successful.
    055         *
    056         * @param value the exit code representing successful execution
    057         */
    058        void setExitValue(final int value);
    059
    060        /**
    061         * Define the exit code of the process to considered
    062         * successful. The caller can pass one of the following values
    063         * <ul>
    064         *  <li>an array of exit values to be considered successful</li>
    065         *  <li>an empty array for auto-detect of successful exit codes</li>
    066         *  <li>null to indicate to skip checking of exit codes</li>
    067         * </ul>
    068         *
    069         * @param values a list of the exit codes
    070         */
    071        void setExitValues(final int[] values);
    072
    073        /**
    074         * Checks whether <code>exitValue</code> signals a failure. If no
    075         * exit values are set than the default conventions of the OS is
    076         * used. e.g. most OS regard an exit code of '0' as successful
    077         * execution and everything else as failure.
    078         *
    079         * @param exitValue the exit value (return code) to be checked
    080         * @return <code>true</code> if <code>exitValue</code> signals a failure
    081         */
    082        boolean isFailure(final int exitValue);
    083
    084        /**
    085         * Get the StreamHandler used for providing input and
    086         * retriving the output.
    087         *
    088         * @return the StreamHandler
    089         */
    090        ExecuteStreamHandler getStreamHandler();
    091
    092        /**
    093         * Set the StreamHandler used for providing input and
    094         * retriving the output.
    095         *
    096         * @param streamHandler the StreamHandler
    097         */
    098
    099        void setStreamHandler(ExecuteStreamHandler streamHandler);
    100
    101        /**
    102         * Get the watchdog used to kill of processes running,
    103         * typically, too long time.
    104         *
    105         * @return the watchdog
    106         */
    107        ExecuteWatchdog getWatchdog();
    108
    109        /**
    110         * Set the watchdog used to kill of processes running,
    111         * typically, too long time.
    112         *
    113         * @param watchDog the watchdog
    114         */
    115        void setWatchdog(ExecuteWatchdog watchDog);
    116
    117        /**
    118         * Set the handler for cleanup of started processes if the main process
    119         * is going to terminate.
    120         *
    121         * @return the ProcessDestroyer
    122         */
    123        ProcessDestroyer getProcessDestroyer();
    124
    125        /**
    126         * Get the handler for cleanup of started processes if the main process
    127         * is going to terminate.
    128         *
    129         * @param processDestroyer the ProcessDestroyer
    130         */
    131        void setProcessDestroyer(ProcessDestroyer processDestroyer);
    132
    133        /**
    134         * Get the working directory of the created process.
    135         *
    136         * @return the working directory
    137         */
    138        File getWorkingDirectory();
    139
    140        /**
    141         * Set the working directory of the created process. The
    142         * working directory must exist when you start the process.
    143         *
    144         * @param dir the working directory
    145         */
    146        void setWorkingDirectory(File dir);
    147
    148        /**
    149         * Methods for starting synchronous execution. The child process inherits
    150         * all environment variables of the parent process.
    151         *
    152         * @param command the command to execute
    153         * @return process exit value
    154         * @throws ExecuteException execution of subprocess failed
    155         */
    156        int execute(CommandLine command)
    157            throws ExecuteException, IOException;
    158
    159        /**
    160         * Methods for starting synchronous execution.
    161         *
    162         * @param command the command to execute
    163         * @param environment The environment for the new process. If null, the
    164         *          environment of the current process is used.
    165         * @return process exit value
    166         * @throws ExecuteException execution of subprocess failed
    167         */
    168        int execute(CommandLine command, Map environment)
    169            throws ExecuteException, IOException;
    170
    171        /**
    172         * Methods for starting asynchronous execution. The child process inherits
    173         * all environment variables of the parent process. Result provided to
    174         * callback handler.
    175         *
    176         * @param command the command to execute
    177         * @param handler capture process termination and exit code
    178         * @throws ExecuteException execution of subprocess failed
    179         */
    180        void execute(CommandLine command, ExecuteResultHandler handler)
    181            throws ExecuteException, IOException;
    182
    183        /**
    184         * Methods for starting asynchronous execution. The child process inherits
    185         * all environment variables of the parent process. Result provided to
    186         * callback handler.
    187         *
    188         * @param command the command to execute
    189         * @param environment The environment for the new process. If null, the
    190         *          environment of the current process is used.
    191         * @param handler capture process termination and exit code
    192         * @throws ExecuteException execution of subprocess failed
    193         */
    194        void execute(CommandLine command, Map environment, ExecuteResultHandler handler)
    195            throws ExecuteException, IOException;
    196    }