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
018package org.apache.commons.exec;
019
020import java.io.File;
021import java.io.IOException;
022import java.util.Map;
023
024/**
025 * The main abstraction to start an external process.
026 *
027 * The interface allows to:
028 * <ul>
029 * <li>set a current working directory for the subprocess</li>
030 * <li>provide a set of environment variables passed to the subprocess</li>
031 * <li>capture the subprocess output of stdout and stderr using an ExecuteStreamHandler</li>
032 * <li>kill long-running processes using an ExecuteWatchdog</li>
033 * <li>define a set of expected exit values</li>
034 * <li>terminate any started processes when the main process is terminating using a ProcessDestroyer</li>
035 * </ul>
036 * <p>
037 * The following example shows the basic usage:
038 * </p>
039 *
040 * <pre>
041 * Executor exec = DefaultExecutor.builder().get();
042 * CommandLine cl = new CommandLine("ls -l");
043 * int exitvalue = exec.execute(cl);
044 * </pre>
045 */
046
047public interface Executor {
048
049    /** Invalid exit code. */
050    int INVALID_EXITVALUE = 0xdeadbeef;
051
052    /**
053     * Executes a command synchronously. The child process inherits all environment variables of the parent process.
054     *
055     * @param command the command to execute.
056     * @return process exit value.
057     * @throws ExecuteException execution of subprocess failed or the subprocess returned a exit value indicating a failure {@link Executor#setExitValue(int)}.
058     * @throws IOException      If an I/O error occurs.
059     */
060    int execute(CommandLine command) throws ExecuteException, IOException;
061
062    /**
063     * Executes a command asynchronously. The child process inherits all environment variables of the parent process. Result provided to callback handler.
064     *
065     * @param command the command to execute.
066     * @param handler capture process termination and exit code.
067     * @throws ExecuteException execution of subprocess failed.
068     * @throws IOException      If an I/O error occurs.
069     */
070    void execute(CommandLine command, ExecuteResultHandler handler) throws ExecuteException, IOException;
071
072    /**
073     * Executes a command synchronously.
074     *
075     * @param command     the command to execute.
076     * @param environment The environment for the new process. If null, the environment of the current process is used.
077     * @return process exit value.
078     * @throws ExecuteException execution of subprocess failed or the subprocess returned a exit value indicating a failure {@link Executor#setExitValue(int)}.
079     * @throws IOException      If an I/O error occurs.
080     */
081    int execute(CommandLine command, Map<String, String> environment) throws ExecuteException, IOException;
082
083    /**
084     * Executes a command asynchronously. The child process inherits all environment variables of the parent process. Result provided to callback handler.
085     *
086     * @param command     the command to execute.
087     * @param environment The environment for the new process. If null, the environment of the current process is used.
088     * @param handler     capture process termination and exit code.
089     * @throws ExecuteException execution of subprocess failed.
090     * @throws IOException      If an I/O error occurs.
091     */
092    void execute(CommandLine command, Map<String, String> environment, ExecuteResultHandler handler) throws ExecuteException, IOException;
093
094    /**
095     * Sets the handler for cleanup of started processes if the main process is going to terminate.
096     *
097     * @return the ProcessDestroyer.
098     */
099    ProcessDestroyer getProcessDestroyer();
100
101    /**
102     * Gets the StreamHandler used for providing input and retrieving the output.
103     *
104     * @return the StreamHandler.
105     */
106    ExecuteStreamHandler getStreamHandler();
107
108    /**
109     * Gets the watchdog used to kill of processes running, typically, too long time.
110     *
111     * @return the watchdog.
112     */
113    ExecuteWatchdog getWatchdog();
114
115    /**
116     * Gets the working directory of the created process.
117     *
118     * @return the working directory.
119     */
120    File getWorkingDirectory();
121
122    /**
123     * Tests whether {@code 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
124     * code of '0' as successful execution and everything else as failure.
125     *
126     * @param exitValue the exit value (return code) to be checked.
127     * @return {@code true} if {@code exitValue} signals a failure.
128     */
129    boolean isFailure(final int exitValue);
130
131    /**
132     * Sets the {@code exitValue} of the process to be considered successful. If a different exit value is returned by the process then
133     * {@link org.apache.commons.exec.Executor#execute(CommandLine)} will throw an {@link org.apache.commons.exec.ExecuteException}.
134     *
135     * @param value the exit code representing successful execution.
136     */
137    void setExitValue(final int value);
138
139    /**
140     * Sets a list of {@code exitValue} of the process to be considered successful. The caller can pass one of the following values.
141     * <ul>
142     * <li>an array of exit values to be considered successful</li>
143     * <li>an empty array for auto-detect of successful exit codes relying on {@link org.apache.commons.exec.Executor#isFailure(int)}</li>
144     * <li>null to indicate to skip checking of exit codes</li>
145     * </ul>
146     *
147     * If an undefined exit value is returned by the process then {@link org.apache.commons.exec.Executor#execute(CommandLine)} will throw an
148     * {@link org.apache.commons.exec.ExecuteException}.
149     *
150     * @param values a list of the exit codes.
151     */
152    void setExitValues(final int[] values);
153
154    /**
155     * Sets the handler for cleanup of started processes if the main process is going to terminate.
156     *
157     * @param processDestroyer the ProcessDestroyer.
158     */
159    void setProcessDestroyer(ProcessDestroyer processDestroyer);
160
161    /**
162     * Sets a custom the StreamHandler used for providing input and retrieving the output. If you don't provide a proper stream handler the executed process
163     * might block when writing to stdout and/or stderr (see {@link Process Process}).
164     *
165     * @param streamHandler the stream handler.
166     */
167    void setStreamHandler(ExecuteStreamHandler streamHandler);
168
169    /**
170     * Sets the watchdog used to kill of processes running, typically, too long time.
171     *
172     * @param watchDog the watchdog.
173     */
174    void setWatchdog(ExecuteWatchdog watchDog);
175
176    /**
177     * Sets the working directory of the created process. The working directory must exist when you start the process.
178     *
179     * @param dir the working directory.
180     */
181    void setWorkingDirectory(File dir);
182}