Package ca.cgjennings.apps.arkham

Class Subprocess

  • public final class Subprocess
extends java.lang.Object
    A Subprocess is a child process that has been started by, and is being monitored by, the application. The subprocess runs concurrently with the application. The output and error streams of the subprocess are connected to the script console.

    While Subprocess can be used to run any shell command, it has special support for starting Java apps, and in particular for starting Java apps included with this app, such as the script debugger client.

    Since:
    3.0
    Author:
    Chris Jennings

    • Constructor Summary

      Constructors 
      Constructor Description
      Subprocess​(java.lang.String... command)
      Creates a new Subprocess that will execute the specified command.
      Subprocess​(java.util.List<java.lang.String> command)
      Creates a new Subprocess that will execute the specified command.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      javax.swing.JComponent createStopButton​(java.lang.String label)
      Creates a control in the main application window that the user can use to terminate the subprocess.
      static java.lang.String getClasspath()
      Returns the application's class path.
      int getExitCode()
      Returns the process's exit code, or -1 if the process has not completed.
      static java.lang.String getJavaRuntimeExecutable()
      Returns a command that can be used to launch a Java runtime.
      boolean isExitCodeShown()
      Returns true if the exit code will be written to the console when the process ends.
      boolean isRunning()
      Returns true if this subprocess has been started and it is still running.
      boolean isStarted()
      Returns true if this subprocess has been started.
      boolean isStreamIORedirected()
      Returns true if this subprocess will redirect the standard I/O streams to the script console.
      boolean isSurvivor()
      Returns true if this subprocess will continue after the application terminates.
      static Subprocess launch​(java.lang.String... appClassNameAndArguments)
      Returns a new Subprocess that will launch an app that is part of this app's main library or JAR file.
      static Subprocess launch​(java.util.List<java.lang.String> appClassNameAndArguments)
      Returns a new Subprocess that will launch an app that is part of this app's main library or JAR file.
      void setExitCodeShown​(boolean show)
      Sets whether the exit code is written to the console when the process ends.
      void setStreamIORedirected​(boolean redirect)
      Sets whether the subprocess will redirect the standard I/O streams to the script console.
      void setSurvivor​(boolean survivor)
      Sets whether the subprocess will be a survivor.
      void start()
      Starts the subprocess.
      void stop()
      Stops the process if it is currently running.
      void waitFor()
      Waits for the subprocess to end.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • Subprocess

        public Subprocess​(java.lang.String... command)
        Creates a new Subprocess that will execute the specified command.
        Parameters:
        command - an array of command tokens to execute
        Throws:
        java.lang.NullPointerException - if command is null
        java.lang.IllegalArgumentException - if command.length == 0
        java.lang.IllegalStateException - if the application window has not been created yet

      • Subprocess

        public Subprocess​(java.util.List<java.lang.String> command)
        Creates a new Subprocess that will execute the specified command.
        Parameters:
        command - an list of command tokens to execute
        Throws:
        java.lang.NullPointerException - if command is null
        java.lang.IllegalArgumentException - if command.length == 0
        java.lang.IllegalStateException - if the application window has not been created yet

    • Method Detail

      • launch

        public static Subprocess launch​(java.lang.String... appClassNameAndArguments)
        Returns a new Subprocess that will launch an app that is part of this app's main library or JAR file. For example, launch("debugger") would launch the debugger client by starting a new runtime with the same classpath as this app and passing it the debugger class.

        If necessary, additional or replacement JVM arguments may be specified before the class name (which is otherwise the first argument).

        Parameters:
        appClassNameAndArguments - the name of the app, followed by any additional command line arguments to pass to the app
        Returns:
        the new Subprocess controlling the launched app
        Throws:
        java.lang.IllegalArgumentException - if argument list is null or empty
        java.lang.IllegalStateException - if the application window has not been created yet
        Since:
        3.2

      • launch

        public static Subprocess launch​(java.util.List<java.lang.String> appClassNameAndArguments)
        Returns a new Subprocess that will launch an app that is part of this app's main library or JAR file. For example, launch("debugger") would launch the debugger client by starting a new runtime with the same classpath as this app and passing it the debugger class.

        If necessary, additional or replacement JVM arguments may be specified before the class name (which is otherwise the first argument).

        Parameters:
        appClassNameAndArguments - the name of the app, followed by any additional command line arguments to pass to the app
        Returns:
        the new Subprocess controlling the launched app
        Throws:
        java.lang.IllegalArgumentException - if argument list is null or empty
        java.lang.IllegalStateException - if the application window has not been created yet
        Since:
        3.2

      • isStarted

        public boolean isStarted()
        Returns true if this subprocess has been started. Once a subprocess has started, its configuration cannot be modified. Once the subprocess starts, this method will always return true even after the subprocess ends.
        Returns:
        true if the process has started
        See Also:
        isRunning()

      • isRunning

        public boolean isRunning()
        Returns true if this subprocess has been started and it is still running.
        Returns:
        true if the process has started but not finished
        See Also:
        isStarted()

      • setSurvivor

        public void setSurvivor​(boolean survivor)
        Sets whether the subprocess will be a survivor. If true, then the process will not be destroyed when the application terminates.
        Parameters:
        survivor - true if the subprocess will survive the application
        Throws:
        java.lang.IllegalStateException - if the subprocess has already been started

      • isSurvivor

        public boolean isSurvivor()
        Returns true if this subprocess will continue after the application terminates.
        Returns:
        true if the subprocess will survive the application

      • setStreamIORedirected

        public void setStreamIORedirected​(boolean redirect)
        Sets whether the subprocess will redirect the standard I/O streams to the script console. The default is to redirect streams.
        Parameters:
        redirect - true if the streams will be redirected
        Throws:
        java.lang.IllegalStateException - if the subprocess has already been started
        Since:
        3.2

      • isStreamIORedirected

        public boolean isStreamIORedirected()
        Returns true if this subprocess will redirect the standard I/O streams to the script console.
        Returns:
        true if the streams will be redirected
        Since:
        3.2

      • setExitCodeShown

        public void setExitCodeShown​(boolean show)
        Sets whether the exit code is written to the console when the process ends. The default is true.
        Parameters:
        show - if true, print the exit code

      • isExitCodeShown

        public boolean isExitCodeShown()
        Returns true if the exit code will be written to the console when the process ends.
        Returns:
        true if the exit code is printed

      • createStopButton

        public javax.swing.JComponent createStopButton​(java.lang.String label)
        Creates a control in the main application window that the user can use to terminate the subprocess. The control will remove itself automatically when the subprocess terminates.
        Parameters:
        label - label text to include on the button; if null the command name will be used
        Returns:
        a control that can be used to stop the subprocess
        Throws:
        java.lang.IllegalStateException - if the subprocess has already been started

      • start

        public void start()
        Starts the subprocess.
        Throws:
        java.lang.IllegalStateException - if the subprocess has already been started

      • stop

        public void stop()
        Stops the process if it is currently running. Otherwise, this method has no effect. In most cases, this thread will wait for the subprocess to finish executing before it returns, but if the subprocess does not exit for some reason, it will give up and return after a timeout period.

      • waitFor

        public void waitFor()
             throws java.lang.InterruptedException
        Waits for the subprocess to end.
        Throws:
        java.lang.InterruptedException - if this thread was interrupted while waiting for the subprocess

      • getExitCode

        public int getExitCode()
        Returns the process's exit code, or -1 if the process has not completed.
        Returns:
        the exit code when the process finished

      • getClasspath

        public static java.lang.String getClasspath()
        Returns the application's class path.
        Returns:
        a list of one or more paths separated by the platform path separator

      • getJavaRuntimeExecutable

        public static java.lang.String getJavaRuntimeExecutable()
        Returns a command that can be used to launch a Java runtime. Where possible, this will be the full path to the specific Java runtime used to start this app. The path is normally detected correctly automatically, but if for some reason detection fails, the user setting invoke-java-cmd can be set to a suitable path.

        For example, on a Windows device on which the app itself was launched with a version of AdoptOpenJDK 8, this might return: 

        C:\Program Files\AdoptOpenJDK\jdk-8.0.292.10-openj9\jre\bin\java.exe
        Returns:
        path to an executable that is expected to launch a separate JVM process