Package org.kiwiproject.base.process

Class ProcessHelper

java.lang.Object

org.kiwiproject.base.process.ProcessHelper

public class ProcessHelper
extends Object

This is a wrapper class around the static utility functions in Processes. You need to create an instance of this class to use it.

Using an instance of this class instead of Processes directly will make it much easier to test code that deals with operating system processes.

Note that most of the methods are intended only for use on Unix/Linux operating systems.

Constructor Summary

Constructors

Constructor	Description
ProcessHelper()

Method Summary

Modifier and Type	Method	Description
Optional<Long>	findChildProcessId(long parentProcessId)	For a given parent process id, find one and only one child process.
Collection<Long>	findChildProcessIds(long parentProcessId)	For a given parent process id, find any child processes.
int	kill(long processId, String signal, long timeout, TimeUnit unit, KillTimeoutAction action)	Kill a process, waiting up to timeout in the specified TimeUnit for it to terminate.
int	kill(long processId, String signal, KillTimeoutAction action)	Kill a process, waiting up to Processes.DEFAULT_KILL_TIMEOUT_SECONDS seconds for it to terminate.
int	kill(long processId, KillSignal signal, long timeout, TimeUnit unit, KillTimeoutAction action)	Kill a process, waiting up to timeout in the specified TimeUnit for it to terminate.
int	kill(long processId, KillSignal signal, KillTimeoutAction action)	Kill a process, waiting up to Processes.DEFAULT_KILL_TIMEOUT_SECONDS seconds for it to terminate.
boolean	killForcibly(Process process, long timeout, TimeUnit unit)	Equivalent to a kill -9 (i.e., a SIGKILL).
Process	launch(@Nullable File workingDirectory, List<String> command)	Launches a new process using the specified workingDirectory and command.
Process	launch(String... command)	Launches a new process using the specified command.
Process	launch(List<String> command)	Launches a new process using the specified command.
List<Long>	pgrep(String commandLine)	Does a pgrep with the specified full command.
List<Long>	pgrep(String user, String commandLine)	Does a pgrep with the specified full command.
List<String>	pgrepList(String commandLine)	Does a pgrep with the specified full command.
List<String>	pgrepList(String user, String commandLine)	Does a pgrep with the specified full command.
List<org.apache.commons.lang3.tuple.Pair<Long,String>>	pgrepParsedList(String commandLine)	Does a pgrep for the specified full command, returning a list of pairs containing the process id (pid) and the matched command line.
List<org.apache.commons.lang3.tuple.Pair<Long,String>>	pgrepParsedList(String user, String commandLine)	Does a pgrep for the specified full command, returning a list of pairs containing the process id (pid) and the matched command line.
Optional<Long>	pgrepWithSingleResult(String commandLine)	Does a pgrep against the specified full command, expecting a single result, or no result.
Optional<Long>	pgrepWithSingleResult(String user, String commandLine)	Does a pgrep against the specified full command, expecting a single result for a specific user, or no result.
Optional<Integer>	waitForExit(Process process)	Waits up to Processes.DEFAULT_WAIT_FOR_EXIT_TIME_SECONDS for the given process to exit.
Optional<Integer>	waitForExit(Process process, long timeout, TimeUnit unit)	Waits up to the specified timeout for the given process to exit.
Optional<String>	which(String program)	Locate a program in the user's path.
Optional<Path>	whichAsPath(String program)	Locate a program in the user's path, returning the result as a Path.

Methods inherited from class java.lang.Object

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

Constructor Details

ProcessHelper

public ProcessHelper()

Method Details

waitForExit

public Optional<Integer> waitForExit(Process process)

Waits up to Processes.DEFAULT_WAIT_FOR_EXIT_TIME_SECONDS for the given process to exit.

Parameters:

process - the process to wait for

Returns:

an Optional that will contain the exit code if the process exited before the timeout, or empty if the process did not exit before the timeout expired.

See Also:

• Processes.waitForExit(Process)

waitForExit

public Optional<Integer> waitForExit(Process process,
 long timeout,
 TimeUnit unit)

Waits up to the specified timeout for the given process to exit.

Parameters:

process - the process to wait for

timeout - the value of the time to wait

unit - the unit of time to wait

Returns:

an Optional that will contain the exit code if the process exited before the timeout, or empty if the process did not exit before the timeout expired.

See Also:

