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    }