Back to index...

	/*
	* Copyright (c) 1995, 2012, 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.*;
	import java.util.concurrent.TimeUnit;

	/**
	* 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.
	*
	* <p>By default, 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, where they can
	* be accessed via the streams obtained using the methods
	* {@link #getOutputStream()},
	* {@link #getInputStream()}, and
	* {@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, or even deadlock.
	*
	* <p>Where desired, <a href="ProcessBuilder.html#redirect-input">
	* subprocess I/O can also be redirected</a>
	* using methods of the {@link ProcessBuilder} class.
	*
	* <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.
	*
	* <p>As of 1.5, {@link ProcessBuilder#start()} is the preferred way
	* to create a {@code Process}.
	*
	* @since JDK1.0
	*/
	public abstract class Process {
	/**
	* Returns the output stream connected to the normal input of the
	* subprocess. Output to the stream is piped into the standard
	* input of the process represented by this {@code Process} object.
	*
	* <p>If the standard input of the subprocess has been redirected using
	* {@link ProcessBuilder#redirectInput(Redirect)
	* ProcessBuilder.redirectInput}
	* then this method will return a
	* <a href="ProcessBuilder.html#redirect-input">null output stream</a>.
	*
	* <p>Implementation note: It is a good idea for the returned
	* output stream to be buffered.
	*
	* @return the output stream connected to the normal input of the
	* subprocess
	*/
	public abstract OutputStream getOutputStream();

	/**
	* Returns the input stream connected to the normal output of the
	* subprocess. The stream obtains data piped from the standard
	* output of the process represented by this {@code Process} object.
	*
	* <p>If the standard output of the subprocess has been redirected using
	* {@link ProcessBuilder#redirectOutput(Redirect)
	* ProcessBuilder.redirectOutput}
	* then this method will return a
	* <a href="ProcessBuilder.html#redirect-output">null input stream</a>.
	*
	* <p>Otherwise, if the standard error of the subprocess has been
	* redirected using
	* {@link ProcessBuilder#redirectErrorStream(boolean)
	* ProcessBuilder.redirectErrorStream}
	* then the input stream returned by this method will receive the
	* merged standard output and the standard error of the subprocess.
	*
	* <p>Implementation note: It is a good idea for the returned
	* input stream to be buffered.
	*
	* @return the input stream connected to the normal output of the
	* subprocess
	*/
	public abstract InputStream getInputStream();

	/**
	* Returns the input stream connected to the error output of the
	* subprocess. The stream obtains data piped from the error output
	* of the process represented by this {@code Process} object.
	*
	* <p>If the standard error of the subprocess has been redirected using
	* {@link ProcessBuilder#redirectError(Redirect)
	* ProcessBuilder.redirectError} or
	* {@link ProcessBuilder#redirectErrorStream(boolean)
	* ProcessBuilder.redirectErrorStream}
	* then this method will return a
	* <a href="ProcessBuilder.html#redirect-output">null input stream</a>.
	*
	* <p>Implementation note: It is a good idea for the returned
	* input stream to be buffered.
	*
	* @return the input stream connected to the error output of
	* the subprocess
	*/
	public abstract InputStream getErrorStream();

	/**
	* 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.
	*
	* @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.
	*/
	public abstract int waitFor() throws InterruptedException;

	/**
	* Causes the current thread to wait, if necessary, until the
	* subprocess represented by this {@code Process} object has
	* terminated, or the specified waiting time elapses.
	*
	* <p>If the subprocess has already terminated then this method returns
	* immediately with the value {@code true}. If the process has not
	* terminated and the timeout value is less than, or equal to, zero, then
	* this method returns immediately with the value {@code false}.
	*
	* <p>The default implementation of this methods polls the {@code exitValue}
	* to check if the process has terminated. Concrete implementations of this
	* class are strongly encouraged to override this method with a more
	* efficient implementation.
	*
	* @param timeout the maximum time to wait
	* @param unit the time unit of the {@code timeout} argument
	* @return {@code true} if the subprocess has exited and {@code false} if
	* the waiting time elapsed before the subprocess has exited.
	* @throws InterruptedException if the current thread is interrupted
	* while waiting.
	* @throws NullPointerException if unit is null
	* @since 1.8
	*/
	public boolean waitFor(long timeout, TimeUnit unit)
	throws InterruptedException
	{
	long startTime = System.nanoTime();
	long rem = unit.toNanos(timeout);

	do {
	try {
	exitValue();
	return true;
	} catch(IllegalThreadStateException ex) {
	if (rem > 0)
	Thread.sleep(
	Math.min(TimeUnit.NANOSECONDS.toMillis(rem) + 1, 100));
	}
	rem = unit.toNanos(timeout) - (System.nanoTime() - startTime);
	} while (rem > 0);
	return false;
	}

	/**
	* Returns the exit value for the subprocess.
	*
	* @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
	*/
	public abstract int exitValue();

	/**
	* Kills the subprocess. Whether the subprocess represented by this
	* {@code Process} object is forcibly terminated or not is
	* implementation dependent.
	*/
	public abstract void destroy();

	/**
	* Kills the subprocess. The subprocess represented by this
	* {@code Process} object is forcibly terminated.
	*
	* <p>The default implementation of this method invokes {@link #destroy}
	* and so may not forcibly terminate the process. Concrete implementations
	* of this class are strongly encouraged to override this method with a
	* compliant implementation. Invoking this method on {@code Process}
	* objects returned by {@link ProcessBuilder#start} and
	* {@link Runtime#exec} will forcibly terminate the process.
	*
	* <p>Note: The subprocess may not terminate immediately.
	* i.e. {@code isAlive()} may return true for a brief period
	* after {@code destroyForcibly()} is called. This method
	* may be chained to {@code waitFor()} if needed.
	*
	* @return the {@code Process} object representing the
	* subprocess to be forcibly destroyed.
	* @since 1.8
	*/
	public Process destroyForcibly() {
	destroy();
	return this;
	}

	/**
	* Tests whether the subprocess represented by this {@code Process} is
	* alive.
	*
	* @return {@code true} if the subprocess represented by this
	* {@code Process} object has not yet terminated.
	* @since 1.8
	*/
	public boolean isAlive() {
	try {
	exitValue();
	return false;
	} catch(IllegalThreadStateException e) {
	return true;
	}
	}
	}

Back to index...