001 /*
002 * Copyright 1995-2007 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.lang;
027
028 import java.io.*;
029
030 /**
031 * The {@link ProcessBuilder#start()} and
032 * {@link Runtime#exec(String[],String[],File) Runtime.exec}
033 * methods create a native process and return an instance of a
034 * subclass of {@code Process} that can be used to control the process
035 * and obtain information about it. The class {@code Process}
036 * provides methods for performing input from the process, performing
037 * output to the process, waiting for the process to complete,
038 * checking the exit status of the process, and destroying (killing)
039 * the process.
040 *
041 * <p>The methods that create processes may not work well for special
042 * processes on certain native platforms, such as native windowing
043 * processes, daemon processes, Win16/DOS processes on Microsoft
044 * Windows, or shell scripts. The created subprocess does not have
045 * its own terminal or console. All its standard I/O (i.e. stdin,
046 * stdout, stderr) operations will be redirected to the parent process
047 * through three streams
048 * ({@link #getOutputStream()},
049 * {@link #getInputStream()},
050 * {@link #getErrorStream()}).
051 * The parent process uses these streams to feed input to and get output
052 * from the subprocess. Because some native platforms only provide
053 * limited buffer size for standard input and output streams, failure
054 * to promptly write the input stream or read the output stream of
055 * the subprocess may cause the subprocess to block, and even deadlock.
056 *
057 * <p>The subprocess is not killed when there are no more references to
058 * the {@code Process} object, but rather the subprocess
059 * continues executing asynchronously.
060 *
061 * <p>There is no requirement that a process represented by a {@code
062 * Process} object execute asynchronously or concurrently with respect
063 * to the Java process that owns the {@code Process} object.
064 *
065 * @author unascribed
066 * @version 1.32, 07/08/07
067 * @see ProcessBuilder
068 * @since JDK1.0
069 */
070 public abstract class Process {
071 /**
072 * Returns the output stream connected to the normal input of the
073 * subprocess. Output to the stream is piped into the standard
074 * input stream of the process represented by this {@code Process}
075 * object.
076 *
077 * <p>Implementation note: It is a good idea for the returned
078 * output stream to be buffered.
079 *
080 * @return the output stream connected to the normal input of the
081 * subprocess
082 */
083 abstract public OutputStream getOutputStream();
084
085 /**
086 * Returns the input stream connected to the normal output of the
087 * subprocess. The stream obtains data piped from the standard
088 * output stream of the process represented by this {@code
089 * Process} object.
090 *
091 * <p>Implementation note: It is a good idea for the returned
092 * input stream to be buffered.
093 *
094 * @return the input stream connected to the normal output of the
095 * subprocess
096 * @see ProcessBuilder#redirectErrorStream()
097 */
098 abstract public InputStream getInputStream();
099
100 /**
101 * Returns the input stream connected to the error output stream of
102 * the subprocess. The stream obtains data piped from the error
103 * output stream of the process represented by this {@code Process}
104 * object.
105 *
106 * <p>Implementation note: It is a good idea for the returned
107 * input stream to be buffered.
108 *
109 * @return the input stream connected to the error output stream of
110 * the subprocess
111 * @see ProcessBuilder#redirectErrorStream()
112 */
113 abstract public InputStream getErrorStream();
114
115 /**
116 * Causes the current thread to wait, if necessary, until the
117 * process represented by this {@code Process} object has
118 * terminated. This method returns immediately if the subprocess
119 * has already terminated. If the subprocess has not yet
120 * terminated, the calling thread will be blocked until the
121 * subprocess exits.
122 *
123 * @return the exit value of the subprocess represented by this
124 * {@code Process} object. By convention, the value
125 * {@code 0} indicates normal termination.
126 * @throws InterruptedException if the current thread is
127 * {@linkplain Thread#interrupt() interrupted} by another
128 * thread while it is waiting, then the wait is ended and
129 * an {@link InterruptedException} is thrown.
130 */
131 abstract public int waitFor() throws InterruptedException;
132
133 /**
134 * Returns the exit value for the subprocess.
135 *
136 * @return the exit value of the subprocess represented by this
137 * {@code Process} object. By convention, the value
138 * {@code 0} indicates normal termination.
139 * @throws IllegalThreadStateException if the subprocess represented
140 * by this {@code Process} object has not yet terminated
141 */
142 abstract public int exitValue();
143
144 /**
145 * Kills the subprocess. The subprocess represented by this
146 * {@code Process} object is forcibly terminated.
147 */
148 abstract public void destroy();
149 }
|