001/* Run a list of commands and save the output in a StringBuffer.
002
003 Copyright (c) 2007-2016 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
029/** Execute commands in a subprocess and accumulate the output in a
030 StringBuffer.
031
032 <p>As an alternative to this class, see
033 {@link ptolemy.gui.JTextAreaExec}, which uses Swing; and
034 {@link ptolemy.util.StreamExec}, which writes to stderr and stdout.
035
036 <p>Sample usage:
037 <pre>
038 List execCommands = new LinkedList();
039 execCommands.add("date");
040 execCommands.add("sleep 3");
041 execCommands.add("date");
042 execCommands.add("notACommand");
043
044 final StringBufferExec exec = new StringBufferExec();
045 exec.setCommands(execCommands);
046
047 exec.start();
048
049 String result = exec.buffer.toString();
050 </pre>
051
052 <p>Loosely based on Example1.java from
053 <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>
054 <p>See also
055 <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>
056 and
057 <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>
058
059 @see ptolemy.gui.JTextAreaExec
060
061 @author Christopher Brooks
062 @version $Id$
063 @since Ptolemy II 6.1
064 @Pt.ProposedRating Red (cxh)
065 @Pt.AcceptedRating Red (cxh)
066 */
067public class StringBufferExec extends StreamExec {
068
069    /** Create a StringBufferExec.  As the commands are executed,
070     *  output is appended to the StringBuffer - no output will appear
071     *  on stderr and stdout.
072     */
073    public StringBufferExec() {
074        super();
075        buffer = new StringBuffer();
076    }
077
078    /** Create a StringBufferExec and optionally append to stderr
079     *  and stdout as the commands are executed.
080     *  @param appendToStderrAndStdout If true, then as the commands
081     *  are executed, the output is append to stderr and stdout.
082     */
083    public StringBufferExec(boolean appendToStderrAndStdout) {
084        super();
085        _appendToStderrAndStdout = appendToStderrAndStdout;
086        buffer = new StringBuffer();
087    }
088
089    ///////////////////////////////////////////////////////////////////
090    ////                         public methods                    ////
091
092    /** Append the text message to the StringBuffer.  The output
093     *  automatically gets a trailing end of line character(s)
094     *  appended.
095     *  Optionally, the text also appears on stderr
096     *  @param text The text to append.
097     */
098    @Override
099    public void stderr(final String text) {
100        if (_appendToStderrAndStdout) {
101            super.stderr(text);
102        }
103        _appendToBuffer(text);
104    }
105
106    /** Append the text message to the StringBuffer.  The output
107     *  automatically gets end of line character(s) appended.
108     *  Optionally, the text also appears on stdout.
109     *  @param text The text to append.
110     */
111    @Override
112    public void stdout(final String text) {
113        if (_appendToStderrAndStdout) {
114            super.stdout(text);
115        }
116        _appendToBuffer(text);
117    }
118
119    ///////////////////////////////////////////////////////////////////
120    ////                         public variables                  ////
121
122    /** The StringBuffer to which the output is appended.  This
123     *  variable is public so that callers can clear the buffer as
124     *  necessary.
125     */
126    public StringBuffer buffer;
127
128    ///////////////////////////////////////////////////////////////////
129    ////                         private methods                   ////
130
131    /** Append to the internal StringBuffer.
132     *  @param text The text to append.  If the text does not
133     *  end with an end of line character(s), then _eol is appended.
134     */
135    private void _appendToBuffer(final String text) {
136        buffer.append(text);
137        if (!text.endsWith(_eol)) {
138            buffer.append(_eol);
139        }
140    }
141
142    ///////////////////////////////////////////////////////////////////
143    ////                         private variables                 ////
144
145    /** If true, append to stderr and stdout as the commands are executed.
146     */
147    private boolean _appendToStderrAndStdout = false;
148
149    /** End of line character.  Under Unix: "\n", under Windows: "\n\r".
150     *  We use a end of line character so that the files we generate
151     *  have the proper end of line character for use by other native tools.
152     */
153    private static String _eol;
154    static {
155        _eol = StringUtilities.getProperty("line.separator");
156    }
157
158}