Package com.jalios.jcms.tools

Class ProcessExecutor

  • public class ProcessExecutor
extends java.lang.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

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static long DEFAULT_TIMEOUT
      Default value in milliseconds for the maximum execution time of a Process before is destroyed : 600000L

    • Constructor Summary

      Constructors 
      Constructor Description
      ProcessExecutor​(java.lang.String... command)
      Constructs a process executor with the specified operating system program and arguments.
      ProcessExecutor​(java.util.List<java.lang.String> command)
      Constructs a process executor with the specified operating system program and arguments.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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).
      java.lang.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​(java.lang.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 java.lang.String[] splitCommandLine​(java.lang.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​(java.util.List<java.lang.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:
        java.lang.NullPointerException - If the argument is null
        Since:
        jcms-7.0.0

      • ProcessExecutor

        public ProcessExecutor​(java.lang.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​(java.lang.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 java.lang.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 java.lang.String[] splitCommandLine​(java.lang.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