Class CommandOutputControl

java.lang.Object
jdk.jpackage.internal.util.CommandOutputControl
public final class CommandOutputControl extends Object
Runs commands and processes their stdout and stderr streams.

A command is either a subprocess represented by ProcessBuilder or a tool provided by ToolProvider.

A command is executed synchronously, and the result of its execution is stored in a CommandOutputControl.Result instance which captures the exit code and any saved output streams.

Depending on the configuration, it can save the entire output stream, only the first line, or not save the output at all. Stdout and stderr streams can be configured independently.

Output streams can be treated as either byte streams or character streams.

The table below shows how different parameter combinations affect the content written to streams returned by dumpStdout() and dumpStderr() for subsequently executed tools, regardless of whether their output streams are saved, or for subprocesses when the output streams are saved:

discardStdout(false) and discardStderr(false) discardStdout(false) and discardStderr(true) discardStdout(true) and discardStderr(false)
redirectStderr(true) and dumpOutput(true)

dumpStdout(): STDOUT and STDERR interleaved

dumpStderr(): unchanged

dumpStdout(): STDOUT

dumpStderr(): unchanged

dumpStdout(): STDERR;

dumpStderr(): unchanged
redirectStderr(false) and dumpOutput(true)

dumpStdout(): STDOUT

dumpStderr(): STDERR

dumpStdout(): STDOUT

dumpStderr(): unchanged

dumpStdout(): unchanged

dumpStderr(): STDERR

The table below shows how different parameter combinations affect the content written to the native file descriptors associated with System.out and System.err for subsequently executed subprocesses when the output streams are not saved:

discardStdout(false) and discardStderr(false) discardStdout(false) and discardStderr(true) discardStdout(true) and discardStderr(false)
redirectStderr(true) and dumpOutput(true)

System.out: STDOUT and STDERR interleaved

System.err: unchanged

System.out: STDOUT

System.err: unchanged

System.out: STDERR;

The command's STDERR will be written to the stream referenced by dumpStdout() rather than to the underlying file descriptor associated with the Java process's STDOUT

System.err: unchanged
redirectStderr(false) and dumpOutput(true)

System.out: STDOUT

System.err: STDERR

System.out: STDOUT

System.err: unchanged

System.out: unchanged

System.err: STDERR

The table below shows how different parameter combinations affect the properties of CommandOutputControl.Result objects returned by execute(ProcessBuilder, long) or execute(ToolProvider, long, String...) when processing character streams:

saveOutput(true) saveFirstLineOfOutput()
redirectStderr(true) and discardStdout(false) and discardStderr(false)

content(): STDOUT and STDERR interleaved

findStdout(): Optional.empty()

findStderr(): Optional.empty()

content(): a single-item list containing the first line of interleaved STDOUT and STDERR if the command produced any output; otherwise, an empty list

findStdout(): Optional.empty()

findStderr(): Optional.empty()
redirectStderr(false) and discardStdout(false) and discardStderr(false)

content(): STDOUT followed by STDERR

stdout(): STDOUT

stderr(): STDERR

content(): a list containing at most two items: the first line of STDOUT (if the command produced any), followed by the first line of STDERR (if the command produced any)

stdout(): The first line of STDOUT (if the command produced any); otherwise an empty list

findStderr(): The first line of STDERR (if the command produced any); otherwise an empty list

redirectStderr(true) and discardStdout(false) and discardStderr(true)

content(): STDOUT

stdout(): The same as content()

findStderr(): Optional.empty()

content(): The first line of STDOUT (if the command produced any); otherwise an empty list

stdout(): The same as content()

findStderr(): Optional.empty()
redirectStderr(false) and discardStdout(false) and discardStderr(true)

content(): STDOUT

stdout(): The same as content()

stderr(): an empty list

content(): The first line of STDOUT (if the command produced any); otherwise an empty list

stdout(): The same as content()

stderr(): an empty list
redirectStderr(true) and discardStdout(true) and discardStderr(false)

content(): STDERR

stdout(): The same as content()

findStderr(): Optional.empty()

content(): The first line of STDERR (if the command produced any); otherwise an empty list

stdout(): The same as content()

findStderr(): Optional.empty()
redirectStderr(false) and discardStdout(true) and discardStderr(false)

content(): STDERR

findStdout(): an empty list

stderr(): The same as content()

content(): The first line of STDERR (if the command produced any); otherwise an empty list

findStdout(): an empty list

stderr(): The same as content()

The table below shows how different parameter combinations affect the properties of CommandOutputControl.Result objects returned by execute(ProcessBuilder, long) or execute(ToolProvider, long, String...) when processing byte streams:

saveOutput(true) or saveFirstLineOfOutput()
redirectStderr(true) and discardStdout(false) and discardStderr(false)

byteContent(): STDOUT and STDERR interleaved

findByteStdout(): Optional.empty()

findByteStderr(): Optional.empty()
redirectStderr(false) and discardStdout(false) and discardStderr(false)

