001/* Execute commands in a subprocess.
002
003 Copyright (c) 2006-2013 The Regents of the University of California.
004 All rights reserved.
005 Permission is hereby granted, without written agreement and without
006 license or royalty fees, to use, copy, modify, and distribute this
007 software and its documentation for any purpose, provided that the above
008 copyright notice and the following two paragraphs appear in all copies
009 of this software.
010
011 IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
012 FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
013 ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
014 THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
015 SUCH DAMAGE.
016
017 THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
018 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
019 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
020 PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
021 CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
022 ENHANCEMENTS, OR MODIFICATIONS.
023
024 PT_COPYRIGHT_VERSION_2
025 COPYRIGHTENDKEY
026 */
027package ptolemy.util;
028
029import java.io.File;
030import java.util.List;
031
032/** Interface for classes execute commands in a subprocess.
033
034 <p>Loosely based on Example1.java from
035 <a href="http://java.sun.com/products/jfc/tsc/articles/threads/threads2.html">http://java.sun.com/products/jfc/tsc/articles/threads/threads2.html</a>
036 <p>See also
037 <a href="http://developer.java.sun.com/developer/qow/archive/135/index.jsp">http://developer.java.sun.com/developer/qow/archive/135/index.jsp</a> <i>(1/11: Broken)</i>
038 and
039 <a href="http://jw.itworld.com/javaworld/jw-12-2000/jw-1229-traps.html">http://jw.itworld.com/javaworld/jw-12-2000/jw-1229-traps.html</a>.</p>
040
041
042 @see StreamExec
043
044 @author Christopher Brooks
045 @version $Id$
046 @since Ptolemy II 5.2
047 @Pt.ProposedRating Red (cxh)
048 @Pt.AcceptedRating Red (cxh)
049 */
050public interface ExecuteCommands {
051
052    ///////////////////////////////////////////////////////////////////
053    ////                         public methods                    ////
054
055    /** Append to the path of the subprocess.
056     *  @param directoryName The name of the directory to append to the path.
057     */
058    public void appendToPath(String directoryName);
059
060    /** Cancel any running commands. */
061    public void cancel();
062
063    /** Clear the text area, status bar and progress bar. */
064    public void clear();
065
066    /** Get the value of the environment of the subprocess.
067     *  @param key The key to be looked up.
068     *  @return The value of the key.  If the key is not set, then
069     *  null is returned.  If appendToPath() has been called, and
070     *  the key parameter is "PATH", then the current value of the PATH
071     *  of the subprocess will be returned.  Note that this may be different
072     *  from the PATH of the current process.
073     */
074    public String getenv(String key);
075
076    /** Return the return code of the last subprocess that was executed.
077     *  @return the return code of the last subprocess that was executed.
078     */
079    public int getLastSubprocessReturnCode();
080
081    /** Set the list of commands.
082     *  @param commands A list of Strings, where each element is a command.
083     */
084    public void setCommands(List commands);
085
086    /** Set the working directory of the subprocess.
087     *  @param workingDirectory The working directory of the
088     *  subprocess.  If this argument is null, then the subprocess is
089     *  executed in the working directory of the current process.
090     */
091    public void setWorkingDirectory(File workingDirectory);
092
093    /** Start running the commands. */
094    public void start();
095
096    /** Append the text message to stderr.  Classes that implement
097     *  this method could append to a StringBuffer or JTextArea.
098     *  The output automatically gets a trailing newline  appended.
099     *  @param text The text to append to standard error.
100     */
101    public void stderr(final String text);
102
103    /** Append the text message to stderr.  Classes that implement
104     *  this method could append to a StringBuffer or JTextArea.
105     *  The output automatically gets a trailing newline  appended.
106     *  @param text The text to append to standard out.
107     */
108    public void stdout(final String text);
109
110    /** Set the text of the status bar.  In this base class, do
111     *  nothing, derived classes may update a status bar.
112     *  @param text The text with which the status bar is updated.
113     */
114    public void updateStatusBar(final String text);
115}