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 }