byteContent(): STDOUT followed by STDERR

byteStdout(): STDOUT

byteStderr(): STDERR
redirectStderr(true) and discardStdout(false) and discardStderr(true)

byteContent(): STDOUT

byteStdout(): The same as byteContent()

findByteStderr(): Optional.empty()
redirectStderr(false) and discardStdout(false) and discardStderr(true)

byteContent(): STDOUT

byteStdout(): The same as byteContent()

byteStderr(): an empty array
redirectStderr(true) and discardStdout(true) and discardStderr(false)

byteContent(): STDERR

byteStdout(): The same as byteContent()

findByteStderr(): Optional.empty()
redirectStderr(false) and discardStdout(true) and discardStderr(false)

byteContent(): STDERR

findByteStdout(): an empty array

byteStderr(): The same as byteContent()

  • Field Details

  • Constructor Details

    • CommandOutputControl

      public CommandOutputControl()

  • Method Details

    • saveOutput

      public CommandOutputControl saveOutput(boolean v)
      Specifies whether the full output produced by commands subsequently executed by this object will be saved.

      If v is true, both stdout and stderr streams will be saved; otherwise, they will not be saved.

      This setting is mutually exclusive with saveFirstLineOfOutput().

      Parameters:
      v - true to save the full stdout and stderr streams; false otherwise
      Returns:
      this

    • isSaveOutput

      public boolean isSaveOutput()
      Returns whether this object will save the complete output of commands subsequently executed.
      Returns:
      true if this object will save the full output of commands it executes subsequently; false otherwise

    • saveFirstLineOfOutput

      public CommandOutputControl saveFirstLineOfOutput()
      Specifies whether the first line of the output, combined from the stdout and stderr streams of commands subsequently executed by this object, will be saved.

      This setting is mutually exclusive with saveOutput(boolean).

      Returns:
      this

    • isSaveFirstLineOfOutput

      public boolean isSaveFirstLineOfOutput()
      Returns whether this object will save the first line of the output of commands subsequently executed.
      Returns:
      true if this object will save the first line of the output of commands it executes subsequently; false otherwise

    • dumpOutput

      public CommandOutputControl dumpOutput(boolean v)
      Specifies whether this object will dump the output streams from subsequently executed commands into the streams returned by dumpStdout() and dumpStdout() methods respectively.

      If this object is configured to redirect stderr of subsequently executed commands into their stdout (redirectStderr(true)), their output streams will be dumped into the stream returned by dumpStdout() method. Otherwise, their stdout and stderr streams will be dumped into the stream returned by dumpStdout() and dumpStderr() methods respectively.

      Parameters:
      v - if output streams from subsequently executed commands will be dumped into streams returned by dumpStdout() and dumpStderr() methods respectively
      Returns:
      this
      See Also:

    • isDumpOutput

      public boolean isDumpOutput()
      Returns the value passed in the last call of dumpOutput(boolean) method on this object, or false if the method has not been called.
      Returns:
      the value passed in the last call of dumpOutput(boolean)

    • binaryOutput

      public CommandOutputControl binaryOutput(boolean v)
      Specifies whether this object will treat output streams of subsequently executed commands as byte streams rather than character streams.
      Parameters:
      v - true if this object will treat the output streams of subsequently executed commands as byte streams, and false otherwise
      Returns:
      this

    • isBinaryOutput

      public boolean isBinaryOutput()
      Returns the value passed in the last call of binaryOutput(boolean) method on this object, or false if the method has not been called.
      Returns:
      the value passed in the last call of binaryOutput(boolean)

    • charset

      public CommandOutputControl charset(Charset v)
      Sets character encoding that will be applied to the stdout and the stderr streams of commands (subprocesses and ToolProvider-s) subsequently executed by this object. The default encoding is UTF-8.

      The value will be ignored if this object is configured for byte output streams.

      Parameters:
      v - character encoding for output streams of subsequently executed commands
      Returns:
      this
      See Also:

    • charset

      public Charset charset()
      Returns the value passed in the last call of charset(Charset) method on this object, or StandardCharsets.UTF_8 if the method has not been called.
      Returns:
      the character encoding that will be applied to the stdout and stderr streams of commands subsequently executed by this object

    • redirectStderr

      public CommandOutputControl redirectStderr(boolean v)
      Specifies whether the stderr stream will be redirected into the stdout stream for commands subsequently executed by this object.
      Parameters:
      v - true if the stderr stream of commands subsequently executed by this object will be redirected into the stdout stream; false otherwise
      Returns:
      this
      See Also:

    • isRedirectStderr

      public boolean isRedirectStderr()
      Returns the value passed in the last call of redirectStderr(boolean) method on this object, or false if the method has not been called.
      Returns:
      the value passed in the last call of redirectStderr(boolean)

    • storeOutputInFiles

      public CommandOutputControl storeOutputInFiles(boolean v)
      Specifies whether stderr and stdout streams for subprocesses subsequently executed by this object will be stored in files.

      By default, if an output stream of a subprocess is configured for saving, this object will retrieve the content using Process.getInputStream() function for stdout and Process.getErrorStream() function for stderr. However, these functions don't always work correctly due to a JDK-8236825 bug still reproducible on macOS JDK26. The alternative way to get the content of output streams of a subprocess is to redirect them into files and read these files when the subprocess terminates.

      It will use Files.createTempFile("jpackageOutputTempFile", ".tmp") to create a file for each subprocess's output stream configured for saving. All created files will be automatically deleted at the exit of execute(ProcessBuilder, long) method.

      Doesn't apply to executing ToolProvider-s.

      Storing output streams in files takes longer than managing them in memory and should be avoided if possible.

      Parameters:
      v - true if this object will use files to store saved output streams of subsequently executed subprocesses; false otherwise
      Returns:
      this

    • isStoreOutputInFiles

      public boolean isStoreOutputInFiles()
      Returns the value passed in the last call of storeOutputInFiles(boolean) method on this object, or false if the method has not been called.
      Returns:
      the value passed in the last call of storeOutputInFiles(boolean)

    • discardStdout

      public CommandOutputControl discardStdout(boolean v)
      Specifies whether stdout streams from commands subsequently executed by this object will be discarded.
      Parameters:
      v - true if this object will discard stdout streams from commands subsequently executed by this object; false otherwise
      Returns:
      this

    • isDiscardStdout

      public boolean isDiscardStdout()
      Returns the value passed in the last call of discardStdout(boolean) method on this object, or false if the method has not been called.
      Returns:
      the value passed in the last call of discardStdout(boolean)

    • discardStderr

      public CommandOutputControl discardStderr(boolean v)
      Specifies whether stderr streams from commands subsequently executed by this object will be discarded.
      Parameters:
      v - true if this object will discard stderr streams from commands subsequently executed by this object; false otherwise
      Returns:
      this

    • isDiscardStderr

      public boolean isDiscardStderr()
      Returns the value passed in the last call of discardStderr(boolean) method on this object, or false if the method has not been called.
      Returns:
      the value passed in the last call of discardStderr(boolean)

    • dumpStdout

      public CommandOutputControl dumpStdout(PrintStream v)
      Specifies the stream where stdout streams from commands subsequently executed by this object will be dumped.

      If the null is specified and this object configuration is equivalent to dumpOutput(true).saveOutput(false).discardStdout(false) the stdout streams from commands subsequently executed by this object will be written into the file descriptor associated with the Systsem.out stream. If you want them to be written into the Systsem.out object, pass the Systsem.out reference into this function.

      Parameters:
      v - the stream where stdout streams from commands subsequently executed by this object will be dumped; null permitted
      Returns:
      this

    • dumpStdout

      public PrintStream dumpStdout()
      Returns the value passed in the last call of dumpStdout(PrintStream) method on this object, or System.out if the method has not been called.
      Returns:
      the stream where stdout streams from commands subsequently executed by this object will be dumped

    • dumpStderr

      public CommandOutputControl dumpStderr(PrintStream v)
      Specifies the stream where stderr streams from commands subsequently executed by this object will be dumped.

      If the null is specified and this object configuration is equivalent to dumpOutput(true).saveOutput(false).redirectStderr(false).discardStderr(false) the stderr streams from commands subsequently executed by this object will be written into the file descriptor associated with the Systsem.err stream. If you want them to be written into the Systsem.err object, pass the Systsem.err reference into this function.

      Parameters:
      v - the stream where stderr streams from commands subsequently executed by this object will be dumped; null permitted
      Returns:
      this

    • dumpStderr

      public PrintStream dumpStderr()
      Returns the value passed in the last call of dumpStderr(PrintStream) method on this object, or System.err if the method has not been called.
      Returns:
      the stream where stderr streams from commands subsequently executed by this object will be dumped

    • processListener

      public CommandOutputControl processListener(Consumer<Process> v)
      Sets the callback to be invoked when this object starts a subprocess from subsequent execute(ProcessBuilder, long) calls.

      This object maintains a single callback. Calling this method replaces any previously set callback.

      The callback is invoked on the thread that calls execute(ProcessBuilder, long) after the subprocess's output streams begin being pumped.

      Parameters:
      v - the callback for notifying a subprocess being started or null
      Returns:
      this

    • processListener

      public Optional<Consumer<Process>> processListener()
      Returns an Optional wrapping the value passed in the last call of processListener(Consumer) method on this object, or an empty Optional if the method has not been called or null was passed in the last call.
      Returns:
      an Optional wrapping the value passed in the last call of processListener(Consumer)

    • copy

      public CommandOutputControl copy()
      Returns a deep copy of this object. Changes to the copy will not affect the original.
      Returns:
      a deep copy of this object

    • createExecutable

      public CommandOutputControl.Executable createExecutable(ToolProvider tp, String... args)

    • createExecutable

      public CommandOutputControl.Executable createExecutable(ProcessBuilder pb)

    • description

      public String description()