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 }