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 <code>exitValue</code> of the process to be considered
054 * successful. If a different exit value is returned by
055 * the process then {@link org.apache.commons.exec.Executor#execute(CommandLine)}
056 * will throw an {@link org.apache.commons.exec.ExecuteException}
057 *
058 * @param value the exit code representing successful execution
059 */
060 void setExitValue(final int value);
061
062 /**
063 * Define a list of <code>exitValue</code> of the process to be considered
064 * successful. The caller can pass one of the following values
065 * <ul>
066 * <li>an array of exit values to be considered successful</li>
067 * <li>an empty array for auto-detect of successful exit codes relying on {@link org.apache.commons.exec.Executor#isFailure(int)}</li>
068 * <li>null to indicate to skip checking of exit codes</li>
069 * </ul>
070 *
071 * If an undefined exit value is returned by the process then
072 * {@link org.apache.commons.exec.Executor#execute(CommandLine)} will
073 * throw an {@link org.apache.commons.exec.ExecuteException}.
074 *
075 * @param values a list of the exit codes
076 */
077 void setExitValues(final int[] values);
078
079 /**
080 * Checks whether <code>exitValue</code> signals a failure. If no
081 * exit values are set than the default conventions of the OS is
082 * used. e.g. most OS regard an exit code of '0' as successful
083 * execution and everything else as failure.
084 *
085 * @param exitValue the exit value (return code) to be checked
086 * @return <code>true</code> if <code>exitValue</code> signals a failure
087 */
088 boolean isFailure(final int exitValue);
089
090 /**
091 * Get the StreamHandler used for providing input and
092 * retrieving the output.
093 *
094 * @return the StreamHandler
095 */
096 ExecuteStreamHandler getStreamHandler();
097
098 /**
099 * Set a custom the StreamHandler used for providing
100 * input and retrieving the output. If you don't provide
101 * a proper stream handler the executed process might block
102 * when writing to stdout and/or stderr (see
103 * {@link java.lang.Process Process}).
104 *
105 * @param streamHandler the stream handler
106 */
107 void setStreamHandler(ExecuteStreamHandler streamHandler);
108
109 /**
110 * Get the watchdog used to kill of processes running,
111 * typically, too long time.
112 *
113 * @return the watchdog
114 */
115 ExecuteWatchdog getWatchdog();
116
117 /**
118 * Set the watchdog used to kill of processes running,
119 * typically, too long time.
120 *
121 * @param watchDog the watchdog
122 */
123 void setWatchdog(ExecuteWatchdog watchDog);
124
125 /**
126 * Set the handler for cleanup of started processes if the main process
127 * is going to terminate.
128 *
129 * @return the ProcessDestroyer
130 */
131 ProcessDestroyer getProcessDestroyer();
132
133 /**
134 * Get the handler for cleanup of started processes if the main process
135 * is going to terminate.
136 *
137 * @param processDestroyer the ProcessDestroyer
138 */
139 void setProcessDestroyer(ProcessDestroyer processDestroyer);
140
141 /**
142 * Get the working directory of the created process.
143 *
144 * @return the working directory
145 */
146 File getWorkingDirectory();
147
148 /**
149 * Set the working directory of the created process. The
150 * working directory must exist when you start the process.
151 *
152 * @param dir the working directory
153 */
154 void setWorkingDirectory(File dir);
155
156 /**
157 * Methods for starting synchronous execution. The child process inherits
158 * all environment variables of the parent process.
159 *
160 * @param command the command to execute
161 * @return process exit value
162 * @throws ExecuteException execution of subprocess failed or the
163 * subprocess returned a exit value indicating a failure
164 * {@link Executor#setExitValue(int)}.
165 */
166 int execute(CommandLine command)
167 throws ExecuteException, IOException;
168
169 /**
170 * Methods for starting synchronous execution.
171 *
172 * @param command the command to execute
173 * @param environment The environment for the new process. If null, the
174 * environment of the current process is used.
175 * @return process exit value
176 * @throws ExecuteException execution of subprocess failed or the
177 * subprocess returned a exit value indicating a failure
178 * {@link Executor#setExitValue(int)}.
179 */
180 int execute(CommandLine command, Map environment)
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 handler capture process termination and exit code
190 * @throws ExecuteException execution of subprocess failed
191 */
192 void execute(CommandLine command, ExecuteResultHandler handler)
193 throws ExecuteException, IOException;
194
195 /**
196 * Methods for starting asynchronous execution. The child process inherits
197 * all environment variables of the parent process. Result provided to
198 * callback handler.
199 *
200 * @param command the command to execute
201 * @param environment The environment for the new process. If null, the
202 * environment of the current process is used.
203 * @param handler capture process termination and exit code
204 * @throws ExecuteException execution of subprocess failed
205 */
206 void execute(CommandLine command, Map environment, ExecuteResultHandler handler)
207 throws ExecuteException, IOException;
208 }