1 /*
   2  * Copyright (c) 1995, 2008, 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 
  30 /**
  31  * The {@link ProcessBuilder#start()} and
  32  * {@link Runtime#exec(String[],String[],File) Runtime.exec}
  33  * methods create a native process and return an instance of a
  34  * subclass of {@code Process} that can be used to control the process
  35  * and obtain information about it.  The class {@code Process}
  36  * provides methods for performing input from the process, performing
  37  * output to the process, waiting for the process to complete,
  38  * checking the exit status of the process, and destroying (killing)
  39  * the process.
  40  *
  41  * <p>The methods that create processes may not work well for special
  42  * processes on certain native platforms, such as native windowing
  43  * processes, daemon processes, Win16/DOS processes on Microsoft
  44  * Windows, or shell scripts.
  45  *
  46  * <p>By default, the created subprocess does not have its own terminal
  47  * or console.  All its standard I/O (i.e. stdin, stdout, stderr)
  48  * operations will be redirected to the parent process, where they can
  49  * be accessed via the streams obtained using the methods
  50  * {@link #getOutputStream()},
  51  * {@link #getInputStream()}, and
  52  * {@link #getErrorStream()}.
  53  * The parent process uses these streams to feed input to and get output
  54  * from the subprocess.  Because some native platforms only provide
  55  * limited buffer size for standard input and output streams, failure
  56  * to promptly write the input stream or read the output stream of
  57  * the subprocess may cause the subprocess to block, or even deadlock.
  58  *
  59  * <p>Where desired, <a href="ProcessBuilder.html#redirect-input">
  60  * subprocess I/O can also be redirected</a>
  61  * using methods of the {@link ProcessBuilder} class.
  62  *
  63  * <p>The subprocess is not killed when there are no more references to
  64  * the {@code Process} object, but rather the subprocess
  65  * continues executing asynchronously.
  66  *
  67  * <p>There is no requirement that a process represented by a {@code
  68  * Process} object execute asynchronously or concurrently with respect
  69  * to the Java process that owns the {@code Process} object.
  70  *
  71  * <p>As of 1.5, {@link ProcessBuilder#start()} is the preferred way
  72  * to create a {@code Process}.
  73  *
  74  * @since   JDK1.0
  75  */
  76 public abstract class Process {
  77     /**
  78      * Returns the output stream connected to the normal input of the
  79      * subprocess.  Output to the stream is piped into the standard
  80      * input of the process represented by this {@code Process} object.
  81      *
  82      * <p>If the standard input of the subprocess has been redirected using
  83      * {@link ProcessBuilder#redirectInput(Redirect)
  84      * ProcessBuilder.redirectInput}
  85      * then this method will return a
  86      * <a href="ProcessBuilder.html#redirect-input">null output stream</a>.
  87      *
  88      * <p>Implementation note: It is a good idea for the returned
  89      * output stream to be buffered.
  90      *
  91      * @return the output stream connected to the normal input of the
  92      *         subprocess
  93      */
  94     public abstract OutputStream getOutputStream();
  95 
  96     /**
  97      * Returns the input stream connected to the normal output of the
  98      * subprocess.  The stream obtains data piped from the standard
  99      * output of the process represented by this {@code Process} object.
 100      *
 101      * <p>If the standard output of the subprocess has been redirected using
 102      * {@link ProcessBuilder#redirectOutput(Redirect)
 103      * ProcessBuilder.redirectOutput}
 104      * then this method will return a
 105      * <a href="ProcessBuilder.html#redirect-output">null input stream</a>.
 106      *
 107      * <p>Otherwise, if the standard error of the subprocess has been
 108      * redirected using
 109      * {@link ProcessBuilder#redirectErrorStream(boolean)
 110      * ProcessBuilder.redirectErrorStream}
 111      * then the input stream returned by this method will receive the
 112      * merged standard output and the standard error of the subprocess.
 113      *
 114      * <p>Implementation note: It is a good idea for the returned
 115      * input stream to be buffered.
 116      *
 117      * @return the input stream connected to the normal output of the
 118      *         subprocess
 119      */
 120     public abstract InputStream getInputStream();
 121 
 122     /**
 123      * Returns the input stream connected to the error output of the
 124      * subprocess.  The stream obtains data piped from the error output
 125      * of the process represented by this {@code Process} object.
 126      *
 127      * <p>If the standard error of the subprocess has been redirected using
 128      * {@link ProcessBuilder#redirectError(Redirect)
 129      * ProcessBuilder.redirectError} or
 130      * {@link ProcessBuilder#redirectErrorStream(boolean)
 131      * ProcessBuilder.redirectErrorStream}
 132      * then this method will return a
 133      * <a href="ProcessBuilder.html#redirect-output">null input stream</a>.
 134      *
 135      * <p>Implementation note: It is a good idea for the returned
 136      * input stream to be buffered.
 137      *
 138      * @return the input stream connected to the error output of
 139      *         the subprocess
 140      */
 141     public abstract InputStream getErrorStream();
 142 
 143     /**
 144      * Causes the current thread to wait, if necessary, until the
 145      * process represented by this {@code Process} object has
 146      * terminated.  This method returns immediately if the subprocess
 147      * has already terminated.  If the subprocess has not yet
 148      * terminated, the calling thread will be blocked until the
 149      * subprocess exits.
 150      *
 151      * @return the exit value of the subprocess represented by this
 152      *         {@code Process} object.  By convention, the value
 153      *         {@code 0} indicates normal termination.
 154      * @throws InterruptedException if the current thread is
 155      *         {@linkplain Thread#interrupt() interrupted} by another
 156      *         thread while it is waiting, then the wait is ended and
 157      *         an {@link InterruptedException} is thrown.
 158      */
 159     public abstract int waitFor() throws InterruptedException;
 160 
 161     /**
 162      * Returns the exit value for the subprocess.
 163      *
 164      * @return the exit value of the subprocess represented by this
 165      *         {@code Process} object.  By convention, the value
 166      *         {@code 0} indicates normal termination.
 167      * @throws IllegalThreadStateException if the subprocess represented
 168      *         by this {@code Process} object has not yet terminated
 169      */
 170     public abstract int exitValue();
 171 
 172     /**
 173      * Kills the subprocess. Whether the subprocess represented by this
 174      * {@code Process} object is forcibly terminated or not is 
 175      * implementation dependent.
 176      */
 177     public abstract void destroy();
 178 
 179     /**
 180      * Kills the subprocess. The subprocess represented by this
 181      * {@code Process} object is forcibly terminated.
 182      */
 183     public abstract Process destroyForcibly();
 184 
 185     /**
 186      * Returns a boolean indicating whether the subprocess is alive.
 187      *
 188      * @return {@code true} if the subprocess represented by this
 189      *         {@code Process} object has not yet terminated.
 190      */
 191     public abstract boolean isAlive();
 192 }