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    }