Package ptolemy.util

Class StreamExec

java.lang.Object

ptolemy.util.StreamExec

All Implemented Interfaces:

ExecuteCommands

Direct Known Subclasses:

StringBufferExec

public class StreamExec
extends java.lang.Object
implements ExecuteCommands

Execute commands in a subprocess and send the results to stderr and stdout.

As an alternative to this class, see JTextAreaExec, which uses Swing; and StringBufferExec, which writes to a StringBuffer.

Sample usage:

 List execCommands = new LinkedList();
 execCommands.add("date");
 execCommands.add("sleep 3");
 execCommands.add("date");
 execCommands.add("notACommand");

 final StreamExec exec = new StreamExec();
 exec.setCommands(execCommands);

 exec.start();
 

Loosely based on Example1.java from http://java.sun.com/products/jfc/tsc/articles/threads/threads2.html

See also http://developer.java.sun.com/developer/qow/archive/135/index.jsp (1/11: Broken) and http://jw.itworld.com/javaworld/jw-12-2000/jw-1229-traps.html.

Since:

Ptolemy II 5.2

Version:

$Id$

Author:

Christopher Hylands

See Also:

JTextAreaExec, StringBufferExec

Pt.AcceptedRating:

Red (cxh)

Pt.ProposedRating:

Red (cxh)

Constructor Summary

Constructors

Constructor	Description
StreamExec()	Create a StreamExec.

Method Summary

Modifier and Type	Method	Description
protected void	_setProgressBarMaximum(int size)	Set the maximum of the progress bar.
void	appendToPath(java.lang.String directoryName)	Append to the path of the subprocess.
void	cancel()	Cancel any running commands.
void	clear()	Clear the text area, status bar and progress bar.
java.lang.String	getenv(java.lang.String key)	Get the value of the environment of the subprocess.
int	getLastSubprocessReturnCode()	Return the return code of the last subprocess that was executed.
java.lang.String	getPatternLog()	Return the value of the pattern log.
void	setCommands(java.util.List commands)	Set the list of commands.
void	setPattern(java.lang.String pattern)	Set the pattern that is used to search data sent to stdout.
void	setWaitForLastSubprocess(boolean waitForLastSubprocess)	Determine whether the last subprocess is waited for or not.
void	setWorkingDirectory(java.io.File workingDirectory)	Set the working directory of the subprocess.
void	start()	Start running the commands.
void	stderr(java.lang.String text)	Append the text message to stderr.
void	stdout(java.lang.String text)	Append the text message to the output.
static java.lang.String[]	updateEnvironment(java.lang.String key, java.lang.String value)	Update the environment and return the results.
void	updateStatusBar(java.lang.String text)	Set the text of the status bar.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StreamExec

public StreamExec()

Create a StreamExec.

Method Detail

appendToPath

public void appendToPath(java.lang.String directoryName)

Append to the path of the subprocess. If directoryName is already in the path, then it is not appended.

Specified by:

appendToPath in interface ExecuteCommands

Parameters:

directoryName - The name of the directory to append to the path.

cancel

public void cancel()

Cancel any running commands.

Specified by:

cancel in interface ExecuteCommands

clear

public void clear()

Clear the text area, status bar and progress bar.

Specified by:

clear in interface ExecuteCommands

getenv

public java.lang.String getenv(java.lang.String key)

Get the value of the environment of the subprocess.

Specified by:

getenv in interface ExecuteCommands

Parameters:

key - The key for which to search.

Returns:

The value of the key. If the key is not set, then null is returned. If appendToPath() has been called, and the then the environment for the subprocess is checked, which might be different than the environment for the current process because appendToPath() was called. Note that that key is searched for in a case-insensitive mode.

getPatternLog

public java.lang.String getPatternLog()

Return the value of the pattern log.

Calling this method resets the log of previously received matches.

Returns:

Any strings sent that match the value of the pattern. The matches for stdout are returned first, then the matches for stdout.

See Also:

setPattern(String), stdout(String)

getLastSubprocessReturnCode

public int getLastSubprocessReturnCode()

Return the return code of the last subprocess that was executed.

Specified by:

getLastSubprocessReturnCode in interface ExecuteCommands

Returns:

the return code of the last subprocess that was executed.

setCommands

public void setCommands(java.util.List commands)

Set the list of commands.

Specified by:

setCommands in interface ExecuteCommands

Parameters:

commands - A list of Strings, where each element is a command.

setPattern

public void setPattern(java.lang.String pattern)

Set the pattern that is used to search data sent to stdout.

If the value of the pattern argument is non-null, then each time stdout(String) is called, the value of the argument to stdout is compared with the pattern regex. If there is a match, then the value is appended to a StringBuffer that whose value may be obtained with the getPatternLog() method.

Calling this method resets the log of previously received matches.

Parameters:

pattern - The pattern used.

See Also:

getPatternLog()

setWaitForLastSubprocess

public void setWaitForLastSubprocess(boolean waitForLastSubprocess)

Determine whether the last subprocess is waited for or not.

Parameters:

waitForLastSubprocess - True if the start() method should wait for the last subprocess to finish.

setWorkingDirectory

public void setWorkingDirectory(java.io.File workingDirectory)

Set the working directory of the subprocess.

Specified by:

setWorkingDirectory in interface ExecuteCommands

Parameters:

workingDirectory - The working directory of the subprocess. If this argument is null, then the subprocess is executed in the working directory of the current process.

start

public void start()

Start running the commands. By default, the start() method returns after the last subprocess finishes. See setWaitForLastSubprocess(boolean).

Specified by:

start in interface ExecuteCommands

stderr

public void stderr(java.lang.String text)

Append the text message to stderr. A derived class could append to a StringBuffer. JTextAreaExec appends to a JTextArea. The output automatically gets a trailing newline appended.

Specified by:

stderr in interface ExecuteCommands

Parameters:

text - The text to append to standard error.

stdout

public void stdout(java.lang.String text)

Append the text message to the output. A derived class could append to a StringBuffer. JTextAreaExec appends to a JTextArea. The output automatically gets a trailing newline appended.

If setPattern(String) has been called with a non-null argument, then any text that matches the pattern regex will be appended to a log file. The log file may be read with getPatternLog().

Specified by:

stdout in interface ExecuteCommands

Parameters:

text - The text to append to standard out.

updateEnvironment

public static java.lang.String[] updateEnvironment(java.lang.String key,
                                                   java.lang.String value)

Update the environment and return the results. Read the environment for the current process, append the value of the value parameter to the environment variable named by the key parameter.

Parameters:

key - The environment variable to be updated.

value - The value to append

Returns:

An array of strings that consists of the subprocess environment variable names and values in the form name=value with the environment variable named by the key parameter updated to include the value of the value parameter.

updateStatusBar

public void updateStatusBar(java.lang.String text)

Set the text of the status bar. In this base class, do nothing, derived classes may update a status bar.

Specified by:

updateStatusBar in interface ExecuteCommands

Parameters:

text - The text with which the status bar is updated.

_setProgressBarMaximum

protected void _setProgressBarMaximum(int size)

Set the maximum of the progress bar. In this base class, do nothing, derived classes may update the size of the progress bar.

Parameters:

size - The maximum size of the progress bar.