com.jalios.jcms.tools
Class ProcessExecutor

java.lang.Object
  com.jalios.jcms.tools.ProcessExecutor

public class ProcessExecutor
extends Object

Helper class to execute native operating system process.

Example :

      ProcessExecutor executor = new ProcessExecutor("/bin/echo", "Hello World!");
      executor.setCaptureOutput(true);

      ProcessExecutionResult result = executor.execute();
      assertEquals(0, result.getExitValue());
      assertFalse(result.hasTimedOut());
      assertEquals("Hello World!", result.getStdout().trim());
      assertEquals("", result.getStderr());
 

Warning : A default timeout value of 10 minutes is defined by DEFAULT_TIMEOUT constant.
Any process taking more time than this duration to execute will be KILLED !.
You can define your own timeout value through setTimeout(long).

Since:

jcms-7.0.0

Nested Class Summary

class

ProcessExecutor.ProcessExecutionResult Holds process execution result.

Field Summary

static long

DEFAULT_TIMEOUT Default value in milliseconds for the maximum execution time of a Process before is destroyed : 600000L

Constructor Summary

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

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

Method Summary

ProcessExecutor.ProcessExecutionResult	execute() Starts a new process using the attributes of this process executor and wait for its termination (either naturally or through the default timeout).
String	getName() Retrieve the name used to prefix any logs message and for threads name
long	getTimeout() Retrieve the maximum duration in milliseconds above which process is be stopped.
boolean	isCaptureOutput() Check if standard output and standard error have been requested for capture.
void	setCaptureOutput(boolean captureOutput) Set whether the standar output and standard error should be captured in an internal string for use after process execution.
void	setName(String name) Set the name used to prefix any logs message and for threads name
void	setTimeout(long timeout) Set the maximum duration in milliseconds above which process is stopped.
static String[]	splitCommandLine(String cmdLine) Split the specified command line String into a String array.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_TIMEOUT

public static final long DEFAULT_TIMEOUT

Default value in milliseconds for the maximum execution time of a Process before is destroyed : 600000L

Since:

jcms-7.0.0

See Also:

Constant Field Values

Constructor Detail

ProcessExecutor

public ProcessExecutor(List<String> command)

Constructs a process executor with the specified operating system program and arguments. This constructor does not make a copy of the command list. Subsequent updates to the list will be reflected in the state of the process builder. It is not checked whether command corresponds to a valid operating system command.

Parameters:

command - The list containing the program and its arguments

Throws:

NullPointerException - If the argument is null

Since:

jcms-7.0.0

ProcessExecutor

public ProcessExecutor(String... command)

Constructs a process executor with the specified operating system program and arguments. This is a convenience constructor that sets the process builder's command to a string list containing the same strings as the command array, in the same order. It is not checked whether command corresponds to a valid operating system command.

Parameters:

command - A string array containing the program and its arguments

Since:

jcms-7.0.0

Method Detail

setCaptureOutput

public void setCaptureOutput(boolean captureOutput)

Set whether the standar output and standard error should be captured in an internal string for use after process execution.

Default value is false, unless log level has been set to the TRACE level.

Parameters:

captureOutput - true to capture, false to ignore command output

Since:

jcms-7.0.0

isCaptureOutput

public boolean isCaptureOutput()

Check if standard output and standard error have been requested for capture.

Returns:

true if streams are capture, false otherwise

Since:

jcms-7.0.0

setName

public void setName(String name)

Set the name used to prefix any logs message and for threads name

Parameters:

name - a short string identifying the purpose of this Executor eg : "MyFeature"

Since:

jcms-7.0.0

getName

public String getName()

Retrieve the name used to prefix any logs message and for threads name

Returns:

a short string identifying the purpose of this Executor

Since:

jcms-7.0.0

setTimeout

public void setTimeout(long timeout)

Set the maximum duration in milliseconds above which process is stopped.

• < 0 : infinite (not recommended!!)
• == 0 : apply default timeout value defined by DEFAULT_TIMEOUT
• > 0 : duration in millisecond

Parameters:

timeout - a duration in millisecond, 0 a negative value of

Since:

jcms-7.0.0

getTimeout

public long getTimeout()

Retrieve the maximum duration in milliseconds above which process is be stopped.

If 0 was specified for timeout value, the default timeout is applied and this methods return the duration being applied

Returns:

a duration in milliseconds (negative value means infinite wait)

Since:

jcms-7.0.0

execute

public ProcessExecutor.ProcessExecutionResult execute()

Starts a new process using the attributes of this process executor and wait for its termination (either naturally or through the default timeout).

Returns:

the result of the execution, never return null

Since:

jcms-7.0.0

splitCommandLine

public static String[] splitCommandLine(String cmdLine)

Split the specified command line String into a String array.

Ensure any arguments enclosed in double quotes are kept as is.

Parameters:

cmdLine - the command line to split

Returns:

the split command line