jdk-sandbox: comparison jdk/src/java.base/share/classes/java/lang/Process.java

equal deleted inserted replaced

-:2665054d3864
+:9564031a20e0
 * <p>Subclasses of Process should override the {@link #onExit()} and
 * {@link #toHandle()} methods to provide a fully functional Process including the
 * {@link #getPid() process id},
 * {@link #info() information about the process},
 * {@link #children() direct children}, and
-* {@link #allChildren() direct and indirect children} of the process.
+* {@link #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
 */
 /**
 * 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 terminates the CompletableFuture is
+* 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
 * {@link java.util.concurrent.CompletableFuture#isDone done} or to
 * {@link java.util.concurrent.CompletableFuture#get() wait} for it to terminate.
 * {@link java.util.concurrent.CompletableFuture#cancel(boolean) Cancelling}
 * the CompletableFuture does not affect the Process.
-* <p>
-* If the process is {@link #isAlive not alive} the {@link CompletableFuture}
-* returned has been {@link java.util.concurrent.CompletableFuture#complete completed}.
 * <p>
 * Processes returned from {@link ProcessBuilder#start} override the
 * default implementation to provide an efficient mechanism to wait
 * for process exit.
 *
 * <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 1.9
 */
 * @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 #getPid}, {@link #info}, {@link #children},
-* and {@link #allChildren}, unless overridden, operate on the ProcessHandle.
+* 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
 }
 /**
 * Returns a snapshot of information about the process.
 *
-* <p> An {@link ProcessHandle.Info} instance has various accessor methods
+* <p> A {@link ProcessHandle.Info} instance has accessor methods
-* that return information about the process, if the process is alive and
+* that return information about the process if it is available.
-* the information is available, otherwise {@code null} is returned.
 *
 * @implSpec
 * This implementation returns information about the process as:
 * {@link #toHandle toHandle().info()}.
 *
 public Stream<ProcessHandle> children() {
 return toHandle().children();
 }
 /**
-* Returns a snapshot of the direct and indirect children of the process.
+* Returns a snapshot of the descendants of the process.
-* An indirect child is one whose parent is either a direct child or
+* The descendants of a process are the children of the process
-* another indirect child.
+* plus the descendants of those children, recursively.
 * Typically, a process that is {@link #isAlive not alive} has no children.
 * <p>
 * <em>Note that processes are created and terminate asynchronously.
 * There is no guarantee that a process is {@link #isAlive alive}.
 * </em>
 *
 * @implSpec
 * This implementation returns all children as:
-* {@link #toHandle toHandle().allChildren()}.
+* {@link #toHandle toHandle().descendants()}.
 *
-* @return a sequential Stream of ProcessHandles for processes that are
+* @return a sequential Stream of ProcessHandles for processes that
-*         direct and indirect children of the process
+*         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 1.9
 */
-public Stream<ProcessHandle> allChildren() {
+public Stream<ProcessHandle> descendants() {
-return toHandle().allChildren();
+return toHandle().descendants();
 }
 }

changeset 33648	9564031a20e0
parent 32764	1586fc6697da
child 35302	e4d2275861c3