• Processes.waitForExit(Process, long, TimeUnit)

launch

public Process launch(List<String> command)

Launches a new process using the specified command.

Parameters:

command - the list containing the program and its arguments

Returns:

the new Process

See Also:

• Processes.launch(List)

launch

public Process launch(@Nullable File workingDirectory,
 List<String> command)

Launches a new process using the specified workingDirectory and command.

Parameters:

workingDirectory - the working directory to use

command - the list containing the program and its arguments

Returns:

the new Process

See Also:

• Processes.launch(File, List)

launch

public Process launch(String... command)

Launches a new process using the specified command.

Parameters:

command - a list containing the program and its arguments

Returns:

the new Process

See Also:

• Processes.launch(String...)

pgrep

public List<Long> pgrep(String commandLine)

Does a pgrep with the specified full command.

Parameters:

commandLine - the full command to match

Returns:

a list of matching process ids (pids)

See Also:

• Processes.pgrep(String)
• Processes.wasPgrepFlagsCheckSuccessful()
• Processes.getPgrepFlags()

pgrep

public List<Long> pgrep(String user,
 String commandLine)

Does a pgrep with the specified full command.

Parameters:

user - the OS user (passed to the -u option)

commandLine - the full command to match

Returns:

list of matching process ids (pids)

See Also:

• Processes.pgrep(String, String)
• Processes.wasPgrepFlagsCheckSuccessful()
• Processes.getPgrepFlags()

pgrepWithSingleResult

public Optional<Long> pgrepWithSingleResult(String commandLine)

Does a pgrep against the specified full command, expecting a single result, or no result.

Parameters:

commandLine - the full command line

Returns:

an optional either containing a process id, or an empty optional

See Also:

• Processes.pgrepWithSingleResult(String)
• Processes.wasPgrepFlagsCheckSuccessful()
• Processes.getPgrepFlags()

pgrepWithSingleResult

public Optional<Long> pgrepWithSingleResult(String user,
 String commandLine)

Does a pgrep against the specified full command, expecting a single result for a specific user, or no result.

Parameters:

user - the OS user (passed to the -u option)

commandLine - the full command to match

Returns:

an optional either containing a process id, or an empty optional

See Also:

• Processes.pgrepWithSingleResult(String, String)
• Processes.wasPgrepFlagsCheckSuccessful()
• Processes.getPgrepFlags()

pgrepList

public List<String> pgrepList(String commandLine)

Does a pgrep with the specified full command.

Parameters:

commandLine - the full command line to match

Returns:

a list of pgrep output, with each line in format "{pid} {command}"

See Also:

• Processes.pgrepList(String)
• Processes.wasPgrepFlagsCheckSuccessful()
• Processes.getPgrepFlags()

pgrepList

public List<String> pgrepList(String user,
 String commandLine)

Does a pgrep with the specified full command.

Parameters:

user - the OS user (passed to the -u option)

commandLine - the full command line to match

Returns:

a list of pgrep output, with each line in format "{pid} {command}"

See Also:

• Processes.pgrepList(String, String)
• Processes.wasPgrepFlagsCheckSuccessful()
• Processes.getPgrepFlags()

pgrepParsedList

public List<org.apache.commons.lang3.tuple.Pair<Long,String>> pgrepParsedList(String commandLine)

Does a pgrep for the specified full command, returning a list of pairs containing the process id (pid) and the matched command line.

Parameters:

commandLine - the full command line to match

Returns:

a list of Pair objects; each pair contains the pid as a Long and the associated full command

See Also:

• Processes.pgrepParsedList(String)
• Processes.wasPgrepFlagsCheckSuccessful()
• Processes.getPgrepFlags()

pgrepParsedList

public List<org.apache.commons.lang3.tuple.Pair<Long,String>> pgrepParsedList(String user,
 String commandLine)

Does a pgrep for the specified full command, returning a list of pairs containing the process id (pid) and the matched command line.

Parameters:

user - the OS user (passed to the -u option)

commandLine - the full command line to match

Returns:

a list of Pair objects; each pair contains the pid as a Long and the associated full command

See Also:

• Processes.pgrepParsedList(String, String)
• Processes.wasPgrepFlagsCheckSuccessful()
• Processes.getPgrepFlags()

kill

public int kill(long processId,
 KillSignal signal,
 KillTimeoutAction action)

