Package org.kiwiproject.base.process

Class Processes

  • public class Processes
extends Object
    Utility class for working with operating system processes.

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

    See Also:
    ProcessHelper

    • Constructor Detail

      • Processes

        public Processes()

    • Method Detail

      • wasPgrepFlagsCheckSuccessful

        public static boolean wasPgrepFlagsCheckSuccessful()
        Use this method to determine if calling any of the pgrep methods in this class will work as expected.
        Returns:
        true if the pgrep check to determine the flags to use for full command matching was successful; false otherwise. If false you should NOT use any of the pgrep methods.
        See Also:
        getPgrepFlags()

      • getPgrepFlags

        public static String getPgrepFlags()
        Returns the pgrep flags that Processes will use in all pgrep methods. Use wasPgrepFlagsCheckSuccessful() to check if the flags were chosen successfully to ensure that pgrep commands will work as expected on your OS.
        Returns:
        the flags that will be used in pgrep commands

      • processId

        public static long processId​(Process process)
        Get a process id, or "pid".

        Earlier versions of Kiwi used to perform some nasty things (checking if the actual process class was java.lang.UNIXProcess, then using reflection to get the value of the private pid field) to obtain Process pids, but since JDK 9 offers the Process.pid() method, that is no longer necessary. This method is now a simple delegation to Process.pid() and you should now prefer that method.

        Parameters:
        process - the process to obtain the process id (pid) from
        Returns:
        the process id of process
        Throws:
        UnsupportedOperationException - if the Process implementation does not support getting the pid
        See Also:
        Process.pid()

      • processIdOrEmpty

        public static OptionalLong processIdOrEmpty​(Process process)
        Get a process id, or "pid", if it is available from the Process implementation, wrapped inside an OptionalLong. If the pid is not available for whatever reason, return an empty OptionalLong.
        Parameters:
        process - the process to obtain the process id (pid) from
        Returns:
        an OptionalLong containing the process if of process or an empty OptionalLong if the Process implementation does not support getting the pid for whatever reason.
        Implementation Note:
        the Process.pid() method says it can throw UnsupportedOperationException if the "implementation does not support this operation" but does not specify under what circumstances that can happen, and I have not been able to find this information using Google, Bing, or DuckDuckGo. This method logs a warning along with the exception, so if this occurs check your logs for the possible reason.

      • isSuccessfulExitCode

        public static boolean isSuccessfulExitCode​(int exitCode)
        Check if the given exit code represents successful termination.
        Parameters:
        exitCode - the exit code to check
        Returns:
        true if the exit code represents success
        See Also:
        SUCCESS_EXIT_CODE, Process.exitValue()

      • waitForExit

        public static Optional<Integer> waitForExit​(Process process)
        Waits up to 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.

      • waitForExit

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

      • launch

        public static 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:
        launch(List)

      • pgrepWithSingleResult

        public static 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:
        wasPgrepFlagsCheckSuccessful(), getPgrepFlags()

      • pgrepWithSingleResult

        public static 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:
        wasPgrepFlagsCheckSuccessful(), getPgrepFlags()

      • pgrepList

        public static 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:
        wasPgrepFlagsCheckSuccessful(), getPgrepFlags()

      • pgrepParsedList

        public static 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:
        pgrepParsedList(String, String), wasPgrepFlagsCheckSuccessful(), getPgrepFlags()

      • pgrepParsedList

        public static 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:
        wasPgrepFlagsCheckSuccessful(), getPgrepFlags()

      • kill

        public static int kill​(long processId,
                       String signal,
                       KillTimeoutAction action)
        Kill a process, waiting up to 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 killing the process

      • kill

        public static 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:
        kill(long, String, long, TimeUnit, KillTimeoutAction)

      • kill

        public static 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 killing the process

      • killForcibly

        public static 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:
        Process.destroyForcibly(), Process.waitFor(long, TimeUnit)