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 }