Kill a process, waiting up to Processes.DEFAULT_KILL_TIMEOUT_SECONDS seconds for it to terminate.

Parameters:

processId - the pid of the process to kill

signal - the kill signal; this could be the signal number (e.g. "1") or name (e.g. "SIGHUP")

action - the KillTimeoutAction to take if the process doesn't terminate within the allotted time

Returns:

the exit code from the kill command, or -1 if action is

See Also:

• Processes.kill(long, KillSignal, KillTimeoutAction)

kill

public int kill(long processId,
 KillSignal signal,
 long timeout,
 TimeUnit unit,
 KillTimeoutAction action)

Kill a process, waiting up to timeout in the specified TimeUnit for it to terminate.

Parameters:

processId - the pid of the process to kill

signal - the kill signal enum

timeout - the time to wait for the process to be killed

unit - the time unit associated with timeout

action - the KillTimeoutAction to take if the process doesn't terminate within the allotted time

Returns:

the exit code from the kill command, or -1 if action is

See Also:

• Processes.kill(long, KillSignal, long, TimeUnit, KillTimeoutAction)

kill

public int kill(long processId,
 String signal,
 KillTimeoutAction action)

Kill a process, waiting up to Processes.DEFAULT_KILL_TIMEOUT_SECONDS seconds for it to terminate.

Parameters:

processId - the pid of the process to kill

signal - the kill signal; this could be the signal number (e.g. "1") or name (e.g. "SIGHUP")

action - the KillTimeoutAction to take if the process doesn't terminate within the allotted time

Returns:

the exit code from the kill command, or -1 if action is KillTimeoutAction.NO_OP and the kill command times out

Throws:

UncheckedIOException - if an I/O error occurs while killing the process

See Also:

• Processes.kill(long, String, KillTimeoutAction)

kill

public int kill(long processId,
 String signal,
 long timeout,
 TimeUnit unit,
 KillTimeoutAction action)

Kill a process, waiting up to timeout in the specified TimeUnit for it to terminate.

Parameters:

processId - the pid of the process to kill

signal - the kill signal; this could be the signal number (e.g. "1") or name (e.g. "SIGHUP")

timeout - the time to wait for the process to be killed

unit - the time unit associated with timeout

action - the KillTimeoutAction to take if the process doesn't terminate within the allotted time

Returns:

the exit code from the kill command, or -1 if action is KillTimeoutAction.NO_OP and the kill command times out

Throws:

UncheckedIOException - if an I/O error occurs while killing the process

See Also:

• Processes.kill(long, String, long, TimeUnit, KillTimeoutAction)

killForcibly

public boolean killForcibly(Process process,
 long timeout,
 TimeUnit unit)
                     throws InterruptedException

Equivalent to a kill -9 (i.e., a SIGKILL).

Parameters:

process - the process to kill forcibly

timeout - the time to wait for the process to be forcibly killed

unit - the time unit associated with the timeout

Returns:

true if process was killed before the timeout period elapsed; false otherwise

Throws:

InterruptedException - if the current thread is interrupted while waiting

See Also:

• Processes.killForcibly(Process, long, TimeUnit)

findChildProcessId

public Optional<Long> findChildProcessId(long parentProcessId)

For a given parent process id, find one and only one child process. There may be no child processes, in which case an empty Optional is returned.

This method considers it an error if the process has more than one child process id.

Parameters:

parentProcessId - the parent process id

Returns:

optional containing the child process id if there is one; otherwise an empty optional

Throws:

IllegalStateException - if there is more than one child process found

findChildProcessIds

public Collection<Long> findChildProcessIds(long parentProcessId)

For a given parent process id, find any child processes. There may be no child processes, in which case an empty collection is returned.

Parameters:

parentProcessId - the parent process id

Returns:

a collection of child pids, or an empty collection if there are no child processes

whichAsPath

public Optional<Path> whichAsPath(String program)

Locate a program in the user's path, returning the result as a Path.

Parameters:

program - the program to locate

Returns:

an Optional containing the full Path to the program, or an empty Optional if not found

See Also:

• Processes.whichAsPath(String)

Implementation Note:

If there is more than program found, only the first one is returned

which

public Optional<String> which(String program)

Locate a program in the user's path.

Parameters:

program - the program to locate

Returns:

an Optional containing the full path to the program, or an empty Optional if not found

See Also:

• Processes.which(String)

Implementation Note:

If there is more than program found, only the first one is returned