(process) Add Process.ID and Process.waitFor(long timeout)

Name: rmT116609 Date: 07/15/2003


A DESCRIPTION OF THE REQUEST :
The Process class, as implemented by UNIXProcess, can easily be improved
to provide access to the process ID (PID) already in UNIXProcess, and to
to the timeout capability of the wait method used by the waitFor method
by the following trivial modifications:

/* Process patch.

    The following two methods - waitFor(long) and ID() - add access to
    the timeout argument of Object.wait that is not provided by the
    existing waitFor method, and the Unix process identification (PID)
    value for which their is no existing accessor. These methods have
    absolutely no affect, direct or indirect, on the existing class
    functionality.

    These are abstract methods which must be implemented in the host OS
    dependent class. For Unix systems this is the UNIXProcess class.
    The accompanying UNIXProcess.patch file provides appropriate java
    code implementations.

    This patch is based on version 1.19 (02/04/04) of the Process.java
    file distributed by Sun Microsystems, Inc. for Java 1.4.

    Author: Bradford Castalia, UA/PIRL, 5/03.
    PIRL CVS ID: $Id: Process.patch,v 1.1 2003/06/16 00:41:12 castalia Exp $
*/

    /**
     * Causes the current thread to wait, if necessary, until the
     * process represented by this <code>Process</code> object has
     * terminated or the timeout period has expired. This method returns
     * immediately if the subprocess has already terminated. If the
     * subprocess has not yet terminated, the calling thread will be
     * blocked. If the subprocess exits while the thread is blocked
     * the exit status of the subprocess will be returned. If the timeout
     * period expires while the thread is blocked an IOException will
     * be thrown.
     *
     * @param timeout the maximum amount of time, in milliseconds,
     * to wait on subprocess exit (if <= 0, wait forever).
     * @return the exit value of the process. By convention,
     * <code>0</code> indicates normal termination.
     * @exception InterruptedException if the current thread is
     * {@link Thread#interrupt() interrupted} by another thread
     * while it is waiting, then the wait is ended and an
     * <code>InterruptedException</code> is thrown.
     */
    abstract public int waitFor(long timeout)
        throws InterruptedException, IOException;

    /**
     * Gets the Process ID that uniquely identifies the system process.
     *
     * @return the integer ID used by the system to identify the process.
     */
    abstract public int ID();


/* UXIXProcess patch.

    The following two methods - waitFor(long) and ID() - add access to
    the timeout argument of Object.wait that is not provided by the
    existing waitFor method, and the Unix process identification (PID)
    value for which their is no existing accessor. These methods have
    absolutely no affect, direct or indirect, on the existing class
    functionality.

    These methods access the "hasExited", "exitcode", and "pid"
    variable values of the existing class code. They only read these
    values; they do not change them in any way. These variable names
    existed in version 1.34 (02/02/25) of the UNIXProcess.java files
    used in the implementation of the UNIXProcess class by Sun
    Microsystems, Inc. for the Java 1.4 version on Solaris, Linux and
    OS-X.

    These methods implement abstract methods that must be specified in
    the abstract Process class. The accompanying Process.patch file
    provides appropriate java code implementations.

    Author: Bradford Castalia, UA/PIRL, 5/03.
    PIRL CVS ID: $Id: UNIXProcess.patch,v 1.1 2003/06/16 00:41:13 castalia Exp $
*/
    public synchronized int waitFor(long timeout)
        throws InterruptedException, IOException {
    if (timeout < 0)
        timeout = 0;
    while (!hasExited) {
        wait(timeout);
        if (!hasExited)
            throw new IOException ("process timeout");
        }
    return exitcode;
    }

    public int ID() {
    return pid;
    }


JUSTIFICATION :
The PID is necessary to uniquely identify the subprocess that has
been forked; it is used for system administration purposes.

The waitFor with a timeout is necessary to prevent the method from
waiting indefinately on a hung process or a process that is running
longer than its parent deems appropriate.


EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
Availability to the Process class user (via Runtime) of capabilities
already present in the UNIXProcess implementation. These capabilities
are important for many process management purposes.

ACTUAL -
Existing capabilities of UNIXProcess are not externally accessable.


CUSTOMER SUBMITTED WORKAROUND :
Apply the patches provided to the java/lang/Process.class and
java/lang/UNIXProcess.class files in the jre/lib/rt.jar. This is
done by adding the method code to the end of the corresponding
Process.java and UNIXProcess.java files available from the
src.zip distributed with the SDK, compiling the upgraded code and
updating (jar -u) the rt.jar file.

A complete patch kit with detailed instructions is available in
the ftp://PIRL.LPL.Arizona.edu/pub/Java/Process.patch-1.4.tar.gz
tarball.
(Incident Review ID: 191550)
======================================================================