Java wait(long timeout)

/**
     * Causes the current thread to wait until either another thread invokes the 
     * {@link java.lang.Object#notify()} method or the 
     * {@link java.lang.Object#notifyAll()} method for this object, or a 
     * specified amount of time has elapsed. 
     * <p>
     * The current thread must own this object's monitor. 
     * <p>
     * This method causes the current thread (call it <var>T</var>) to 
     * place itself in the wait set for this object and then to relinquish 
     * any and all synchronization claims on this object. Thread <var>T</var> 
     * becomes disabled for thread scheduling purposes and lies dormant 
     * until one of four things happens:
     * <ul>
     * <li>Some other thread invokes the <tt>notify</tt> method for this 
     * object and thread <var>T</var> happens to be arbitrarily chosen as 
     * the thread to be awakened. 
     * <li>Some other thread invokes the <tt>notifyAll</tt> method for this 
     * object. 
     * <li>Some other thread {@linkplain Thread#interrupt() interrupts} 
     * thread <var>T</var>. 
     * <li>The specified amount of real time has elapsed, more or less.  If 
     * <tt>timeout</tt> is zero, however, then real time is not taken into 
     * consideration and the thread simply waits until notified. 
     * </ul>
     * The thread <var>T</var> is then removed from the wait set for this 
     * object and re-enabled for thread scheduling. It then competes in the 
     * usual manner with other threads for the right to synchronize on the 
     * object; once it has gained control of the object, all its 
     * synchronization claims on the object are restored to the status quo 
     * ante - that is, to the situation as of the time that the <tt>wait</tt> 
     * method was invoked. Thread <var>T</var> then returns from the 
     * invocation of the <tt>wait</tt> method. Thus, on return from the 
     * <tt>wait</tt> method, the synchronization state of the object and of 
     * thread <tt>T</tt> is exactly as it was when the <tt>wait</tt> method 
     * was invoked. 
     * <p>
     * A thread can also wake up without being notified, interrupted, or
     * timing out, a so-called <i>spurious wakeup</i>.  While this will rarely
     * occur in practice, applications must guard against it by testing for
     * the condition that should have caused the thread to be awakened, and
     * continuing to wait if the condition is not satisfied.  In other words,
     * waits should always occur in loops, like this one:
     * <pre>
     *     synchronized (obj) {
     *         while (<condition does not hold>)
     *             obj.wait(timeout);
     *         ... // Perform action appropriate to condition
     *     }
     * </pre>
     * (For more information on this topic, see Section 3.2.3 in Doug Lea's
     * "Concurrent Programming in Java (Second Edition)" (Addison-Wesley,
     * 2000), or Item 50 in Joshua Bloch's "Effective Java Programming
     * Language Guide" (Addison-Wesley, 2001).
     *
     * <p>If the current thread is {@linkplain java.lang.Thread#interrupt()
     * interrupted} by any thread before or while it is waiting, then an
     * <tt>InterruptedException</tt> is thrown.  This exception is not
     * thrown until the lock status of this object has been restored as
     * described above.
     *
     * <p>
     * Note that the <tt>wait</tt> method, as it places the current thread 
     * into the wait set for this object, unlocks only this object; any 
     * other objects on which the current thread may be synchronized remain 
     * locked while the thread waits.
     * <p>
     * This method should only be called by a thread that is the owner 
     * of this object's monitor. See the <code>notify</code> method for a 
     * description of the ways in which a thread can become the owner of 
     * a monitor. 
     *
     * @param      timeout   the maximum time to wait in milliseconds.
     * @exception  IllegalArgumentException      if the value of timeout is
     *		     negative.
     * @exception  IllegalMonitorStateException  if the current thread is not
     *               the owner of the object's monitor.
     * @exception  InterruptedException if any thread interrupted the
     *             current thread before or while the current thread
     *             was waiting for a notification.  The <i>interrupted
     *             status</i> of the current thread is cleared when
     *             this exception is thrown.
     * @see        java.lang.Object#notify()
     * @see        java.lang.Object#notifyAll()
     */
    public final native void wait(long timeout) throws InterruptedException;