org.safs.tools.consoles

Class GenericProcessCapture

java.lang.Object

org.safs.tools.consoles.GenericProcessConsole

org.safs.tools.consoles.GenericProcessCapture

All Implemented Interfaces:

java.lang.Runnable

Direct Known Subclasses:

ProcessCapture

public class GenericProcessCapture
extends GenericProcessConsole

Attempts to capture out and err streams from a process for use by other processes. The process data is available via a Vector retrieved from getData().

By default, this subclass of GenericProcessConsole disables the out and err streams from appearing in the debug/console output. Users can change this behavior by overriding the debug() method and also by turning on the output of either or both of the streams via GenericProcessConsole.setShowOutStream(boolean) and GenericProcessConsole.setShowErrStream(boolean).

Normal usage might be something like below:

 
        Process process = runtime.exec(procstr);
        GenericProcessCapture console = new GenericProcessCapture(process);
        Thread athread = new Thread(console);
        athread.start();
  //we can wait until process is finished
        try{ athread.join();}catch(InterruptedException x){;}
        console.shutdown();//precaution
        Vector data = console.getData();
 

Alternatively, we can autostart the capture thread. We don't have to wait for it to end if we don't want to. The autostarted thread can be acquired, though:

 
        Process process = runtime.exec(procstr);
        GenericProcessCapture console = new GenericProcessCapture(process, null, true);
  //we can wait until process is finished if we want
        try{ console.thread.join();}catch(InterruptedException x){;}
        Vector data = console.getData();
        console.shutdown();//precautionary force shutdown
 

Data for the Error and Output streams is captured into the single Vector storage. The Error stream data is prefixed with the ERR_PREFIX, while the Output data is prefixed with the OUT_PREFIX.

This class contains no extended SAFS dependencies and can be readily packaged and distributed for non-SAFS installations.

Author:

Carl Nagle

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.Vector	data
java.lang.String	monitor If non-null, we will check to see if this CMD(Unix), IMAGE(Win), or PID is running.
java.lang.Thread	thread The (running) thread used to autostart the process capture, if applicable.

Fields inherited from class org.safs.tools.consoles.GenericProcessConsole

err, ERR_PREFIX, exceptions, exited, exitValue, in, out, OUT_PREFIX, process, showErrStream, showOutStream, shutdown

Constructor Summary

Constructors

Constructor and Description
GenericProcessCapture(java.lang.Process process) Default Constructor for GenericProcessCapture.
GenericProcessCapture(java.lang.Process process, java.lang.String monitor, boolean autostart) Alternative constructor allowing the IO thread to remain open as long as a secondary process/pid remains running (if specified).
GenericProcessCapture(java.lang.Process process, java.lang.String monitor, boolean autostart, boolean debug2console) Alternative constructor allowing the IO thread to remain open as long as a secondary process/pid remains running (if specified).

Method Summary

Modifier and Type	Method and Description
java.util.Vector	getData() Return a snapshot(copy) of the String lines of data from the streams.
int	getDataLineCount()
void	run() Continuously monitors the process out and err streams routing them to the local process System.out and System.err.
void	waitOutput(long timeout, int stdoutLineToWait, int stderrLineToWait) Wait for the number of line on both STDOUT and STDERR is bigger than some expected number respectively.

Methods inherited from class org.safs.tools.consoles.GenericProcessConsole

_initialize, debug, getExceptions, getExceptionsCount, getExitValue, isExited, setShowErrStream, setShowOutStream, shutdown

Methods inherited from class java.lang.Object

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

Field Detail

data

protected java.util.Vector data

monitor

public java.lang.String monitor

If non-null, we will check to see if this CMD(Unix), IMAGE(Win), or PID is running. If the process is still running, we will not attempt to end our reading of the IO streams.

thread

public java.lang.Thread thread

The (running) thread used to autostart the process capture, if applicable. Will normally be null if this thread was not autostarted.

Constructor Detail

GenericProcessCapture

public GenericProcessCapture(java.lang.Process process)

Default Constructor for GenericProcessCapture. This sets up a default console that does not monitor any secondary processes and does NOT autostart its own capture thread. This instance also will not route either the System.out or System.err to the debug() sink.

Parameters:

process - to capture IO in, out, and err streams.

See Also:

thread, GenericProcessConsole.setShowOutStream(boolean), GenericProcessConsole.setShowErrStream(boolean)

GenericProcessCapture

public GenericProcessCapture(java.lang.Process process,
                             java.lang.String monitor,
                             boolean autostart)

Alternative constructor allowing the IO thread to remain open as long as a secondary process/pid remains running (if specified). This instance also will not route either the System.out or System.err to the debug() sink.

Parameters:

process - -- to capture IO in, out, and err streams.

monitor - -- optional secondary process name or pid to monitor for continued IO output.

autostart - -- true if we should automatically start the separate capture thread.

See Also:

thread, GenericProcessConsole.setShowOutStream(boolean), GenericProcessConsole.setShowErrStream(boolean)

GenericProcessCapture

public GenericProcessCapture(java.lang.Process process,
                             java.lang.String monitor,
                             boolean autostart,
                             boolean debug2console)

Alternative constructor allowing the IO thread to remain open as long as a secondary process/pid remains running (if specified). This version also allows the caller to change the default behavior for routing the System.out and System.err streams to the debug() sink.

Parameters:

process - -- to capture IO in, out, and err streams.

monitor - -- optional secondary process name or pid to monitor for continued IO output.

autostart - -- true if we should automatically start the separate capture thread.

debug2console - set true to have the out and err streams copied to the debug() sink.

Method Detail

waitOutput

public void waitOutput(long timeout,
                       int stdoutLineToWait,
                       int stderrLineToWait)
                throws java.util.concurrent.TimeoutException

Wait for the number of line on both STDOUT and STDERR is bigger than some expected number respectively.

Parameters:

timeout - long, the timeout in millisecond.

stdoutLineToWait - int, the number of line on STDOUT to wait.

stderrLineToWait - int, the number of line on STDERR to wait.

Throws:

java.util.concurrent.TimeoutException - if the timeout has been reached before the condition is satisfied.

Example:

1. //Wait that the number of output on STDOUT is bigger than 20 lines
   waitOutput(2000, 20, 0);
2. //Wait that the number of output on STDERR is bigger than 20 lines
   waitOutput(2000, 0, 20);
3. //Wait that the number of output on both STDOUT and STDERR is bigger than 20 lines
   waitOutput(2000, 20, 20);

getData

public java.util.Vector getData()

Return a snapshot(copy) of the String lines of data from the streams. The output stream data is prefixed with OUT_PREFIX. The error stream data is prefixed with ERR_PREFIX.

Returns:

Vector storing a snapshot of the data read from Process out and err streams.

getDataLineCount

public int getDataLineCount()

Returns:

the count of lines in combined out and err streams, or 0.

run

public void run()

Description copied from class: GenericProcessConsole

Continuously monitors the process out and err streams routing them to the local process System.out and System.err. Also attempts to see "unhandled exceptions" and store them in the exceptions Vector. Will run indefinitely until the process exits on its own or the shutdown method is called.

Specified by:

run in interface java.lang.Runnable

Overrides:

run in class GenericProcessConsole

See Also:

GenericProcessConsole.getExceptions(), GenericProcessConsole.shutdown()