Java tutorial
/* * 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; } } }