JDK-4310779 : (spec thread) Incomplete spec for Thread.{sleep(),join()} signatures that take arguments
  • Type: Bug
  • Component: core-libs
  • Sub-Component: java.lang
  • Affected Version: 1.3.0,1.3.1,1.4.1,7
  • Priority: P3
  • Status: Closed
  • Resolution: Fixed
  • OS: generic,solaris_2.5
  • CPU: generic,sparc
  • Submitted: 2000-02-08
  • Updated: 2017-05-16
  • Resolved: 2011-05-18
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 7 Other
7 b18Fixed OpenJDK6Fixed
Related Reports
Duplicate :  
JDK-4712553 - (spec thread) Thread.join(long) missing "@throws IllegalArgumentException"
Duplicate :  
JDK-4712520 - (spec thread) Thread.sleep(long) missing "@throws IllegalArgumentException"
Relates :  
JDK-4189292 - (thread spec) ThreadGroup and Thread need better and tighter specs
Description
Name: vsC97678			Date: 02/08/2000


Javadoc for J2SE v1.3 does not describe any possible exception thrown
in case of negative input parameter in sleep(long millis) method.
Actually, the implementation (JDK 1.3) throws the IllegalArgumentException
which should be documented.

======================================================================
The situation with the single arg join method is identical and the two arg join method has a typo in the @exception too.
Comments
EVALUATION The specification for java.lang.Thread.join(long) does not describe the behavior of this method if the input parameter is negative. The long standing behavior of the implementation is to throw IllegalArgumentException for a negative value. The specification of java.lang.Thread.join(long, int) already defines this behavior for a negative value for the long parameter. java.lang.Thread.sleep(long) has the same problem as join. The solution is to clarify the behavior of these two methods in the case where a negative value is passed.
17-07-2007
EVALUATION There are current JCK tests for out of range args to both sleep and join methods, so this change aligns the spec with the relevant JCK tests also.
23-04-2007
SUGGESTED FIX For two arg signatures, also: "nanosecond timeout value out of range"
23-04-2007
SUGGESTED FIX --- /home/psoper/public_html/webrev/4385444_070508140106/./src/share/classes/java/lang/Thread.java- Tue May 8 14:03:51 2007 +++ Thread.java Tue May 8 14:00:57 2007 @@ -120,11 +120,11 @@ * Every thread has a name for identification purposes. More than * one thread may have the same name. If a name is not specified when * a thread is created, a new name is generated for it. * * @author unascribed - * @version 1.177, 03/13/07 + * @version 1.178, 05/08/07 * @see Runnable * @see Runtime#exit(int) * @see #run() * @see #stop() * @since JDK1.0 @@ -272,10 +272,11 @@ * execution) for the specified number of milliseconds, subject to * the precision and accuracy of system timers and schedulers. The thread * does not lose ownership of any monitors. * * @param millis the length of time to sleep in milliseconds. + * @exception IllegalArgumentException if the value of millis is negative * @exception InterruptedException if any thread has interrupted * the current thread. The <i>interrupted status</i> of the * current thread is cleared when this exception is thrown. * @see Object#notify() */ @@ -1141,10 +1142,11 @@ /** * Waits at most <code>millis</code> milliseconds for this thread to * die. A timeout of <code>0</code> means to wait forever. * * @param millis the time to wait in milliseconds. + * @exception IllegalArgumentException if the value of millis is negative * @exception InterruptedException if any thread has interrupted * the current thread. The <i>interrupted status</i> of the * current thread is cleared when this exception is thrown. */ public final synchronized void join(long millis) @@ -1177,11 +1179,11 @@ * <code>nanos</code> nanoseconds for this thread to die. * * @param millis the time to wait in milliseconds. * @param nanos 0-999999 additional nanoseconds to wait. * @exception IllegalArgumentException if the value of millis is negative - * the value of nanos is not in the range 0-999999. + * or the value of nanos is not in the range 0-999999. * @exception InterruptedException if any thread has interrupted * the current thread. The <i>interrupted status</i> of the * current thread is cleared when this exception is thrown. */ public final synchronized void join(long millis, int nanos)
26-09-2005
EVALUATION This is a long standing omission from the Thread.sleep(long) javadoc.
26-09-2005