net.sf.mmm.util.process.api
Interface ProcessUtil

All Known Implementing Classes:

ProcessUtilImpl

@ComponentSpecification
public interface ProcessUtil

This is the interface for a collection of utility functions to deal with Processes.

Since:

1.0.2

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

See Also:

ProcessUtilImpl

Method Summary

int	execute(ProcessContext context, long timeout, TimeUnit unit, ProcessBuilder... builders) This method executes the external Processes configured by the given builders.
int	execute(ProcessContext context, ProcessBuilder... builders) This method executes the external Processes configured by the given builders.
AsyncProcessExecutor	executeAsync(ProcessContext context, ProcessBuilder... builders) This method executes the external Processes configured by the given builders as async task.

Method Detail

execute

int execute(ProcessContext context,
            ProcessBuilder... builders)
            throws IOException,
                   InterruptedException

This method executes the external Processes configured by the given builders. If more than one builder is given, the according processes are piped.

Parameters:

context - is the context of the process pipe (fist stdin, last stdout and stderr for all processes as well as a potential timeout).

builders - are the configurations of the Process(es) to execute. The array needs to have a length greater than zero.

Returns:

the exit-code of the Process-pipe configured by the given builders.

Throws:

IOException - if an input/output-error occurred.

InterruptedException - if the calling Thread was interrupted while waiting for a Process to complete.

execute

int execute(ProcessContext context,
            long timeout,
            TimeUnit unit,
            ProcessBuilder... builders)
            throws IOException,
                   TimeoutException,
                   InterruptedException

This method executes the external Processes configured by the given builders. If more than one builder is given, the according processes are piped.
ATTENTION:
This method spins up multiple threads, especially when multiple processes are piped (2*n+1[+1] threads). Therefore you should NOT use the singleton variant of this util except you are writing a simple command-line client that does a simple job and then terminates. When writing a server-application or library, that makes such calls repetitive, you should create your own instance of ProcessUtil and configure a thread-pool as Executor.

Parameters:

context - is the context of the process pipe (fist stdin, last stdout and stderr for all processes as well as a potential timeout).

timeout - is the maximum amount of time to wait for the Process-pipe to finish.

unit - is the TimeUnit of the given timeout argument.

builders - are the configurations of the Process(es) to execute. The array needs to have a length greater than zero.

Returns:

the exit-code of the Process-pipe configured by the given builders.

Throws:

IOException - if an input/output-error occurred.

TimeoutException - if the Process-pipe did NOT complete before the given timeout (according to unit).

InterruptedException - if the calling Thread was interrupted while waiting for the Process-pipe to complete and before the timeout occurred.

executeAsync

AsyncProcessExecutor executeAsync(ProcessContext context,
                                  ProcessBuilder... builders)
                                  throws IOException

This method executes the external Processes configured by the given builders as async task. If more than one builder is given, the according processes are piped.
ATTENTION:
This method spins up multiple threads, especially when multiple processes are piped (2*n+1[+1] threads). Therefore you should NOT use the singleton variant of this util except you are writing a simple command-line client that does a simple job and then terminates. When writing a server-application or library, that makes such calls repetitive, you should create your own instance of ProcessUtil and configure a thread-pool as Executor.

Parameters:

context - is the context of the process pipe (fist stdin, last stdout and stderr for all processes as well as a potential timeout).

builders - are the configurations of the Process(es) to execute. The array needs to have a length greater than zero.

Returns:

the exit-code of the Process-pipe configured by the given builders.

Throws:

IOException - if an input/output-error occurred while setting up the Process(es).