org.biojava.utils.process

Class ExternalProcess

java.lang.Object

org.biojava.utils.process.ExternalProcess

public final class ExternalProcess
extends Object

Utility class to execute an external process and to handle the STDOUT, STDERR and STDIN streams in multiple threads managed by a thread pool.

This class is intended for applications that call an external program many times, e.g. in a loop, and that need high performance throughput, i.e. the program's input and output should not be written to disk. The Java Runtime.exec(java.lang.String) methods requires the application to read/write the external program's input and output streams in multiple threads. Otherwise the calling application may block. However, instantiating multiple threads for each call is extensive. On Linux systems there is also the problem that each Java thread is represented by a single process and the number of processes is limited on Linux. Because the Java garbage collector does not free the Thread objects properly, an application might run out of threads (indicated by a OutOfMemoryError exception) after multiple iterations. Therefore, the ExternalProcess class uses a thread pool.

The simplest way to use this class is by calling the static methods execute(String) and execute(String, String, StringWriter, StringWriter). However, these methods are not thread safe and no configuration is possible. In the former case the program's input, output and error output is redirected to STDIN, STDOUT and STDERR of the calling program. In the latter case input is provided as string and output and error output is written to StringWriter objects. The environment, i.e. the current working directory and the environment variables, are inherited from the calling process. In both cases, a static thread pool of size THREAD_POOL_SIZE is used. The command that should be executed is provided as a string argument.

In scenarios where the environment has to be changed, the program input is generated just in time, or the program's output is parsed just in time, the use of an explicit instance of the ExternalProcess class is recommended. This instance could be initialized with a custom thread pool. Otherwise a SimpleThreadPool of size 3 is used. The input and output is managed by multithreaded input handler and output handler objects. There are four predefined handlers that read the program's input from a Reader object or a InputStream object and write the program's output to a Writer object or a OutputStream object. These classes are called: ReaderInputHandler, SimpleInputHandler, WriterOutputHandler and SimpleOutputHandler. If no handlers are specified the input and output is redirected to the standards streams of the calling process.

