1 /*
   2  * Copyright (c) 1995, 2012, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.lang;
  27 
  28 import java.io.*;
  29 import java.util.concurrent.TimeUnit;
  30 
  31 /**
  32  * The {@link ProcessBuilder#start()} and
  33  * {@link Runtime#exec(String[],String[],File) Runtime.exec}
  34  * methods create a native process and return an instance of a
  35  * subclass of {@code Process} that can be used to control the process
  36  * and obtain information about it.  The class {@code Process}
  37  * provides methods for performing input from the process, performing
  38  * output to the process, waiting for the process to complete,
  39  * checking the exit status of the process, and destroying (killing)
  40  * the process.
  41  *
  42  * <p>The methods that create processes may not work well for special
  43  * processes on certain native platforms, such as native windowing
  44  * processes, daemon processes, Win16/DOS processes on Microsoft
  45  * Windows, or shell scripts.
  46  *
  47  * <p>By default, the created subprocess does not have its own terminal
  48  * or console.  All its standard I/O (i.e. stdin, stdout, stderr)
  49  * operations will be redirected to the parent process, where they can
  50  * be accessed via the streams obtained using the methods
  51  * {@link #getOutputStream()},
  52  * {@link #getInputStream()}, and
  53  * {@link #getErrorStream()}.
  54  * The parent process uses these streams to feed input to and get output
  55  * from the subprocess.  Because some native platforms only provide
  56  * limited buffer size for standard input and output streams, failure
  57  * to promptly write the input stream or read the output stream of
  58  * the subprocess may cause the subprocess to block, or even deadlock.
  59  *
  60  * <p>Where desired, <a href="ProcessBuilder.html#redirect-input">
  61  * subprocess I/O can also be redirected</a>
  62  * using methods of the {@link ProcessBuilder} class.
  63  *
  64  * <p>The subprocess is not killed when there are no more references to
  65  * the {@code Process} object, but rather the subprocess
  66  * continues executing asynchronously.
  67  *
  68  * <p>There is no requirement that a process represented by a {@code
  69  * Process} object execute asynchronously or concurrently with respect
  70  * to the Java process that owns the {@code Process} object.
  71  *
  72  * <p>As of 1.5, {@link ProcessBuilder#start()} is the preferred way
  73  * to create a {@code Process}.
  74  *
  75  * @since   JDK1.0
  76  */
  77 public abstract class Process {
  78     /**
  79      * Returns the output stream connected to the normal input of the
  80      * subprocess.  Output to the stream is piped into the standard
  81      * input of the process represented by this {@code Process} object.
  82      *
  83      * <p>If the standard input of the subprocess has been redirected using
  84      * {@link ProcessBuilder#redirectInput(Redirect)
  85      * ProcessBuilder.redirectInput}
  86      * then this method will return a
  87      * <a href="ProcessBuilder.html#redirect-input">null output stream</a>.
  88      *
  89      * <p>Implementation note: It is a good idea for the returned
  90      * output stream to be buffered.
  91      *
  92      * @return the output stream connected to the normal input of the
  93      *         subprocess
  94      */
  95     public abstract OutputStream getOutputStream();
  96 
  97     /**
  98      * Returns the input stream connected to the normal output of the
  99      * subprocess.  The stream obtains data piped from the standard
 100      * output of the process represented by this {@code Process} object.
 101      *
 102      * <p>If the standard output of the subprocess has been redirected using
 103      * {@link ProcessBuilder#redirectOutput(Redirect)
 104      * ProcessBuilder.redirectOutput}
 105      * then this method will return a
 106      * <a href="ProcessBuilder.html#redirect-output">null input stream</a>.
 107      *
 108      * <p>Otherwise, if the standard error of the subprocess has been
 109      * redirected using
 110      * {@link ProcessBuilder#redirectErrorStream(boolean)
 111      * ProcessBuilder.redirectErrorStream}
 112      * then the input stream returned by this method will receive the
 113      * merged standard output and the standard error of the subprocess.
 114      *
 115      * <p>Implementation note: It is a good idea for the returned
 116      * input stream to be buffered.
 117      *
 118      * @return the input stream connected to the normal output of the
 119      *         subprocess
 120      */
 121     public abstract InputStream getInputStream();
 122 
 123     /**
 124      * Returns the input stream connected to the error output of the
 125      * subprocess.  The stream obtains data piped from the error output
 126      * of the process represented by this {@code Process} object.
 127      *
 128      * <p>If the standard error of the subprocess has been redirected using
 129      * {@link ProcessBuilder#redirectError(Redirect)
 130      * ProcessBuilder.redirectError} or
 131      * {@link ProcessBuilder#redirectErrorStream(boolean)
 132      * ProcessBuilder.redirectErrorStream}
 133      * then this method will return a
 134      * <a href="ProcessBuilder.html#redirect-output">null input stream</a>.
 135      *
 136      * <p>Implementation note: It is a good idea for the returned
 137      * input stream to be buffered.
 138      *
 139      * @return the input stream connected to the error output of
 140      *         the subprocess
 141      */
 142     public abstract InputStream getErrorStream();
 143 
 144     /**
 145      * Causes the current thread to wait, if necessary, until the
 146      * process represented by this {@code Process} object has
 147      * terminated.  This method returns immediately if the subprocess
 148      * has already terminated.  If the subprocess has not yet
 149      * terminated, the calling thread will be blocked until the
 150      * subprocess exits.
 151      *
 152      * @return the exit value of the subprocess represented by this
 153      *         {@code Process} object.  By convention, the value
 154      *         {@code 0} indicates normal termination.
 155      * @throws InterruptedException if the current thread is
 156      *         {@linkplain Thread#interrupt() interrupted} by another
 157      *         thread while it is waiting, then the wait is ended and
 158      *         an {@link InterruptedException} is thrown.
 159      */
 160     public abstract int waitFor() throws InterruptedException;
 161         
 162     /**
 163      * Causes the current thread to wait, if necessary, until the
 164      * subprocess represented by this {@code Process} object has
 165      * terminated, or the specified waiting time elapses. 
 166      *
 167      * <p>If the subprocess has already terminated then this method returns
 168      * immediately with the value {@code true}.  If the process has not
 169      * terminated and the timeout value is less than, or equal to, zero, then
 170      * this method returns immediately with the value {@code false}.
 171      *
 172      * <p>The default implementation of this methods polls the {@code exitValue}
 173      * to check if the process has terminated. Concrete implementations of this 
 174      * class are strongly encouraged to override this method with a more 
 175      * efficient implementation.
 176      *
 177      * @param timeout the maximum time to wait
 178      * @param unit the time unit of the {@code timeout} argument
 179      * @return {@code true} if the subprocess has exited and {@code false} if
 180      *         the waiting time elapsed before the subprocess has exited.
 181      * @throws InterruptedException if the current thread is interrupted
 182      *         while waiting.
 183      * @throws NullPointerException if unit is null
 184      * @since 1.8
 185      */
 186     public boolean waitFor(long timeout, TimeUnit unit) 
 187         throws InterruptedException
 188     {
 189         long startTime = System.nanoTime();
 190         long rem = unit.toNanos(timeout) - (System.nanoTime() - startTime);
 191         
 192         do {
 193             try {
 194                 exitValue();
 195                 return true;
 196             } catch(IllegalThreadStateException ex) {
 197                 if(rem > 0)
 198                     Thread.sleep(
 199                         Math.min(TimeUnit.NANOSECONDS.toMillis(rem) + 1, 100));
 200             }
 201             rem = unit.toNanos(timeout) - (System.nanoTime() - startTime);
 202         } while(rem > 0);
 203         return false;
 204     }
 205 
 206     /**
 207      * Returns the exit value for the subprocess.
 208      *
 209      * @return the exit value of the subprocess represented by this
 210      *         {@code Process} object.  By convention, the value
 211      *         {@code 0} indicates normal termination.
 212      * @throws IllegalThreadStateException if the subprocess represented
 213      *         by this {@code Process} object has not yet terminated
 214      */
 215     public abstract int exitValue();
 216 
 217     /**
 218      * Kills the subprocess. Whether the subprocess represented by this
 219      * {@code Process} object is forcibly terminated or not is
 220      * implementation dependent.
 221      */
 222     public abstract void destroy();
 223 
 224     /**
 225      * Kills the subprocess. The subprocess represented by this
 226      * {@code Process} object is forcibly terminated.
 227      *
 228      * <p>The default implementation of this method invokes {@link #destroy}
 229      * and so may not forcibly terminate the process. Concrete implementations
 230      * of this class are strongly encouraged to override this method with a
 231      * compliant implementation.  Invoking this method on {@code Process} 
 232      * objects returned by {@link ProcessBuilder#start} and 
 233      * {@link Runtime#exec} will forcibly terminate the process.
 234      *
 235      * <p>Note: The subprocess may not terminate immediately.
 236      * i.e. {@code isAlive()} may return true for a brief period
 237      * after {@code destroyForcibly()} is called. This method
 238      * may be chained to {@code waitFor()} if needed.
 239      *
 240      * @return the {@code Process} object representing the
 241      *         subprocess to be forcibly destroyed.
 242      * @since 1.8
 243      */
 244     public Process destroyForcibly() {
 245         destroy();
 246         return this;
 247     }
 248 
 249     /**
 250      * Tests whether the subprocess represented by this {@code Process} is 
 251      * alive.
 252      *
 253      * @return {@code true} if the subprocess represented by this
 254      *         {@code Process} object has not yet terminated.
 255      * @since 1.8
 256      */
 257     public boolean isAlive() {
 258         try {
 259             exitValue();
 260             return false;
 261         } catch(IllegalThreadStateException e) {
 262             return true;
 263         }
 264     }
 265 }