net.sf.jnati.proc
Class ProcessMonitor

java.lang.Object
  net.sf.jnati.proc.ProcessMonitor

public class ProcessMonitor
extends Object

This class is used to create and monitor the running of an operating system process.

Class for running a native process in a separate thread.

 ProcessMonitor proc = new ProcessMonitor("/usr/bin/babel", "-ismiles", "-ocml");
 proc.setInput("CN(C)CCC1=CNC2=C1C=C(C=C2)CC3COC(=O)N3");
 ByteArrayOutputStream out = new ByteArrayOutputStream();
 proc.setOutputStream(out);
 proc.setErrorStream(System.err);
 proc.execsute();
 

Author:

Sam Adams

Nested Class Summary

static class

ProcessMonitor.ProcessState

Constructor Summary

ProcessMonitor(List<String> command)
Constructs a monitored process with the specified operating system program and arguments.

ProcessMonitor(String... command)
Constructs a monitored process with the specified operating system program and arguments.

Method Summary

void	cancel() Cancel the process monitored by this object.
int	execute() Runs the process, waits for it to complete, and returns its exit status.
byte[]	getCachedError() Returns an array containing the last bytes the process monitored by this object has written to STDERR.
byte[]	getCachedOutput() Returns an array containing the last bytes the process monitored by this object has written to STDOUT.
List<String>	getCommand() Returns this monitored process's operating system program and arguments.
Map<String,String>	getEnvironment()
Integer	getExitValue()
Throwable	getFailCause() Returns any exception while the process is running, or null if no exception was thrown.
boolean	getRedirectErrorStream()
ProcessMonitor.ProcessState	getState() Returns the current state of this process.
long	getTimeout(TimeUnit unit)
File	getWorkingDirectory() Returns this monitored process's working directory.
ProcessOutput	runProcess() Runs the process, waits for it to complete, and returns its output.
void	setCommand(List<String> command) Sets this monitored process's operating system program and arguments.
void	setCommand(String... command) Sets this monitored process's operating system program and arguments.
void	setEnvironmentVariable(String key, String value)
void	setErrorTarget(OutputStream stderr) Sets the OutputStream to which bytes written to the process' STDERR will be directed.
void	setInput(byte[] input) Sets input for process.
void	setInput(InputStream input)
void	setInput(String input) Sets input for process.
void	setOutputTarget(OutputStream stdout) Sets the OutputStream to which bytes written to the process' STDOUT will be directed.
void	setRedirectErrorStream(boolean redirect)
void	setTimeout(long timeout, TimeUnit timeoutUnit) Sets timeout after which process will be stopped.
void	setWorkingDirectory(File dir) Sets this process' working directory.
void	start() Starts the new process to be monitored by this object.
void	unsetEnvironmentVariable(String key)
Integer	waitFor() Waits for the process to terminate, and returns the process' exit value.

Methods inherited from class java.lang.Object

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

Constructor Detail

ProcessMonitor

public ProcessMonitor(String... command)

Constructs a monitored process with the specified operating system program and arguments. It is not checked whether command corresponds to a valid operating system command.

Parameters:

command - A string array containing the program and its arguments

Throws:

NullPointerException - If the argument is null

ProcessMonitor

public ProcessMonitor(List<String> command)

Constructs a monitored process with the specified operating system program and arguments. It is not checked whether command corresponds to a valid operating system command.

Parameters:

command - A list containing the program and its arguments

Throws:

NullPointerException - If the argument is null

Method Detail

getCommand

public List<String> getCommand()

Returns this monitored process's operating system program and arguments. The returned list is a copy. Subsequent updates to the list will not be reflected in the state of this monitored process.

Returns:

This monitored process's program and its arguments

See Also:

ProcessBuilder.command()

setCommand

public void setCommand(String... command)

Sets this monitored process's operating system program and arguments. It is not checked whether command corresponds to a valid operating system command.

Parameters:

command - A string array containing the program and its arguments

Throws:

NullPointerException - If the argument is null

IllegalStateException - If this monitored process has been started

See Also:

ProcessBuilder.command(String...)

setCommand

public void setCommand(List<String> command)

Sets this monitored process's operating system program and arguments. It is not checked whether command corresponds to a valid operating system command.

Parameters:

command - A list containing the program and its arguments

command -

Throws:

NullPointerException - If the argument is null

IllegalStateException - If this monitored process has been started

See Also:

ProcessBuilder.command(List)

getEnvironment

public Map<String,String> getEnvironment()

setEnvironmentVariable

public void setEnvironmentVariable(String key,
                                   String value)

unsetEnvironmentVariable

public void unsetEnvironmentVariable(String key)

getWorkingDirectory

public File getWorkingDirectory()