Before one of the methods execute() or execute(Properties) is called, the commands property should be set. One may include placeholders of the form %PARAM% within the commands. If a Properties object is passed to the execute(Properties) method, the placeholders are replaced by the particular property value. Therefore, the Properties object must contain a key named PARAM (case doesn't matter). The environment for calling the external program can be configured using the properties workingDirectory and environmentProperties.

Finally, the sleepTime property can be increased, in case the output handlers are not able to catch the whole program's output within the given time. The default value is SLEEP_TIME [in milliseconds].

Version:

$Revision$

Author:

Martin Szugat

See Also:

Process

Field Summary

Fields

Modifier and Type	Field and Description
static int	SLEEP_TIME Number of milliseconds the execute method should pauses after the external process has finished the execution.
static int	THREAD_POOL_SIZE Size of the thread pool for the static execute methods.

Constructor Summary

Constructors

Constructor and Description
ExternalProcess() Initializes the external process.
ExternalProcess(ThreadPool threadPool) Initializes the external process.

Method Summary

Methods

Modifier and Type	Method and Description
int	execute() Executes the external process and waits for its termination.
int	execute(Properties variables) Executes the external process and waits for its termination.
static int	execute(String commands) Executes an external program.
static int	execute(String commands, String inputString, StringWriter outputString, StringWriter errorString) Executes an external program.
protected void	finalize()
String	getCommands() Gets the command line including the path or name of the external program and its command line arguments.
String[]	getEnvironmentProperties() Gets environment variables for the external process.
OutputHandler	getErrorHandler() Gets the output error handler which is responsible for the standard error output of the external process.
InputHandler	getInputHandler() Gets the input handler which is responsible for the standard input of the external process.
OutputHandler	getOutputHandler() Gets the output handler which is responsible for the standard output of the external process.
int	getSleepTime() Gets the number of milliseconds the execute(Properties) method should pauses after the external process is terminated.
File	getWorkingDirectory() Gets the working directory for the external process.
static String	joinCommands(Object[] commandList) Joins a command list to a single command string.
static void	main(String[] args) Runs an external program from the command line.
static String	resolveCommands(String commands, Properties variables) Resolves the given command line by replacing all placeholder of the format %NAME% with the values from the given properties for the corresponding keys of the format NAME.
void	setCommands(String commands) Sets the command line including the path or name of the external program and its command line arguments.
void	setEnvironmentProperties(String[] environmentProperties) Sets environment variables for the external process.
void	setErrorHandler(OutputHandler errorHandler) Sets the output error handler which is responsible for the standard error output of the external process.
void	setInputHandler(InputHandler inputHandler) Sets the input handler which is responsible for the standard input of the external process.
void	setOutputHandler(OutputHandler outputHandler) Sets the output handler which is responsible for the standard output of the external process.
void	setSleepTime(int sleepTime) Sets the number of milliseconds the execute(Properties) method should pauses after the external process is terminated.
void	setWorkingDirectory(File workingDirectory) Sets the working directory for the external process.
ThreadPool	threadPool() Gets the thread pool which is used for the input and output handlers.

Methods inherited from class java.lang.Object

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

Field Detail

THREAD_POOL_SIZE

public static final int THREAD_POOL_SIZE

Size of the thread pool for the static execute methods.

See Also:

Constant Field Values

SLEEP_TIME

public static final int SLEEP_TIME

Number of milliseconds the execute method should pauses after the external process has finished the execution.

See Also:

Constant Field Values

Constructor Detail

ExternalProcess

public ExternalProcess()

Initializes the external process.

ExternalProcess

public ExternalProcess(ThreadPool threadPool)

Initializes the external process.

Parameters:

threadPool - a thread pool with at least three threads or null if the default thread pool should be used

Method Detail

main

public static void main(String[] args)

Runs an external program from the command line. The external process inherits the environment variables and the current working directory from the parent process.

Parameters:

args - the path or the name of the external program and its command line arguments

resolveCommands

public static String resolveCommands(String commands,
                     Properties variables)
                              throws NullPointerException

Resolves the given command line by replacing all placeholder of the format %NAME% with the values from the given properties for the corresponding keys of the format NAME.

Parameters:

commands - the given command line

variables - the placeholders or null if no resolvement should be performed

Returns:

the new command line

Throws:

NullPointerException - if commands is null.

execute

public static int execute(String commands)
                   throws IOException,
                          InterruptedException,
                          NullPointerException,
                          SecurityException,
                          IllegalArgumentException

Executes an external program. The working directory and the environment variables are inherited from the parent process. The program input is read from STDIN, the program output is written to STDOUT and the program error output is written to STDERR.

Note: This method is not thread-safe.

Parameters:

commands - the command line including the path or the name of the external program and its command line arguments

Returns:

the exit code from the external program

Throws:

SecurityException - if a security manager exists and its checkExec method doesn't allow creation of a subprocess.

IOException - if an I/O error occurs.

NullPointerException - if commands is null.

IllegalArgumentException - if commandList is empty.

InterruptedException - if the current thread is interrupted by another thread while it is waiting, then the wait is ended and an InterruptedException is thrown.

execute

public static int execute(String commands,
          String inputString,
          StringWriter outputString,
          StringWriter errorString)
                   throws IOException,
                          InterruptedException,
                          NullPointerException,
                          SecurityException,
                          IllegalArgumentException

Executes an external program. The working directory and the environment variables are inherited from the parent process.

Note: This method is not thread-safe.

Parameters:

commands - the command line including the path or the name of the external program and its command line arguments

inputString - the input for the external programm or null if the input should be read from STDIN

outputString - the output of the external programm or null if the output should be written to STDOUT

errorString - the error output of the external program or null if the error output should be written to STDERR

Returns:

the exit code from the external program

Throws:

SecurityException - if a security manager exists and its checkExec method doesn't allow creation of a subprocess.

IOException - if an I/O error occurs.

NullPointerException - if commandList is null.

IllegalArgumentException - if commandList is empty.

InterruptedException - if the current thread is interrupted by another thread while it is waiting, then the wait is ended and an InterruptedException is thrown.

joinCommands

public static String joinCommands(Object[] commandList)
                           throws NullPointerException

Joins a command list to a single command string.

Parameters:

commandList - the list of the command and its arguments

Returns:

the joined command line

Throws:

NullPointerException - if commandList is null.

execute

public int execute()
            throws IOException,
                   InterruptedException,
                   SecurityException,
                   IllegalArgumentException

Executes the external process and waits for its termination.

Returns:

the exit code from the external process

Throws:

IllegalArgumentException - if the command is empty

SecurityException - if a security manager exists and its checkExec method doesn't allow creation of a subprocess.

IOException - if an I/O error occurs.

InterruptedException - if the current thread is interrupted by another thread while it is waiting, then the wait is ended and an InterruptedException is thrown.

execute

public int execute(Properties variables)
            throws IOException,
                   InterruptedException,
                   SecurityException,
                   IllegalArgumentException

Executes the external process and waits for its termination.

Parameters:

variables - a list of key-value-pairs that should be used to replace placeholders in the command line. May be null.

Returns:

the exit code from the external process

Throws:

SecurityException - if a security manager exists and its checkExec method doesn't allow creation of a subprocess.

IllegalArgumentException - if the command is empty

IOException - if an I/O error occurs.

InterruptedException - if the current thread is interrupted by another thread while it is waiting, then the wait is ended and an InterruptedException is thrown.

getCommands

public String getCommands()

Gets the command line including the path or name of the external program and its command line arguments.

Returns:

the command line

setCommands

public void setCommands(String commands)
                 throws NullPointerException

Sets the command line including the path or name of the external program and its command line arguments.

Parameters:

commands - the command line

Throws:

NullPointerException - if commands is null.

getEnvironmentProperties

public String[] getEnvironmentProperties()

Gets environment variables for the external process.

Returns:

a list of strings in the format name=value or null if the environment variables should be inherited from the parent process

setEnvironmentProperties

public void setEnvironmentProperties(String[] environmentProperties)

Sets environment variables for the external process.

Parameters:

environmentProperties - a list of strings in the format name=value or null if the environment variables should be inherited from the parent process

getErrorHandler

public OutputHandler getErrorHandler()

Gets the output error handler which is responsible for the standard error output of the external process.

Returns:

the error output handler

setErrorHandler

public void setErrorHandler(OutputHandler errorHandler)

Sets the output error handler which is responsible for the standard error output of the external process.

Parameters:

errorHandler - the error output handler or null if the error output should be redirected to STDERR

getInputHandler

public InputHandler getInputHandler()

Gets the input handler which is responsible for the standard input of the external process.

Returns:

the input handler

setInputHandler

public void setInputHandler(InputHandler inputHandler)

Sets the input handler which is responsible for the standard input of the external process.

Parameters:

inputHandler - the input handler or null if the input should be read from STDIN

getOutputHandler

public OutputHandler getOutputHandler()

Gets the output handler which is responsible for the standard output of the external process.

Returns:

the output handler

setOutputHandler

public void setOutputHandler(OutputHandler outputHandler)

Sets the output handler which is responsible for the standard output of the external process.

Parameters:

outputHandler - the output handler or null if the output should be redirected to STDOUT

threadPool

public ThreadPool threadPool()

Gets the thread pool which is used for the input and output handlers.

Returns:

a thread pool with at least three threads

getWorkingDirectory

public File getWorkingDirectory()

Gets the working directory for the external process.

Returns:

the working directory or null if it should be inherited from the parent process

setWorkingDirectory

public void setWorkingDirectory(File workingDirectory)

Sets the working directory for the external process.

Parameters:

workingDirectory - the working directory or null if it should be inherited from the parent process

getSleepTime

public int getSleepTime()

Gets the number of milliseconds the execute(Properties) method should pauses after the external process is terminated. This gives the stream handlers the time to complete their work.

Returns:

time in milliseconds

setSleepTime

public void setSleepTime(int sleepTime)
                  throws IllegalArgumentException

Sets the number of milliseconds the execute(Properties) method should pauses after the external process is terminated. Increase this value if the output handlers didn't catch the whole program output.

Parameters:

sleepTime - time in milliseconds

Throws:

IllegalArgumentException - if sleepTime is negative.

finalize

protected void finalize()

Overrides:

finalize in class Object