net.sf.mmm.util.process.base
Class ProcessUtilImpl

java.lang.Object
  net.sf.mmm.util.component.base.AbstractComponent
      net.sf.mmm.util.component.base.AbstractLoggableComponent
          net.sf.mmm.util.process.base.ProcessUtilImpl

All Implemented Interfaces:

ProcessUtil

@Singleton
@Named
public class ProcessUtilImpl
extends AbstractLoggableComponent
implements ProcessUtil

This is the implementation of the ProcessUtil interface.
ATTENTION:
The execute-methods spin 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 and configure a thread-pool as Executor.

Since:

1.0.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Nested Class Summary

protected static class	ProcessUtilImpl.AsyncProcessExecutorImpl This inner class is the default implementation of the AsyncProcessExecutor.
protected class	ProcessUtilImpl.ProcessExecutor This inner class is does the actual execution of the Process(es).

Field Summary

private Executor	executor
private static ProcessUtil	instance
private StreamUtil	streamUtil

Constructor Summary

ProcessUtilImpl()
The constructor.

Method Summary

protected void	doInitialize() This method performs the actual initialization.
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.
protected Executor	getExecutor() This method gets the Executor used to run asynchronous tasks.
static ProcessUtil	getInstance() This method gets the singleton instance of this ProcessUtilImpl.
protected StreamUtil	getStreamUtil() This method gets the stream-util that is used by this process-util.
void	setExecutor(Executor executor) This method sets the executor.
void	setStreamUtil(StreamUtil streamUtil) This method sets the stream-util.

Methods inherited from class net.sf.mmm.util.component.base.AbstractLoggableComponent

getLogger, setLogger

Methods inherited from class net.sf.mmm.util.component.base.AbstractComponent

doInitialized, getInitializationState, initialize

Methods inherited from class java.lang.Object

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

Field Detail

instance

private static ProcessUtil instance

See Also:

getInstance()

streamUtil

private StreamUtil streamUtil

See Also:

getStreamUtil()

executor

private Executor executor

See Also:

getExecutor()

Constructor Detail

ProcessUtilImpl

public ProcessUtilImpl()

The constructor.

Method Detail

getInstance

public static ProcessUtil getInstance()

This method gets the singleton instance of this ProcessUtilImpl.
This design is the best compromise between easy access (via this indirection you have direct, static access to all offered functionality) and IoC-style design which allows extension and customization.
For IoC usage, simply ignore all static getInstance() methods and construct new instances via the container-framework of your choice (like plexus, pico, springframework, etc.). To wire up the dependent components everything is properly annotated using common-annotations (JSR-250). If your container does NOT support this, you should consider using a better one.

Returns:

the singleton instance.

doInitialize

protected void doInitialize()

This method performs the actual initialization. It is called when AbstractComponent.initialize() is invoked for the first time.
ATTENTION:
When you override this method from a sub-class you need to do a super.AbstractComponent.doInitialize().

Overrides:

doInitialize in class AbstractLoggableComponent

getExecutor

protected Executor getExecutor()

This method gets the Executor used to run asynchronous tasks. It may use a thread-pool.

Returns:

the executor.

setExecutor

@Inject
public void setExecutor(Executor executor)

This method sets the executor.

Parameters:

executor - the executor to set.

getStreamUtil

protected StreamUtil getStreamUtil()

This method gets the stream-util that is used by this process-util.

Returns:

the streamUtil

setStreamUtil

@Inject
public void setStreamUtil(StreamUtil streamUtil)

This method sets the stream-util.

Parameters:

streamUtil - the streamUtil to set

execute

public 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.

Specified by:

execute in interface ProcessUtil

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

public 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.

Specified by:

execute in interface ProcessUtil

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

public 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.

Specified by:

executeAsync in interface ProcessUtil

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).