/*
* Copyright (c) 1995, 2007, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.lang;
import java.io.*;
/** {@collect.stats}
* {@description.open}
* The {@link ProcessBuilder#start()} and
* {@link Runtime#exec(String[],String[],File) Runtime.exec}
* methods create a native process and return an instance of a
* subclass of {@code Process} that can be used to control the process
* and obtain information about it. The class {@code Process}
* provides methods for performing input from the process, performing
* output to the process, waiting for the process to complete,
* checking the exit status of the process, and destroying (killing)
* the process.
*
* <p>The methods that create processes may not work well for special
* processes on certain native platforms, such as native windowing
* processes, daemon processes, Win16/DOS processes on Microsoft
* Windows, or shell scripts. The created subprocess does not have
* its own terminal or console. All its standard I/O (i.e. stdin,
* stdout, stderr) operations will be redirected to the parent process
* through three streams
* ({@link #getOutputStream()},
* {@link #getInputStream()},
* {@link #getErrorStream()}).
* The parent process uses these streams to feed input to and get output
* from the subprocess. Because some native platforms only provide
* limited buffer size for standard input and output streams, failure
* to promptly write the input stream or read the output stream of
* the subprocess may cause the subprocess to block, and even deadlock.
*
* <p>The subprocess is not killed when there are no more references to
* the {@code Process} object, but rather the subprocess
* continues executing asynchronously.
*
* <p>There is no requirement that a process represented by a {@code
* Process} object execute asynchronously or concurrently with respect
* to the Java process that owns the {@code Process} object.
* {@description.close}
*
* @author unascribed
* @see ProcessBuilder
* @since JDK1.0
*/
public abstract class Process {
/** {@collect.stats}
* {@description.open}
* Returns the output stream connected to the normal input of the
* subprocess. Output to the stream is piped into the standard
* input stream of the process represented by this {@code Process}
* object.
*
* <p>Implementation note: It is a good idea for the returned
* output stream to be buffered.
* {@description.close}
*
* @return the output stream connected to the normal input of the
* subprocess
*/
abstract public OutputStream getOutputStream();
/** {@collect.stats}
* {@description.open}
* Returns the input stream connected to the normal output of the
* subprocess. The stream obtains data piped from the standard
* output stream of the process represented by this {@code
* Process} object.
*
* <p>Implementation note: It is a good idea for the returned
* input stream to be buffered.
* {@description.close}
*
* @return the input stream connected to the normal output of the
* subprocess
* @see ProcessBuilder#redirectErrorStream()
*/
abstract public InputStream getInputStream();
/** {@collect.stats}
* {@description.open}
* Returns the input stream connected to the error output stream of
* the subprocess. The stream obtains data piped from the error
* output stream of the process represented by this {@code Process}
* object.
*
* <p>Implementation note: It is a good idea for the returned
* input stream to be buffered.
* {@description.close}
*
* @return the input stream connected to the error output stream of
* the subprocess
* @see ProcessBuilder#redirectErrorStream()
*/
abstract public InputStream getErrorStream();
/** {@collect.stats}
* {@description.open}
* Causes the current thread to wait, if necessary, until the
* process represented by this {@code Process} object has
* terminated. This method returns immediately if the subprocess
* has already terminated. If the subprocess has not yet
* terminated, the calling thread will be blocked until the
* subprocess exits.
* {@description.close}
*
* @return the exit value of the subprocess represented by this
* {@code Process} object. By convention, the value
* {@code 0} indicates normal termination.
* @throws InterruptedException if the current thread is
* {@linkplain Thread#interrupt() interrupted} by another
* thread while it is waiting, then the wait is ended and
* an {@link InterruptedException} is thrown.
*/
abstract public int waitFor() throws InterruptedException;
/** {@collect.stats}
* {@description.open}
* Returns the exit value for the subprocess.
* {@description.close}
*
* @return the exit value of the subprocess represented by this
* {@code Process} object. By convention, the value
* {@code 0} indicates normal termination.
* @throws IllegalThreadStateException if the subprocess represented
* by this {@code Process} object has not yet terminated
*/
abstract public int exitValue();
/** {@collect.stats}
* {@description.open}
* Kills the subprocess. The subprocess represented by this
* {@code Process} object is forcibly terminated.
* {@description.close}
*/
abstract public void destroy();
}