/*
 * Copyright (c) 1995, 2012, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package java.lang;

import java.io.*;
import java.util.concurrent.TimeUnit;

/**
 * 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. The class {@code Process}
 * 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.
 *
 * <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 subprocess 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 subprocess. 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 subprocess may cause the subprocess to block, or even deadlock.
 *
 * <p>Where desired, <a href="ProcessBuilder.html#redirect-input">
 * subprocess I/O can also be redirected</a>
 * using methods of the {@link ProcessBuilder} class.
 *
 * <p>The subprocess is not killed when there are no more references to
 * the {@code Process} object, but rather the subprocess
 * continues executing asynchronously.
 *
 * <p>There is no requirement that a 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}.
 *
 * @since JDK1.0
 */
public abstract class Process {
 /**
 * Returns the output stream connected to the normal input of the
 * subprocess. 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 subprocess 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
 * subprocess
 */
 public abstract OutputStream getOutputStream();

 /**
 * Returns the input stream connected to the normal output of the
 * subprocess. 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 subprocess 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 subprocess 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 subprocess.
 *
 * <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
 * subprocess
 */
 public abstract InputStream getInputStream();

 /**
 * Returns the input stream connected to the error output of the
 * subprocess. 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 subprocess 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 subprocess
 */
 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 subprocess
 * has already terminated. If the subprocess has not yet
 * terminated, the calling thread will be blocked until the
 * subprocess exits.
 *
 * @return the exit value of the subprocess 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
 * subprocess represented by this {@code Process} object has
 * terminated, or the specified waiting time elapses.
 *
 * <p>If the subprocess 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 subprocess has exited and {@code false} if
 * the waiting time elapsed before the subprocess 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 startTime = System.nanoTime();
 long rem = unit.toNanos(timeout);

 do {
 try {
 exitValue();
 return true;
 } catch(IllegalThreadStateException ex) {
 if (rem > 0)
 Thread.sleep(
 Math.min(TimeUnit.NANOSECONDS.toMillis(rem) + 1, 100));
 }
 rem = unit.toNanos(timeout) - (System.nanoTime() - startTime);
 } while (rem > 0);
 return false;
 }

 /**
 * Returns the exit value for the subprocess.
 *
 * @return the exit value of the subprocess represented by this
 * {@code Process} object. By convention, the value
 * {@code 0} indicates normal termination.
 * @throws IllegalThreadStateException if the subprocess represented
 * by this {@code Process} object has not yet terminated
 */
 public abstract int exitValue();

 /**
 * 销毁当前命令进程,是否是强制的,由实现类决定
 * Kills the subprocess. Whether the subprocess represented by this
 * {@code Process} object is forcibly terminated or not is
 * implementation dependent.
 */
 public abstract void destroy();

 /**
 * 强制销毁当前命令进程,语义上是强制销毁,
 * 官方默认给的是直接调用destroy(),可根据isAlive()判断是否强制销毁命令进程
 * Kills the subprocess. The subprocess represented by this
 * {@code Process} object is forcibly terminated.
 *
 * <p>The default implementation of this method invokes {@link #destroy}
 * and so may not forcibly terminate the process. Concrete implementations
 * of this class are strongly encouraged to override this method with a
 * compliant implementation. Invoking this method on {@code Process}
 * objects returned by {@link ProcessBuilder#start} and
 * {@link Runtime#exec} will forcibly terminate the process.
 *
 * <p>Note: The subprocess 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
 * subprocess to be forcibly destroyed.
 * @since 1.8
 */
 public Process destroyForcibly() {
 destroy();
 return this;
 }

 /**
 * Tests whether the subprocess represented by this {@code Process} is
 * alive.
 *
 * @return {@code true} if the subprocess represented by this
 * {@code Process} object has not yet terminated.
 * @since 1.8
 */
 public boolean isAlive() {
 try {
 exitValue();
 return false;
 } catch(IllegalThreadStateException e) {
 return true;
 }
 }
}