Package org.kiwiproject.base.process
Class ProcessHelper
- java.lang.Object
-
- org.kiwiproject.base.process.ProcessHelper
-
public class ProcessHelper extends Object
Wrapper class around the static utility functions inProcesses
that requires an instance, adn thus by using an instance of this class instead ofProcesses
directly, it will make it much easier to test code that deals with 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
All Methods Instance Methods Concrete Methods 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 totimeout
in the specifiedTimeUnit
for it to terminate.int
kill(long processId, String signal, KillTimeoutAction action)
Kill a process, waiting up toProcesses.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 totimeout
in the specifiedTimeUnit
for it to terminate.int
kill(long processId, KillSignal signal, KillTimeoutAction action)
Kill a process, waiting up toProcesses.DEFAULT_KILL_TIMEOUT_SECONDS
seconds for it to terminate.boolean
killForcibly(Process process, long timeout, TimeUnit unit)
Equivalent to akill -9
(i.e.Process
launch(String... command)
Launches a new process using the specifiedcommand
.Process
launch(List<String> command)
Launches a new process using the specifiedcommand
.List<Long>
pgrep(String commandLine)
Does apgrep
with the specified full command.List<Long>
pgrep(String user, String commandLine)
Does apgrep
with the specified full command.List<String>
pgrepList(String commandLine)
Does apgrep
with the specified full command.List<String>
pgrepList(String user, String commandLine)
Does apgrep
with the specified full command.List<org.apache.commons.lang3.tuple.Pair<Long,String>>
pgrepParsedList(String commandLine)
Does apgrep
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 apgrep
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 apgrep
against the specified full command, expecting a single result, or no result.Optional<Long>
pgrepWithSingleResult(String user, String commandLine)
Does apgrep
against the specified full command, expecting a single result for a specific user, or no result.Optional<Integer>
waitForExit(Process process)
Waits up toProcesses.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 specifiedtimeout
for the given process to exit.
-
-
-
Method Detail
-
waitForExit
public Optional<Integer> waitForExit(Process process)
Waits up toProcesses.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 specifiedtimeout
for the given process to exit.- Parameters:
process
- the process to wait fortimeout
- the value of the time to waitunit
- 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 specifiedcommand
.- Parameters:
command
- the list containing the program and its arguments- Returns:
- the new
Process
- See Also:
Processes.launch(List)
-
launch
public Process launch(String... command)
Launches a new process using the specifiedcommand
.- 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 apgrep
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 apgrep
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 apgrep
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 apgrep
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 apgrep
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 apgrep
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 apgrep
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 apgrep
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 toProcesses.DEFAULT_KILL_TIMEOUT_SECONDS
seconds for it to terminate.- Parameters:
processId
- the pid of the process to killsignal
- the kill signal; this could be the signal number (e.g. "1") or name (e.g. "SIGHUP")action
- theKillTimeoutAction
to take if the process doesn't terminate within the allotted time- Returns:
- the exit code from the
kill
command, or-1
ifaction
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 totimeout
in the specifiedTimeUnit
for it to terminate.- Parameters:
processId
- the pid of the process to killsignal
- the kill signal enumtimeout
- the time to wait for the process to be killedunit
- the time unit associated withtimeout
action
- theKillTimeoutAction
to take if the process doesn't terminate within the allotted time- Returns:
- the exit code from the
kill
command, or-1
ifaction
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 toProcesses.DEFAULT_KILL_TIMEOUT_SECONDS
seconds for it to terminate.- Parameters:
processId
- the pid of the process to killsignal
- the kill signal; this could be the signal number (e.g. "1") or name (e.g. "SIGHUP")action
- theKillTimeoutAction
to take if the process doesn't terminate within the allotted time- Returns:
- the exit code from the
kill
command, or-1
ifaction
isKillTimeoutAction.NO_OP
and the kill command times out - Throws:
UncheckedIOException
- if an I/O error occurs 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 totimeout
in the specifiedTimeUnit
for it to terminate.- Parameters:
processId
- the pid of the process to killsignal
- 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 killedunit
- the time unit associated withtimeout
action
- theKillTimeoutAction
to take if the process doesn't terminate within the allotted time- Returns:
- the exit code from the
kill
command, or-1
ifaction
isKillTimeoutAction.NO_OP
and the kill command times out - Throws:
UncheckedIOException
- if an I/O error occurs 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 akill -9
(i.e. aSIGKILL
).- Parameters:
process
- the process to kill forciblytimeout
- the time to wait for the process to be forcibly killedunit
- the time unit associated with thetimeout
- Returns:
true
ifprocess
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 emptyOptional
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
-
-