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. 
     * 

     * The current thread must own this object's monitor. 
     * 

     * This method causes the current thread (call it T) to 
     * place itself in the wait set for this object and then to relinquish 
     * any and all synchronization claims on this object. Thread T 
     * becomes disabled for thread scheduling purposes and lies dormant 
     * until one of four things happens:
     * 

     * 
Some other thread invokes the notify method for this 
     * object and thread T happens to be arbitrarily chosen as 
     * the thread to be awakened. 
     * 
Some other thread invokes the notifyAll method for this 
     * object. 
     * 
Some other thread {@linkplain Thread#interrupt() interrupts} 
     * thread T. 
     * 
The specified amount of real time has elapsed, more or less.  If 
     * timeout is zero, however, then real time is not taken into 
     * consideration and the thread simply waits until notified. 
     * 
     * The thread T 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 wait 
     * method was invoked. Thread T then returns from the 
     * invocation of the wait method. Thus, on return from the 
     * wait method, the synchronization state of the object and of 
     * thread T is exactly as it was when the wait method 
     * was invoked. 
     * 

     * A thread can also wake up without being notified, interrupted, or
     * timing out, a so-called spurious wakeup.  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:
     * 

     *     synchronized (obj) {
     *         while ()
     *             obj.wait(timeout);
     *         ... // Perform action appropriate to condition
     *     }
     * 
* (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).
*
* If the current thread is {@linkplain java.lang.Thread#interrupt()
* interrupted} by any thread before or while it is waiting, then an
* InterruptedException is thrown.  This exception is not
* thrown until the lock status of this object has been restored as
* described above.
*
* 
* Note that the wait 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.
* 
* This method should only be called by a thread that is the owner 
* of this object's monitor. See the  notify  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 interrupted
*             status 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;