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 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
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 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():
findStderr(): |
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():
findStderr(): |
| 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(): |
content(): The first line of STDOUT (if the command produced any); otherwise an empty list stdout(): The same as content()
findStderr(): |
| 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(): |
content(): The first line of STDERR (if the command produced any); otherwise an empty list stdout(): The same as content()
findStderr(): |
| 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 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():
findByteStderr(): |
| 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(): |
| 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(): |
| redirectStderr(false) and discardStdout(true) and discardStderr(false) |
byteContent(): STDERR findByteStdout(): an empty array byteStderr(): The same as byteContent() |
| Modifier and Type | Class and Description |
|---|---|
| private static record | |
| private static record | |
| private class | |
| private static record | |
| private static interface | |
| public static interface | |
| public static interface | |
| private static enum | |
| private static class | |
| private static enum | |
| private static record | |
| public static record | |
| private static record | |
| public static record | |
| private static record | |
| public static record | |
| private static record | |
| public static class | |
| public static class | |
| public static class |
| Modifier and Type | Field and Description |
|---|---|
| private Charset | |
| private PrintStream | |
| private PrintStream | |
| public static CommandOutputControl. | |
| private int | |
| private final Executor | |
| private final CommandOutputControl. | |
| private Consumer |
| Access | Constructor and Description |
|---|---|
| public | |
| private |
| Modifier and Type | Method and Description |
|---|---|
| public CommandOutputControl | Returns: thistrue if this object will treat the output streams of
subsequently executed commands as byte streams, and false
otherwiseSpecifies whether this object will treat output streams of subsequently executed commands as byte streams rather than character streams. |
| public CommandOutputControl | |
| public Charset | Returns: the character encoding that will be applied to the stdout and stderr streams of commands subsequently executed by this objectReturns the value passed in the last call of
|
| private static <T> CommandOutputControl. | combine(Optional<? extends CommandOutputControl.
|
| private void | |
| public CommandOutputControl | |
| public CommandOutputControl. | |
| public CommandOutputControl. | |
| public String | |
| public CommandOutputControl | Returns: thistrue if this object will discard stderr streams from
commands subsequently executed by this object; false
otherwiseSpecifies whether stderr streams from commands subsequently executed by this object will be discarded. |
| public CommandOutputControl | Returns: thistrue if this object will discard stdout streams from
commands subsequently executed by this object; false
otherwiseSpecifies whether stdout streams from commands subsequently executed by this object will be discarded. |
| public CommandOutputControl | Returns: thisif output streams from subsequently executed commands will be
dumped into streams returned by v)dumpStdout() and
dumpStderr() methods respectivelySpecifies whether this object will dump the output streams from
subsequently executed commands into the streams returned by
|
| public CommandOutputControl | Returns: thisthe stream where stderr streams from commands subsequently executed
by this object will be dumped; v)null permittedSpecifies the stream where stderr streams from commands subsequently executed by this object will be dumped. |
| public PrintStream | Returns: the stream where stderr streams from commands subsequently executed by this object will be dumpedReturns the value passed in the last call of |
| public CommandOutputControl | Returns: thisthe stream where stdout streams from commands subsequently executed
by this object will be dumped; v)null permittedSpecifies the stream where stdout streams from commands subsequently executed by this object will be dumped. |
| public PrintStream | Returns: the stream where stdout streams from commands subsequently executed by this object will be dumpedReturns the value passed in the last call of |
| private CommandOutputControl. | |
| private CommandOutputControl. | |
| private static Optional | |
| public boolean | Returns: the value passed in the last call ofbinaryOutput(boolean)Returns the value passed in the last call of |
| public boolean | Returns: the value passed in the last call ofdiscardStderr(boolean)Returns the value passed in the last call of |
| public boolean | Returns: the value passed in the last call ofdiscardStdout(boolean)Returns the value passed in the last call of |
| public boolean | Returns: the value passed in the last call ofdumpOutput(boolean)Returns the value passed in the last call of |
| public boolean | Returns: the value passed in the last call ofredirectStderr(boolean)Returns the value passed in the last call of |
| public boolean | Returns: true if this object will save the first line of the output of
commands it executes subsequently; false otherwiseReturns whether this object will save the first line of the output of commands subsequently executed. |
| public boolean | Returns: true if this object will save the full output of commands it
executes subsequently; false otherwiseReturns whether this object will save the complete output of commands subsequently executed. |
| public boolean | Returns: the value passed in the last call ofstoreOutputInFiles(boolean)Returns the value passed in the last call of |
| private static <T> T | |
| private static void | |
| private ProcessBuilder. | |
| private static boolean | |
| private static PrintStream | |
| public CommandOutputControl | Returns: thisthe callback for notifying a subprocess being started or
v)nullSets the callback to be invoked when this object starts a subprocess from
subsequent |
| public Optional | processListener()
Returns an |
| private static Optional | |
| private static Optional | readBinary(CommandOutputControl.
|
| private boolean | redirectRetainedStderr()
Returns |
| public CommandOutputControl | Returns: thistrue if the stderr stream of commands subsequently executed
by this object will be redirected into the stdout stream;
false otherwiseSpecifies whether the stderr stream will be redirected into the stdout stream for commands subsequently executed by this object. |
| private boolean | |
| public CommandOutputControl | Returns: thisSpecifies whether the first line of the output, combined from the stdout and stderr streams of commands subsequently executed by this object, will be saved. |
| public CommandOutputControl | Returns: thistrue to save the full stdout and stderr streams;
false otherwiseSpecifies whether the full output produced by commands subsequently executed by this object will be saved. |
| private CommandOutputControl | |
| private CommandOutputControl | |
| public CommandOutputControl | Returns: thistrue if this object will use files to store saved output
streams of subsequently executed subprocesses; false
otherwiseSpecifies whether stderr and stdout streams for subprocesses subsequently executed by this object will be stored in files. |
| private Optional | |
| private static void | |
| private static <T> void |
