|
FlexDoc/Javadoc 2.0 Demo Java Doc |
The methods that create processes may not work well for special processes on certain native platforms, such as native windowing processes, daemon processes, Win16/DOS processes on Microsoft Windows, or shell scripts.
By default, the created process does not have its own terminal or console. All its standard I/O (i.e. stdin, stdout, stderr) operations will be redirected to the parent process, where they can be accessed via the streams obtained using the methods getOutputStream(), getInputStream(), and getErrorStream(). The I/O streams of characters and lines can be written and read using the methods outputWriter(), outputWriter(Charset)}, inputReader(), inputReader(Charset), errorReader(), and errorReader(Charset). The parent process uses these streams to feed input to and get output from the process. Because some native platforms only provide limited buffer size for standard input and output streams, failure to promptly write the input stream or read the output stream of the process may cause the process to block, or even deadlock.
Where desired, process I/O can also be redirected using methods of the ProcessBuilder class.
The process is not killed when there are no more references to the Process object, but rather the process continues executing asynchronously.
There is no requirement that the process represented by a Process object execute asynchronously or concurrently with respect to the Java process that owns the Process object.
As of 1.5, ProcessBuilder.start() is the preferred way to create a Process.
Subclasses of Process should override the onExit() and toHandle() methods to provide a fully functional Process including the process id, information about the process, direct children, and direct children plus descendants of those children of the process. Delegating to the underlying Process or ProcessHandle is typically easiest and most efficient.
Constructor Summary |
||
Process()
Default constructor for Process.
|
Method Summary |
||
children()
Returns a snapshot of the direct children of the process.
|
||
Returns a snapshot of the descendants of the process.
|
||
abstract void |
destroy()
Kills the process.
|
|
Kills the process forcibly.
|
||
final BufferedReader |
Returns a BufferedReader connected to the standard
error of the process.
|
|
final BufferedReader |
errorReader(Charset charset)
Returns a BufferedReader connected to the
standard error of this process using a Charset.
|
|
abstract int |
Returns the exit value for the process.
|
|
abstract InputStream |
Returns the input stream connected to the error output of the
process.
|
|
abstract InputStream |
Returns the input stream connected to the normal output of the
process.
|
|
abstract OutputStream |
Returns the output stream connected to the normal input of the
process.
|
|
info()
Returns a snapshot of information about the process.
|
||
final BufferedReader |
Returns a BufferedReader connected to the standard
output of the process.
|
|
final BufferedReader |
inputReader(Charset charset)
Returns a BufferedReader connected to the
standard output of this process using a Charset.
|
|
boolean |
isAlive()
Tests whether the process represented by this Process is
alive.
|
|
onExit()
Returns a CompletableFuture<Process> for the termination of the Process.
|
||
final BufferedWriter |
Returns a BufferedWriter connected to the normal input of the process
using the native encoding.
|
|
final BufferedWriter |
outputWriter(Charset charset)
Returns a BufferedWriter connected to the normal input of the process
using a Charset.
|
|
long |
pid()
Returns the native process ID of the process.
|
|
boolean |
Returns true if the implementation of destroy() is to
normally terminate the process,
Returns false if the implementation of destroy
forcibly and immediately terminates the process.
|
|
toHandle()
Returns a ProcessHandle for the Process.
|
||
abstract int |
waitFor()
Causes the current thread to wait, if necessary, until the
process represented by this Process object has
terminated.
|
|
boolean |
Causes the current thread to wait, if necessary, until the
process represented by this Process object has
terminated, or the specified waiting time elapses.
|
Methods inherited from class java.lang.Object |
public Process |
() |
public abstract OutputStream getOutputStream |
() |
If the standard input of the process has been redirected using ProcessBuilder.redirectInput then this method will return a null output stream.
public abstract InputStream getInputStream |
() |
If the standard output of the process has been redirected using ProcessBuilder.redirectOutput then this method will return a null input stream.
Otherwise, if the standard error of the process has been redirected using ProcessBuilder.redirectErrorStream then the input stream returned by this method will receive the merged standard output and the standard error of the process.
public abstract InputStream getErrorStream |
() |
If the standard error of the process has been redirected using ProcessBuilder.redirectError or ProcessBuilder.redirectErrorStream then this method will return a null input stream.
public final BufferedReader inputReader |
() |
This method delegates to inputReader(Charset) using the Charset named by the native.encoding system property. If the native.encoding is not a valid charset name or not supported the Charset.defaultCharset() is used.
public final BufferedReader inputReader |
(Charset charset) |
Characters are read by an InputStreamReader that reads and decodes bytes from this process getInputStream(). Bytes are decoded to characters using the charset; malformed-input and unmappable-character sequences are replaced with the charset's default replacement. The BufferedReader reads and buffers characters from the InputStreamReader.
The first call to this method creates the BufferedReader, if called again with the same charset the same BufferedReader is returned. It is an error to call this method again with a different charset.
If the standard output of the process has been redirected using ProcessBuilder.redirectOutput then the InputStreamReader will be reading from a null input stream.
Otherwise, if the standard error of the process has been redirected using ProcessBuilder.redirectErrorStream then the input reader returned by this method will receive the merged standard output and the standard error of the process.
public final BufferedReader errorReader |
() |
This method delegates to errorReader(Charset) using the Charset named by the native.encoding system property. If the native.encoding is not a valid charset name or not supported the Charset.defaultCharset() is used.
public final BufferedReader errorReader |
(Charset charset) |
Characters are read by an InputStreamReader that reads and decodes bytes from this process getErrorStream(). Bytes are decoded to characters using the charset; malformed-input and unmappable-character sequences are replaced with the charset's default replacement. The BufferedReader reads and buffers characters from the InputStreamReader.
The first call to this method creates the BufferedReader, if called again with the same charset the same BufferedReader is returned. It is an error to call this method again with a different charset.
If the standard error of the process has been redirected using ProcessBuilder.redirectError or ProcessBuilder.redirectErrorStream then the InputStreamReader will be reading from a null input stream.
public final BufferedWriter outputWriter |
() |
This method delegates to outputWriter(Charset) using the Charset named by the native.encoding system property. If the native.encoding is not a valid charset name or not supported the Charset.defaultCharset() is used.
public final BufferedWriter outputWriter |
(Charset charset) |
Characters written by the writer are encoded to bytes using OutputStreamWriter and the Charset are written to the standard input of the process represented by this Process. Malformed-input and unmappable-character sequences are replaced with the charset's default replacement.
The first call to this method creates the BufferedWriter, if called again with the same charset the same BufferedWriter is returned. It is an error to call this method again with a different charset.
If the standard input of the process has been redirected using ProcessBuilder.redirectInput then the OutputStreamWriter writes to a null output stream.
public abstract int waitFor |
() |
throws |
public boolean waitFor |
(long timeout, TimeUnit unit) |
throws |
If the process has already terminated then this method returns immediately with the value true. If the process has not terminated and the timeout value is less than, or equal to, zero, then this method returns immediately with the value false.
The default implementation of this methods polls the exitValue to check if the process has terminated. Concrete implementations of this class are strongly encouraged to override this method with a more efficient implementation.
public abstract int exitValue |
() |
public abstract void destroy |
() |
The CompletableFuture from onExit() is completed when the process has terminated.
public Process destroyForcibly |
() |
The CompletableFuture from onExit() is completed when the process has terminated.
Invoking this method on Process objects returned by ProcessBuilder.start() and Runtime.exec(String) forcibly terminate the process.
public boolean supportsNormalTermination |
() |
Invoking this method on Process objects returned by ProcessBuilder.start() and Runtime.exec(String) return true or false depending on the platform implementation.
public boolean isAlive |
() |
public long pid |
() |
() |
Calling onExit().get() waits for the process to terminate and returns the Process. The future can be used to check if the process is done or to wait for it to terminate. Cancelling the CompletableFuture does not affect the Process.
Processes returned from ProcessBuilder.start() override the default implementation to provide an efficient mechanism to wait for process exit.
When waitFor() returns successfully the CompletableFuture is completed regardless of the exit status of the process. This implementation may consume a lot of memory for thread stacks if a large number of processes are waited for concurrently.
External implementations should override this method and provide a more efficient implementation. For example, to delegate to the underlying process, it can do the following:
public CompletableFuture<Process> onExit() {
return delegate.onExit().thenApply(p -> this);
}
public ProcessHandle toHandle |
() |
public ProcessHandle.Info info |
() |
A ProcessHandle.Info instance has accessor methods that return information about the process if it is available.
() |
Note that processes are created and terminate asynchronously. There is no guarantee that a process is alive.
() |
Note that processes are created and terminate asynchronously. There is no guarantee that a process is alive.
|
FlexDoc/Javadoc 2.0 Demo Java Doc |