Returns this monitored process's working directory. The returned value may be null -- this means to use the working directory of the current Java process, usually the directory named by the system property user.dir, as the working directory.

Returns:

This monitored process's working directory

See Also:

ProcessBuilder.directory()

setWorkingDirectory

public void setWorkingDirectory(File dir)

Sets this process' working directory. The argument may be null -- this means to use the working directory of the current Java process, usually the directory named by the system property user.dir, as the working directory of the child process.

Parameters:

dir - The new working directory

Throws:

IllegalStateException - If the process has been started

See Also:

ProcessBuilder.directory(File)

setInput

public void setInput(byte[] input)

Sets input for process.

Parameters:

input -

Throws:

NullPointerException - - if input is null.

IllegalStateException - - if process has been started, or input is already set.

setInput

public void setInput(String input)

Sets input for process. Makes call to setInput(final byte[] input), and will pass down any exception which that method throws.

Parameters:

input -

Throws:

NullPointerException - - if input is null.

setInput

public void setInput(InputStream input)

setErrorTarget

public void setErrorTarget(OutputStream stderr)

Sets the OutputStream to which bytes written to the process' STDERR will be directed. If this is set to null, then the output of the process will be discarded.

Parameters:

stderr -

Throws:

IllegalStateException - If the process has been started

setOutputTarget

public void setOutputTarget(OutputStream stdout)

Sets the OutputStream to which bytes written to the process' STDOUT will be directed. If this is set to null, then the output of the process will be discarded.

Parameters:

stdout -

Throws:

IllegalStateException - If the process has been started

setRedirectErrorStream

public void setRedirectErrorStream(boolean redirect)

getRedirectErrorStream

public boolean getRedirectErrorStream()

setTimeout

public void setTimeout(long timeout,
                       TimeUnit timeoutUnit)

Sets timeout after which process will be stopped. A timeout of 0 means wait forever.

Parameters:

timeout - - timeout in milliseconds.

Throws:

IllegalStateException - - if thread has been started.

getTimeout

public long getTimeout(TimeUnit unit)

getExitValue

public Integer getExitValue()
                     throws ExecutionException,
                            TimeoutException

Returns:

Throws:

IllegalStateException - If process has not been started, or is still running

ExecutionException - If this process threw an exception

TimeoutException - If this process timed out

CancellationException - If this process was cancelled

execute

public int execute()
            throws ExecutionException,
                   InterruptedException,
                   TimeoutException

Runs the process, waits for it to complete, and returns its exit status.

Returns:

Throws:

InterruptedException

IllegalStateException - - If process already started

InterruptedException - If this thread was interrupted before the process had finished.

TimeoutException

ExecutionException - If the process failed. This exception contains the output up to the point of failure, and the cause of failure.

runProcess

public ProcessOutput runProcess()
                         throws ExecutionException,
                                InterruptedException,
                                TimeoutException

Runs the process, waits for it to complete, and returns its output. This method captures the complete output (STDOUT/STDERR) from the process, along with its exit value. If the process produces a very large output then this may cause an OutOfMemoryError.

Returns:

Throws:

InterruptedException

IllegalStateException - - If process already started

InterruptedException - If this thread was interrupted before the process had finished.

TimeoutException

ExecutionException - If the process failed. This exception contains the output up to the point of failure, and the cause of failure.

waitFor

public Integer waitFor()
                throws ExecutionException,
                       TimeoutException,
                       InterruptedException

Waits for the process to terminate, and returns the process' exit value.

Returns:

The process' exit value

Throws:

IllegalStateException - If the process has not been started

ExecutionException - If an error occurs while the process is executing

CancellationException - If the process is cancelled

TimeoutException - If the process timed out

InterruptedException - If this thread is interrupted while waiting for the process to finish

start

public void start()

Starts the new process to be monitored by this object.

Throws:

IllegalStateException - If the process has been started.

cancel

public void cancel()

Cancel the process monitored by this object. If the process has already terminated, nothing is done.

Throws:

IllegalStateException - If the process has not started

getCachedOutput

public byte[] getCachedOutput()

Returns an array containing the last bytes the process monitored by this object has written to STDOUT.

Returns:

The last bytes the process has written to STDOUT.

Throws:

IllegalArgumentException - If the process has not started

getCachedError

public byte[] getCachedError()

Returns an array containing the last bytes the process monitored by this object has written to STDERR.

Returns:

The last bytes the process has written to STDERR.

Throws:

IllegalArgumentException - If the process has not started

getState

public ProcessMonitor.ProcessState getState()

Returns the current state of this process.

Returns:

getFailCause

public Throwable getFailCause()

Returns any exception while the process is running, or null if no exception was thrown.

Returns: