593 lines
24 KiB
Java
593 lines
24 KiB
Java
/*
|
|
* Copyright (c) 1995, 2019, Oracle and/or its affiliates. All rights reserved.
|
|
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
|
*
|
|
* This code is free software; you can redistribute it and/or modify it
|
|
* under the terms of the GNU General Public License version 2 only, as
|
|
* published by the Free Software Foundation. Oracle designates this
|
|
* particular file as subject to the "Classpath" exception as provided
|
|
* by Oracle in the LICENSE file that accompanied this code.
|
|
*
|
|
* This code is distributed in the hope that it will be useful, but WITHOUT
|
|
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
|
* version 2 for more details (a copy is included in the LICENSE file that
|
|
* accompanied this code).
|
|
*
|
|
* You should have received a copy of the GNU General Public License version
|
|
* 2 along with this work; if not, write to the Free Software Foundation,
|
|
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
|
|
*
|
|
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
|
|
* or visit www.oracle.com if you need additional information or have any
|
|
* questions.
|
|
*/
|
|
|
|
package java.lang;
|
|
|
|
import java.io.*;
|
|
import java.lang.ProcessBuilder.Redirect;
|
|
import java.util.concurrent.CompletableFuture;
|
|
import java.util.concurrent.ForkJoinPool;
|
|
import java.util.concurrent.TimeUnit;
|
|
import java.util.stream.Stream;
|
|
|
|
/**
|
|
* {@code Process} provides control of native processes started by
|
|
* ProcessBuilder.start and Runtime.exec.
|
|
* The class provides methods for performing input from the process, performing
|
|
* output to the process, waiting for the process to complete,
|
|
* checking the exit status of the process, and destroying (killing)
|
|
* the process.
|
|
* The {@link ProcessBuilder#start()} and
|
|
* {@link Runtime#exec(String[],String[],File) Runtime.exec}
|
|
* methods create a native process and return an instance of a
|
|
* subclass of {@code Process} that can be used to control the process
|
|
* and obtain information about it.
|
|
*
|
|
* <p>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.
|
|
*
|
|
* <p>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
|
|
* {@link #getOutputStream()},
|
|
* {@link #getInputStream()}, and
|
|
* {@link #getErrorStream()}.
|
|
* 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.
|
|
*
|
|
* <p>Where desired, <a href="ProcessBuilder.html#redirect-input">
|
|
* process I/O can also be redirected</a>
|
|
* using methods of the {@link ProcessBuilder} class.
|
|
*
|
|
* <p>The process is not killed when there are no more references to
|
|
* the {@code Process} object, but rather the process
|
|
* continues executing asynchronously.
|
|
*
|
|
* <p>There is no requirement that the process represented by a {@code
|
|
* Process} object execute asynchronously or concurrently with respect
|
|
* to the Java process that owns the {@code Process} object.
|
|
*
|
|
* <p>As of 1.5, {@link ProcessBuilder#start()} is the preferred way
|
|
* to create a {@code Process}.
|
|
*
|
|
* <p>Subclasses of Process should override the {@link #onExit()} and
|
|
* {@link #toHandle()} methods to provide a fully functional Process including the
|
|
* {@linkplain #pid() process id},
|
|
* {@linkplain #info() information about the process},
|
|
* {@linkplain #children() direct children}, and
|
|
* {@linkplain #descendants() direct children plus descendants of those children} of the process.
|
|
* Delegating to the underlying Process or ProcessHandle is typically
|
|
* easiest and most efficient.
|
|
*
|
|
* @since 1.0
|
|
*/
|
|
public abstract class Process {
|
|
/**
|
|
* Default constructor for Process.
|
|
*/
|
|
public Process() {}
|
|
|
|
/**
|
|
* Returns the output stream connected to the normal input of the
|
|
* process. Output to the stream is piped into the standard
|
|
* input of the process represented by this {@code Process} object.
|
|
*
|
|
* <p>If the standard input of the process has been redirected using
|
|
* {@link ProcessBuilder#redirectInput(Redirect)
|
|
* ProcessBuilder.redirectInput}
|
|
* then this method will return a
|
|
* <a href="ProcessBuilder.html#redirect-input">null output stream</a>.
|
|
*
|
|
* <p>Implementation note: It is a good idea for the returned
|
|
* output stream to be buffered.
|
|
*
|
|
* @return the output stream connected to the normal input of the
|
|
* process
|
|
*/
|
|
public abstract OutputStream getOutputStream();
|
|
|
|
/**
|
|
* Returns the input stream connected to the normal output of the
|
|
* process. The stream obtains data piped from the standard
|
|
* output of the process represented by this {@code Process} object.
|
|
*
|
|
* <p>If the standard output of the process has been redirected using
|
|
* {@link ProcessBuilder#redirectOutput(Redirect)
|
|
* ProcessBuilder.redirectOutput}
|
|
* then this method will return a
|
|
* <a href="ProcessBuilder.html#redirect-output">null input stream</a>.
|
|
*
|
|
* <p>Otherwise, if the standard error of the process has been
|
|
* redirected using
|
|
* {@link ProcessBuilder#redirectErrorStream(boolean)
|
|
* ProcessBuilder.redirectErrorStream}
|
|
* then the input stream returned by this method will receive the
|
|
* merged standard output and the standard error of the process.
|
|
*
|
|
* <p>Implementation note: It is a good idea for the returned
|
|
* input stream to be buffered.
|
|
*
|
|
* @return the input stream connected to the normal output of the
|
|
* process
|
|
*/
|
|
public abstract InputStream getInputStream();
|
|
|
|
/**
|
|
* Returns the input stream connected to the error output of the
|
|
* process. The stream obtains data piped from the error output
|
|
* of the process represented by this {@code Process} object.
|
|
*
|
|
* <p>If the standard error of the process has been redirected using
|
|
* {@link ProcessBuilder#redirectError(Redirect)
|
|
* ProcessBuilder.redirectError} or
|
|
* {@link ProcessBuilder#redirectErrorStream(boolean)
|
|
* ProcessBuilder.redirectErrorStream}
|
|
* then this method will return a
|
|
* <a href="ProcessBuilder.html#redirect-output">null input stream</a>.
|
|
*
|
|
* <p>Implementation note: It is a good idea for the returned
|
|
* input stream to be buffered.
|
|
*
|
|
* @return the input stream connected to the error output of
|
|
* the process
|
|
*/
|
|
public abstract InputStream getErrorStream();
|
|
|
|
/**
|
|
* Causes the current thread to wait, if necessary, until the
|
|
* process represented by this {@code Process} object has
|
|
* terminated. This method returns immediately if the process
|
|
* has already terminated. If the process has not yet
|
|
* terminated, the calling thread will be blocked until the
|
|
* process exits.
|
|
*
|
|
* @return the exit value of the process represented by this
|
|
* {@code Process} object. By convention, the value
|
|
* {@code 0} indicates normal termination.
|
|
* @throws InterruptedException if the current thread is
|
|
* {@linkplain Thread#interrupt() interrupted} by another
|
|
* thread while it is waiting, then the wait is ended and
|
|
* an {@link InterruptedException} is thrown.
|
|
*/
|
|
public abstract int waitFor() throws InterruptedException;
|
|
|
|
/**
|
|
* Causes the current thread to wait, if necessary, until the
|
|
* process represented by this {@code Process} object has
|
|
* terminated, or the specified waiting time elapses.
|
|
*
|
|
* <p>If the process has already terminated then this method returns
|
|
* immediately with the value {@code 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 {@code false}.
|
|
*
|
|
* <p>The default implementation of this methods polls the {@code 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.
|
|
*
|
|
* @param timeout the maximum time to wait
|
|
* @param unit the time unit of the {@code timeout} argument
|
|
* @return {@code true} if the process has exited and {@code false} if
|
|
* the waiting time elapsed before the process has exited.
|
|
* @throws InterruptedException if the current thread is interrupted
|
|
* while waiting.
|
|
* @throws NullPointerException if unit is null
|
|
* @since 1.8
|
|
*/
|
|
public boolean waitFor(long timeout, TimeUnit unit)
|
|
throws InterruptedException
|
|
{
|
|
long remainingNanos = unit.toNanos(timeout); // throw NPE before other conditions
|
|
if (hasExited())
|
|
return true;
|
|
if (timeout <= 0)
|
|
return false;
|
|
|
|
long deadline = System.nanoTime() + remainingNanos;
|
|
do {
|
|
Thread.sleep(Math.min(TimeUnit.NANOSECONDS.toMillis(remainingNanos) + 1, 100));
|
|
if (hasExited())
|
|
return true;
|
|
remainingNanos = deadline - System.nanoTime();
|
|
} while (remainingNanos > 0);
|
|
|
|
return false;
|
|
}
|
|
|
|
/**
|
|
* Returns the exit value for the process.
|
|
*
|
|
* @return the exit value of the process represented by this
|
|
* {@code Process} object. By convention, the value
|
|
* {@code 0} indicates normal termination.
|
|
* @throws IllegalThreadStateException if the process represented
|
|
* by this {@code Process} object has not yet terminated
|
|
*/
|
|
public abstract int exitValue();
|
|
|
|
/**
|
|
* Kills the process.
|
|
* Whether the process represented by this {@code Process} object is
|
|
* {@linkplain #supportsNormalTermination normally terminated} or not is
|
|
* implementation dependent.
|
|
* Forcible process destruction is defined as the immediate termination of a
|
|
* process, whereas normal termination allows the process to shut down cleanly.
|
|
* If the process is not alive, no action is taken.
|
|
* <p>
|
|
* The {@link java.util.concurrent.CompletableFuture} from {@link #onExit} is
|
|
* {@linkplain java.util.concurrent.CompletableFuture#complete completed}
|
|
* when the process has terminated.
|
|
*/
|
|
public abstract void destroy();
|
|
|
|
/**
|
|
* Kills the process forcibly. The process represented by this
|
|
* {@code Process} object is forcibly terminated.
|
|
* Forcible process destruction is defined as the immediate termination of a
|
|
* process, whereas normal termination allows the process to shut down cleanly.
|
|
* If the process is not alive, no action is taken.
|
|
* <p>
|
|
* The {@link java.util.concurrent.CompletableFuture} from {@link #onExit} is
|
|
* {@linkplain java.util.concurrent.CompletableFuture#complete completed}
|
|
* when the process has terminated.
|
|
* <p>
|
|
* Invoking this method on {@code Process} objects returned by
|
|
* {@link ProcessBuilder#start} and {@link Runtime#exec} forcibly terminate
|
|
* the process.
|
|
*
|
|
* @implSpec
|
|
* The default implementation of this method invokes {@link #destroy}
|
|
* and so may not forcibly terminate the process.
|
|
* @implNote
|
|
* Concrete implementations of this class are strongly encouraged to override
|
|
* this method with a compliant implementation.
|
|
* @apiNote
|
|
* The process may not terminate immediately.
|
|
* i.e. {@code isAlive()} may return true for a brief period
|
|
* after {@code destroyForcibly()} is called. This method
|
|
* may be chained to {@code waitFor()} if needed.
|
|
*
|
|
* @return the {@code Process} object representing the
|
|
* process forcibly destroyed
|
|
* @since 1.8
|
|
*/
|
|
public Process destroyForcibly() {
|
|
destroy();
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Returns {@code true} if the implementation of {@link #destroy} is to
|
|
* normally terminate the process,
|
|
* Returns {@code false} if the implementation of {@code destroy}
|
|
* forcibly and immediately terminates the process.
|
|
* <p>
|
|
* Invoking this method on {@code Process} objects returned by
|
|
* {@link ProcessBuilder#start} and {@link Runtime#exec} return
|
|
* {@code true} or {@code false} depending on the platform implementation.
|
|
*
|
|
* @implSpec
|
|
* This implementation throws an instance of
|
|
* {@link java.lang.UnsupportedOperationException} and performs no other action.
|
|
*
|
|
* @return {@code true} if the implementation of {@link #destroy} is to
|
|
* normally terminate the process;
|
|
* otherwise, {@link #destroy} forcibly terminates the process
|
|
* @throws UnsupportedOperationException if the Process implementation
|
|
* does not support this operation
|
|
* @since 9
|
|
*/
|
|
public boolean supportsNormalTermination() {
|
|
throw new UnsupportedOperationException(this.getClass()
|
|
+ ".supportsNormalTermination() not supported" );
|
|
}
|
|
|
|
/**
|
|
* Tests whether the process represented by this {@code Process} is
|
|
* alive.
|
|
*
|
|
* @return {@code true} if the process represented by this
|
|
* {@code Process} object has not yet terminated.
|
|
* @since 1.8
|
|
*/
|
|
public boolean isAlive() {
|
|
return !hasExited();
|
|
}
|
|
|
|
/**
|
|
* This is called from the default implementation of
|
|
* {@code waitFor(long, TimeUnit)}, which is specified to poll
|
|
* {@code exitValue()}.
|
|
*/
|
|
private boolean hasExited() {
|
|
try {
|
|
exitValue();
|
|
return true;
|
|
} catch (IllegalThreadStateException e) {
|
|
return false;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Returns the native process ID of the process.
|
|
* The native process ID is an identification number that the operating
|
|
* system assigns to the process.
|
|
*
|
|
* @implSpec
|
|
* The implementation of this method returns the process id as:
|
|
* {@link #toHandle toHandle().pid()}.
|
|
*
|
|
* @return the native process id of the process
|
|
* @throws UnsupportedOperationException if the Process implementation
|
|
* does not support this operation
|
|
* @since 9
|
|
*/
|
|
public long pid() {
|
|
return toHandle().pid();
|
|
}
|
|
|
|
/**
|
|
* Returns a {@code CompletableFuture<Process>} for the termination of the Process.
|
|
* The {@link java.util.concurrent.CompletableFuture} provides the ability
|
|
* to trigger dependent functions or actions that may be run synchronously
|
|
* or asynchronously upon process termination.
|
|
* When the process has terminated the CompletableFuture is
|
|
* {@link java.util.concurrent.CompletableFuture#complete completed} regardless
|
|
* of the exit status of the process.
|
|
* <p>
|
|
* Calling {@code onExit().get()} waits for the process to terminate and returns
|
|
* the Process. The future can be used to check if the process is
|
|
* {@linkplain java.util.concurrent.CompletableFuture#isDone done} or to
|
|
* {@linkplain java.util.concurrent.CompletableFuture#get() wait} for it to terminate.
|
|
* {@linkplain java.util.concurrent.CompletableFuture#cancel(boolean) Cancelling}
|
|
* the CompletableFuture does not affect the Process.
|
|
* <p>
|
|
* Processes returned from {@link ProcessBuilder#start} override the
|
|
* default implementation to provide an efficient mechanism to wait
|
|
* for process exit.
|
|
*
|
|
* @apiNote
|
|
* Using {@link #onExit() onExit} is an alternative to
|
|
* {@link #waitFor() waitFor} that enables both additional concurrency
|
|
* and convenient access to the result of the Process.
|
|
* Lambda expressions can be used to evaluate the result of the Process
|
|
* execution.
|
|
* If there is other processing to be done before the value is used
|
|
* then {@linkplain #onExit onExit} is a convenient mechanism to
|
|
* free the current thread and block only if and when the value is needed.
|
|
* <br>
|
|
* For example, launching a process to compare two files and get a boolean if they are identical:
|
|
* <pre> {@code Process p = new ProcessBuilder("cmp", "f1", "f2").start();
|
|
* Future<Boolean> identical = p.onExit().thenApply(p1 -> p1.exitValue() == 0);
|
|
* ...
|
|
* if (identical.get()) { ... }
|
|
* }</pre>
|
|
*
|
|
* @implSpec
|
|
* This implementation executes {@link #waitFor()} in a separate thread
|
|
* repeatedly until it returns successfully. If the execution of
|
|
* {@code waitFor} is interrupted, the thread's interrupt status is preserved.
|
|
* <p>
|
|
* When {@link #waitFor()} returns successfully the CompletableFuture is
|
|
* {@linkplain java.util.concurrent.CompletableFuture#complete 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.
|
|
* <p>
|
|
* 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:
|
|
* <pre>{@code
|
|
* public CompletableFuture<Process> onExit() {
|
|
* return delegate.onExit().thenApply(p -> this);
|
|
* }
|
|
* }</pre>
|
|
* @apiNote
|
|
* The process may be observed to have terminated with {@link #isAlive}
|
|
* before the ComputableFuture is completed and dependent actions are invoked.
|
|
*
|
|
* @return a new {@code CompletableFuture<Process>} for the Process
|
|
*
|
|
* @since 9
|
|
*/
|
|
public CompletableFuture<Process> onExit() {
|
|
return CompletableFuture.supplyAsync(this::waitForInternal);
|
|
}
|
|
|
|
/**
|
|
* Wait for the process to exit by calling {@code waitFor}.
|
|
* If the thread is interrupted, remember the interrupted state to
|
|
* be restored before returning. Use ForkJoinPool.ManagedBlocker
|
|
* so that the number of workers in case ForkJoinPool is used is
|
|
* compensated when the thread blocks in waitFor().
|
|
*
|
|
* @return the Process
|
|
*/
|
|
private Process waitForInternal() {
|
|
boolean interrupted = false;
|
|
while (true) {
|
|
try {
|
|
ForkJoinPool.managedBlock(new ForkJoinPool.ManagedBlocker() {
|
|
@Override
|
|
public boolean block() throws InterruptedException {
|
|
waitFor();
|
|
return true;
|
|
}
|
|
|
|
@Override
|
|
public boolean isReleasable() {
|
|
return !isAlive();
|
|
}
|
|
});
|
|
break;
|
|
} catch (InterruptedException x) {
|
|
interrupted = true;
|
|
}
|
|
}
|
|
if (interrupted) {
|
|
Thread.currentThread().interrupt();
|
|
}
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Returns a ProcessHandle for the Process.
|
|
*
|
|
* {@code Process} objects returned by {@link ProcessBuilder#start} and
|
|
* {@link Runtime#exec} implement {@code toHandle} as the equivalent of
|
|
* {@link ProcessHandle#of(long) ProcessHandle.of(pid)} including the
|
|
* check for a SecurityManager and {@code RuntimePermission("manageProcess")}.
|
|
*
|
|
* @implSpec
|
|
* This implementation throws an instance of
|
|
* {@link java.lang.UnsupportedOperationException} and performs no other action.
|
|
* Subclasses should override this method to provide a ProcessHandle for the
|
|
* process. The methods {@link #pid}, {@link #info}, {@link #children},
|
|
* and {@link #descendants}, unless overridden, operate on the ProcessHandle.
|
|
*
|
|
* @return Returns a ProcessHandle for the Process
|
|
* @throws UnsupportedOperationException if the Process implementation
|
|
* does not support this operation
|
|
* @throws SecurityException if a security manager has been installed and
|
|
* it denies RuntimePermission("manageProcess")
|
|
* @since 9
|
|
*/
|
|
public ProcessHandle toHandle() {
|
|
throw new UnsupportedOperationException(this.getClass()
|
|
+ ".toHandle() not supported");
|
|
}
|
|
|
|
/**
|
|
* Returns a snapshot of information about the process.
|
|
*
|
|
* <p> A {@link ProcessHandle.Info} instance has accessor methods
|
|
* that return information about the process if it is available.
|
|
*
|
|
* @implSpec
|
|
* This implementation returns information about the process as:
|
|
* {@link #toHandle toHandle().info()}.
|
|
*
|
|
* @return a snapshot of information about the process, always non-null
|
|
* @throws UnsupportedOperationException if the Process implementation
|
|
* does not support this operation
|
|
* @since 9
|
|
*/
|
|
public ProcessHandle.Info info() {
|
|
return toHandle().info();
|
|
}
|
|
|
|
/**
|
|
* Returns a snapshot of the direct children of the process.
|
|
* The parent of a direct child process is the process.
|
|
* Typically, a process that is {@linkplain #isAlive not alive} has no children.
|
|
* <p>
|
|
* <em>Note that processes are created and terminate asynchronously.
|
|
* There is no guarantee that a process is {@linkplain #isAlive alive}.
|
|
* </em>
|
|
*
|
|
* @implSpec
|
|
* This implementation returns the direct children as:
|
|
* {@link #toHandle toHandle().children()}.
|
|
*
|
|
* @return a sequential Stream of ProcessHandles for processes that are
|
|
* direct children of the process
|
|
* @throws UnsupportedOperationException if the Process implementation
|
|
* does not support this operation
|
|
* @throws SecurityException if a security manager has been installed and
|
|
* it denies RuntimePermission("manageProcess")
|
|
* @since 9
|
|
*/
|
|
public Stream<ProcessHandle> children() {
|
|
return toHandle().children();
|
|
}
|
|
|
|
/**
|
|
* Returns a snapshot of the descendants of the process.
|
|
* The descendants of a process are the children of the process
|
|
* plus the descendants of those children, recursively.
|
|
* Typically, a process that is {@linkplain #isAlive not alive} has no children.
|
|
* <p>
|
|
* <em>Note that processes are created and terminate asynchronously.
|
|
* There is no guarantee that a process is {@linkplain #isAlive alive}.
|
|
* </em>
|
|
*
|
|
* @implSpec
|
|
* This implementation returns all children as:
|
|
* {@link #toHandle toHandle().descendants()}.
|
|
*
|
|
* @return a sequential Stream of ProcessHandles for processes that
|
|
* are descendants of the process
|
|
* @throws UnsupportedOperationException if the Process implementation
|
|
* does not support this operation
|
|
* @throws SecurityException if a security manager has been installed and
|
|
* it denies RuntimePermission("manageProcess")
|
|
* @since 9
|
|
*/
|
|
public Stream<ProcessHandle> descendants() {
|
|
return toHandle().descendants();
|
|
}
|
|
|
|
/**
|
|
* An input stream for a subprocess pipe that skips by reading bytes
|
|
* instead of seeking, the underlying pipe does not support seek.
|
|
*/
|
|
static class PipeInputStream extends FileInputStream {
|
|
|
|
PipeInputStream(FileDescriptor fd) {
|
|
super(fd);
|
|
}
|
|
|
|
@Override
|
|
public long skip(long n) throws IOException {
|
|
long remaining = n;
|
|
int nr;
|
|
|
|
if (n <= 0) {
|
|
return 0;
|
|
}
|
|
|
|
int size = (int)Math.min(2048, remaining);
|
|
byte[] skipBuffer = new byte[size];
|
|
while (remaining > 0) {
|
|
nr = read(skipBuffer, 0, (int)Math.min(size, remaining));
|
|
if (nr < 0) {
|
|
break;
|
|
}
|
|
remaining -= nr;
|
|
}
|
|
|
|
return n - remaining;
|
|
}
|
|
}
|
|
}
|