Mp3dings 
20100427

de.mospace.lang
Class ProcessRunnable

java.lang.Object
  extended by de.mospace.lang.ProcessRunnable
All Implemented Interfaces:
RunnableQueue.Job, Runnable

public class ProcessRunnable
extends Object
implements RunnableQueue.Job

A runnable whose run method executes a system command. The system command is either specified as a single string or as an array of string tokens.

See Also:
Runtime.exec(java.lang.String)

Nested Class Summary
protected static class ProcessRunnable.FileInput
          Wraps a file as a ProcessRunnable.Input.
protected static class ProcessRunnable.FileOutput
          Wraps a file as a ProcessRunnable.Output.
protected static interface ProcessRunnable.Input
          A common interface for various kinds of byte sources.
protected static interface ProcessRunnable.Output
          A common interface for various kinds of byte sinks.
protected static class ProcessRunnable.PipeThread
          A thread that writes bytes from its input to its output as long as the associated ProcessRunnable is running.
protected static class ProcessRunnable.StreamInput
          Wraps an input stream as a ProcessRunnable.Input.
protected static class ProcessRunnable.StreamOutput
          Wraps an input stream as a ProcessRunnable.Input.
 
Field Summary
protected  ProcessRunnable.Output errp
          Where the error stream of this Runnable's system command will be redirected.
protected  ProcessRunnable.Input inpt
          Where this Runnable's system command will read its standard input from.
protected  ProcessRunnable.Output outp
          Where the output stream of this Runnable's system command will be redirected.
 
Constructor Summary
ProcessRunnable(String command)
          Constructs a new ProcessRunnable whose run() method will execute the specified command.
ProcessRunnable(String[] cmdarray)
          Constructs a new ProcessRunnable whose run() method will execute the command made up of the specified tokens.
 
Method Summary
 void clearInput()
          Causes this process runnable to not provide any standard input to its system command.
 String getCommand()
          Returns the command that will be executed when run() is called.
 String[] getCommandArray()
          Returns a copy of the command line that will be executed when run() is called.
 String getCommandAsString()
          Returns the command that will be executed when run() is called, independently of whether this command has been specified as a single string or as an array of string tokens.
 String[] getEnvironment()
          Returns the environment for this process runnable's system command.
protected  ExceptionHandler getExceptionHandler()
          Returns the exception handler that deals with exceptions thrown within the run() method.
 int getExitStatus()
          Returns the exit status of the system process that returned last.
 File getWorkingDirectory()
          Returns the working directory for this process runnable's system command.
 boolean hasInput()
          Returns whether this process runnable currently has a non-null input.
 boolean isRunning()
          Returns whether this process runnable is currently running.
 void readInputFrom(File f)
          Makes this process runnable's system command read input from the specified file.
 void readInputFrom(InputStream i)
          Makes this process runnable's system command read input from the specified stream.
 void redirectErrorsTo(File f)
          Redirects error output of this process runnable's system command to the specified file.
 void redirectErrorsTo(OutputStream o)
          Redirects error output of this process runnable's system command to the specified stream.
 void redirectOutputTo(File f)
          Redirects output of this process runnable's system command to the specified file.
 void redirectOutputTo(OutputStream o)
          Redirects output of this process runnable's system command to the specified stream.
 void registerExceptionHandler(ExceptionHandler xh)
          Registers an exception handler to deal with exceptions thrown within the run() method.
 void run()
          Executes this process runnable's system command.
 void setCommand(String cmd)
          Sets the command that will be executed when run() is called.
 void setCommand(String[] cmdarray)
          Sets the command line that will be executed when run() is called.
 void setEnvironment(String[] envp)
          Sets the environment for this process runnable's system command.
 void setWorkingDirectory(File dir)
          Sets the working directory for this process runnable's system command.
 void stop()
          Kills the system process spawned by the run() method if this process runnable is currently running.
 int waitFor()
          Waits for the system process spawned by the run() method to terminate if this process runnable is currently running.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

errp

protected ProcessRunnable.Output errp
Where the error stream of this Runnable's system command will be redirected. By default this is a NullStream.


outp

protected ProcessRunnable.Output outp
Where the output stream of this Runnable's system command will be redirected. By default this is a NullStream.


inpt

protected ProcessRunnable.Input inpt
Where this Runnable's system command will read its standard input from. By default this is null.

Constructor Detail

ProcessRunnable

public ProcessRunnable(String command)
Constructs a new ProcessRunnable whose run() method will execute the specified command.

Parameters:
command - the system command to execute

ProcessRunnable

public ProcessRunnable(String[] cmdarray)
Constructs a new ProcessRunnable whose run() method will execute the command made up of the specified tokens.

Parameters:
cmdarray - the tokens that together form the command line to execute
Method Detail

setCommand

public void setCommand(String cmd)
                throws IllegalStateException
Sets the command that will be executed when run() is called.

Parameters:
cmd - the system command to execute
Throws:
IllegalStateException - when this process runnable is currently running.

getCommand

public String getCommand()
Returns the command that will be executed when run() is called.

Returns:
the system command to execute or null if this process runnable's command has been specified as an array.

setCommand

public void setCommand(String[] cmdarray)
                throws IllegalStateException
Sets the command line that will be executed when run() is called.

Parameters:
cmdarray - the tokens that together form the command line to execute
Throws:
IllegalStateException - when this process runnable is currently running.

