001/*
002 * Copyright (c) 2004-2010 The Regents of the University of California.
003 * All rights reserved.
004 *
005 * '$Author: welker $'
006 * '$Date: 2010-05-06 05:21:26 +0000 (Thu, 06 May 2010) $' 
007 * '$Revision: 24234 $'
008 * 
009 * Permission is hereby granted, without written agreement and without
010 * license or royalty fees, to use, copy, modify, and distribute this
011 * software and its documentation for any purpose, provided that the above
012 * copyright notice and the following two paragraphs appear in all copies
013 * of this software.
014 *
015 * IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
016 * FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
017 * ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
018 * THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
019 * SUCH DAMAGE.
020 *
021 * THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
022 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
023 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
024 * PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
025 * CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
026 * ENHANCEMENTS, OR MODIFICATIONS.
027 *
028 */
029
030package org.kepler.ssh;
031
032import java.io.File;
033import java.io.OutputStream;
034import java.util.Collection;
035
036/**
037 * This interface defines functionality to execute local/remote commands and to
038 * transfer files. It is implemented by LocalExec and RemoteExec classes.
039 * 
040 * <p>
041 * 
042 * @author Norbert Podhorszki
043 */
044
045public interface ExecInterface {
046
047        /**
048         * Execute a command externally. The streams <i>streamOut</i> and
049         * <i>streamErr</i> should be provided to get the output and errors.
050         * 
051         * @return exit code of command if execution succeeded, throws
052         *         ExecException, which can also be an instance of
053         *         ExecTimeoutException
054         */
055        public abstract int executeCmd(String command, OutputStream streamOut,
056                        OutputStream streamErr) throws ExecException;
057
058        /**
059         * Execute a command externally where the command connects to a third party
060         * and needs to authenticate to that third party. The streams
061         * <i>streamOut</i> should be provided to get the output and errors (merged
062         * together in case of remote targets).
063         * 
064         * @return exit code of command if execution succeeded, throws
065         *         ExecException, which can also be an instance of
066         *         ExecTimeoutException
067         */
068        public abstract int executeCmd(String command, OutputStream streamOut,
069                        OutputStream streamErr, String thirdParty) throws ExecException;
070
071        /**
072         * Create directory. It should be relative to the user's home dir in case of
073         * remote machines, or to the current dir in case of local machine, or an
074         * absolute path. If parentflag is true, parent directories in the path
075         * should be created as well if necessary. Moreover, in this case, if the
076         * directory already exists, this method should return true (otherwise it
077         * returns an error).
078         * 
079         * @return true if succeeded
080         */
081        public boolean createDir(String dir, boolean parentflag)
082                        throws ExecException;
083
084        /**
085         * Delete file or directory on the local/remote site It should be relative
086         * to the user's home dir in case of remote machines, or to the current dir
087         * in case of local machine, or an absolute path For safety, * and ? is
088         * allowed in filename string only if explicitely asked with allowFileMask =
089         * true If you want to delete a directory, recursive should be set to true
090         * 
091         * @return true if succeeded
092         */
093        public boolean deleteFile(String fname, boolean recursive,
094                        boolean allowFileMask) throws ExecException;
095
096        /**
097         * Copy local files to a local/remote directory Input: files is a Collection
098         * of files of type File, targetPath is either a directory in case of
099         * several files, or it is either a dir or filename in case of one single
100         * local file recursive: true if you want traverse directories The files can
101         * have wildcards in their names but not in their path.
102         * 
103         * @return number of files copied successfully
104         */
105        public int copyTo(Collection files, String targetPath, boolean recursive)
106                        throws ExecException;
107
108        /**
109         * Copy a local file to a local/remote directory Input: file of type File
110         * (which can be a directory) The input can have wildcards in its name but
111         * not in its path. targetPath is either a directory or filename
112         * 
113         * @return number of files copied successfully (i.e either returns true or
114         *         an exception is raised)
115         */
116        public int copyTo(File lfile, String targetPath, boolean recursive)
117                        throws ExecException;
118
119        /**
120         * Copy files from a local/remote directory to a local path Input: 'files'
121         * is a Collection of files of type String (! not like at copyTo !),
122         * 'sourcePath' is either empty string (or null) in case the 'files' contain
123         * full paths to the individual files, or it should be a directory, and in
124         * this case each file name in 'files' will be extended with the directory
125         * name before copy. 'localPath' should be a directory name in case of
126         * several files. It can be a filename in case of a single file to be
127         * copied. This is a convenience method for copyFrom on several remote
128         * files. recursive: true if you want traverse directories
129         * 
130         * @return number of files copied successfully
131         */
132        public int copyFrom(String sourcePath, Collection files, File localPath,
133                        boolean recursive) throws ExecException;
134
135        /**
136         * Copy a local/remote file into a local file Input: 'sourcePath' of type
137         * String (can be a directory or filename) 'localPath' is either a directory
138         * or filename Only if 'recursive' is set, will directories copied
139         * recursively.
140         * 
141         * @return number of files copied successfully (i.e either returns true or
142         *         an exception is raised)
143         */
144        public int copyFrom(String sourcePath, File localPath, boolean recursive)
145                        throws ExecException;
146
147        /**
148         * Specify if killing of external processes (i.e. clean-up) after error or
149         * timeout is required. Not implemented for local execution. Use only if you
150         * are connecting to a unix machine.
151         */
152        public void setForcedCleanUp(boolean foo);
153
154        /**
155         * Set timeout for the operations. Timeout should be given in seconds. If
156         * 'stdout' is set to true, the timer is restarted whenever there is data on
157         * stdout. If 'stderr' is set to true, the timer is restarted whenever there
158         * is data on stderr. An operation will throw an ExecException, an instance
159         * of ExecTimeoutException if the timeout limit is reached. 'seconds' = 0
160         * means no timeout at all.
161         */
162        public void setTimeout(int seconds, boolean stdout, boolean stderr);
163
164        /**
165         * Set timeout for the operations.
166         */
167        public void setTimeout(int seconds);
168
169        /**
170         * addIdentity, useless for local exec 
171         */
172        public void addIdentity(String identity);
173
174        /**
175         * port forwarding not working on local exec
176         */
177        public void setPortForwardingL(String spec) 
178                        throws ExecException;
179
180        /**
181         * port forwarding not working on local exec
182         */
183        public void setPortForwardingR(String spec) 
184                        throws ExecException;
185
186        public boolean openConnection() 
187                        throws ExecException;
188
189        public void closeConnection();
190
191} // end-of-interface
192