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: }
| 