getCommandArray

public String[] getCommandArray()
Returns a copy of the command line that will be executed when run() is called.

Returns:
the command line to execute or null if this process runnable's command has been specified as a single string.

getCommandAsString

public String getCommandAsString()
Returns the command that will be executed when run() is called, independently of whether this command has been specified as a single string or as an array of string tokens.

Returns:
the system command to execute

redirectOutputTo

public void redirectOutputTo(OutputStream o)
                      throws IllegalStateException
Redirects output of this process runnable's system command to the specified stream. When null is passed output from the external process will be read and discarded (the default). The specified output stream will not be closed by this class.

Parameters:
o - the output stream the program should write its output to
Throws:
IllegalStateException - when this process runnable is currently running.

redirectOutputTo

public void redirectOutputTo(File f)
                      throws IllegalStateException
Redirects output of this process runnable's system command to the specified file. The file will be opened for writing and closed when the system commands starts and stops executing, respectively.

Parameters:
f - the file the program should write its output to
Throws:
IllegalStateException - when this process runnable is currently running.

redirectErrorsTo

public void redirectErrorsTo(OutputStream o)
                      throws IllegalStateException
Redirects error output of this process runnable's system command to the specified stream. When null is passed output from the external process will be read and discarded (the default). The specified output stream will not be closed by this class.

Parameters:
o - the output stream the program should write its output to
Throws:
IllegalStateException - when this process runnable is currently running.

redirectErrorsTo

public void redirectErrorsTo(File f)
                      throws IllegalStateException
Redirects error output of this process runnable's system command to the specified file. The file will be opened for writing and closed when the system commands starts and stops executing, respectively.

Parameters:
f - the file the program should write its output to
Throws:
IllegalStateException - when this process runnable is currently running.

setEnvironment

public void setEnvironment(String[] envp)
                    throws IllegalStateException
Sets the environment for this process runnable's system command.

Parameters:
envp - the environment for this process runnable's system command specified as an array of "key=value" pairs.
Throws:
IllegalStateException - when this process runnable is currently running.
See Also:
Runtime.exec(String[] cmd,String[] envp, File dir), getEnvironment()

getEnvironment

public String[] getEnvironment()
Returns the environment for this process runnable's system command.

Returns:
the environment for this process runnable's system command as an array of "key=value" pairs.
See Also:
Runtime.exec(String[] cmd,String[] envp, File dir), setEnvironment(java.lang.String[])

setWorkingDirectory

public void setWorkingDirectory(File dir)
                         throws IllegalStateException
Sets the working directory for this process runnable's system command.

Parameters:
dir - the working directory for this process runnable's system command
Throws:
IllegalStateException - when this process runnable is currently running.
See Also:
Runtime.exec(String[] cmd,String[] envp, File dir), getWorkingDirectory()

getWorkingDirectory

public File getWorkingDirectory()
Returns the working directory for this process runnable's system command.

Returns:
the working directory for this process runnable's system command
See Also:
getWorkingDirectory()

run

public void run()
Executes this process runnable's system command. If we are already running then we first wait until the process spawned on the last invocation terminates.

Specified by:
run in interface Runnable

registerExceptionHandler

public void registerExceptionHandler(ExceptionHandler xh)
Registers an exception handler to deal with exceptions thrown within the run() method. By default any exceptions thrown within run will be re-thrown as RuntimeExceptions.

Specified by:
registerExceptionHandler in interface RunnableQueue.Job
Parameters:
xh - an exception handler

getExceptionHandler

protected ExceptionHandler getExceptionHandler()
Returns the exception handler that deals with exceptions thrown within the run() method.

Returns:
the exception handler registered with this ProcessRunnable if any
See Also:
registerExceptionHandler(de.mospace.lang.ExceptionHandler)

stop

public void stop()
Kills the system process spawned by the run() method if this process runnable is currently running.

Specified by:
stop in interface RunnableQueue.Job

waitFor

public int waitFor()
            throws InterruptedException
Waits for the system process spawned by the run() method to terminate if this process runnable is currently running. In this case the exit value of the currently running process is returned. Otherwise this method has the same effect as getExitStatus().

Returns:
the exit value of the currently running process
Throws:
InterruptedException - if the system process is interrupted

getExitStatus

public int getExitStatus()
Returns the exit status of the system process that returned last.

Specified by:
getExitStatus in interface RunnableQueue.Job
Returns:
the exit status of the system process that returned last or zero if this runnable has never run.

isRunning

public boolean isRunning()
Returns whether this process runnable is currently running.

Returns:
whether this process runnable is currently running

readInputFrom

public void readInputFrom(File f)
Makes this process runnable's system command read input from the specified file. The file will be opened for reading and closed when the system commands starts and stops executing, respectively.

Parameters:
f - the file to read input from

readInputFrom

public void readInputFrom(InputStream i)
Makes this process runnable's system command read input from the specified stream.

Specified by:
readInputFrom in interface RunnableQueue.Job
Parameters:
i - the stream to read input from

hasInput

public boolean hasInput()
Returns whether this process runnable currently has a non-null input.

Specified by:
hasInput in interface RunnableQueue.Job
Returns:
whether this process runnable has a non-null input
See Also:
readInputFrom(File), readInputFrom(InputStream)

clearInput

public void clearInput()
Causes this process runnable to not provide any standard input to its system command.


Mp3dings 
20100427