1 /*

     2  * Copyright 1995-2007 Sun Microsystems, Inc.  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.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any 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.  The created subprocess does not have

    45  * its own terminal or console.  All its standard I/O (i.e. stdin,

    46  * stdout, stderr) operations will be redirected to the parent process

    47  * through three streams

    48  * ({@link #getOutputStream()},

    49  * {@link #getInputStream()},

    50  * {@link #getErrorStream()}).

    51  * The parent process uses these streams to feed input to and get output

    52  * from the subprocess.  Because some native platforms only provide

    53  * limited buffer size for standard input and output streams, failure

    54  * to promptly write the input stream or read the output stream of

    55  * the subprocess may cause the subprocess to block, and even deadlock.

    56  *

    57  * <p>The subprocess is not killed when there are no more references to

    58  * the {@code Process} object, but rather the subprocess

    59  * continues executing asynchronously.

    60  *

    61  * <p>There is no requirement that a process represented by a {@code

    62  * Process} object execute asynchronously or concurrently with respect

    63  * to the Java process that owns the {@code Process} object.

    64  *

    65  * @author  unascribed

    66  * @see     ProcessBuilder

    67  * @since   JDK1.0

    68  */

    69 public abstract class Process {

    70     /**

    71      * Returns the output stream connected to the normal input of the

    72      * subprocess.  Output to the stream is piped into the standard

    73      * input stream of the process represented by this {@code Process}

    74      * object.

    75      *

    76      * <p>Implementation note: It is a good idea for the returned

    77      * output stream to be buffered.

    78      *

    79      * @return the output stream connected to the normal input of the

    80      *         subprocess

    81      */

    82     abstract public OutputStream getOutputStream();

    83 

    84     /**

    85      * Returns the input stream connected to the normal output of the

    86      * subprocess.  The stream obtains data piped from the standard

    87      * output stream of the process represented by this {@code

    88      * Process} object.

    89      *

    90      * <p>Implementation note: It is a good idea for the returned

    91      * input stream to be buffered.

    92      *

    93      * @return the input stream connected to the normal output of the

    94      *         subprocess

    95      * @see ProcessBuilder#redirectErrorStream()

    96      */

    97     abstract public InputStream getInputStream();

    98 

    99     /**

   100      * Returns the input stream connected to the error output stream of

   101      * the subprocess.  The stream obtains data piped from the error

   102      * output stream of the process represented by this {@code Process}

   103      * object.

   104      *

   105      * <p>Implementation note: It is a good idea for the returned

   106      * input stream to be buffered.

   107      *

   108      * @return the input stream connected to the error output stream of

   109      *         the subprocess

   110      * @see ProcessBuilder#redirectErrorStream()

   111      */

   112     abstract public InputStream getErrorStream();

   113 

   114     /**

   115      * Causes the current thread to wait, if necessary, until the

   116      * process represented by this {@code Process} object has

   117      * terminated.  This method returns immediately if the subprocess

   118      * has already terminated.  If the subprocess has not yet

   119      * terminated, the calling thread will be blocked until the

   120      * subprocess exits.

   121      *

   122      * @return the exit value of the subprocess represented by this

   123      *         {@code Process} object.  By convention, the value

   124      *         {@code 0} indicates normal termination.

   125      * @throws InterruptedException if the current thread is

   126      *         {@linkplain Thread#interrupt() interrupted} by another

   127      *         thread while it is waiting, then the wait is ended and

   128      *         an {@link InterruptedException} is thrown.

   129      */

   130     abstract public int waitFor() throws InterruptedException;

   131 

   132     /**

   133      * Returns the exit value for the subprocess.

   134      *

   135      * @return the exit value of the subprocess represented by this

   136      *         {@code Process} object.  By convention, the value

   137      *         {@code 0} indicates normal termination.

   138      * @throws IllegalThreadStateException if the subprocess represented

   139      *         by this {@code Process} object has not yet terminated

   140      */

   141     abstract public int exitValue();

   142 

   143     /**

   144      * Kills the subprocess. The subprocess represented by this

   145      * {@code Process} object is forcibly terminated.

   146      */

   147     abstract public void destroy();

   148 }