JDK-6311092 : (spec thread) InterruptedException usage doc should not say "if *another* thread has interrupted"
  • Type: Bug
  • Component: core-libs
  • Sub-Component: java.lang
  • Affected Version: 6
  • Priority: P4
  • Status: Resolved
  • Resolution: Fixed
  • OS: generic
  • CPU: generic
  • Submitted: 2005-08-15
  • Updated: 2017-05-16
  • Resolved: 2005-09-30
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 6
6 b55Fixed
Related Reports
Relates :  
Description
This is a problem with unclear documentation of existing behavior (i.e. doc improvement only).
The Java SE javadoc for all @throws and @exception of InterruptedException should be modified as needed to say "if the current thread is interrupted" or "if any thread has interrupted the current thread", rather than "if another thread has interrupted the current thread." The point is that a thread can interrupt itself, so saying "another thread" is misleading, possibly making users think there is some immunity from self-interruption. Using "if the current thread is interrupted" would add consistency with a large number of @throws of InterruptedException in java.util.concurrent.

A quick grep of the Java SE suggests the javadoc of the following files should be inspected/fixed in the Java SE src directory:

./share/classes/com/sun/jndi/ldap/EventQueue.java
./share/classes/java/awt/EventQueue.java
./share/classes/java/awt/MediaTracker.java
./share/classes/java/lang/Object.java
./share/classes/java/lang/Thread.java
./share/classes/sun/misc/ConditionLock.java
./share/classes/sun/misc/Lock.java
./share/classes/sun/misc/Queue.java
./share/classes/com/sun/jdi/event/EventQueue.java

Comments
EVALUATION The scope of this change was initially extended to all @throws of InterruptedException to adopt the above uniform wording everywhere in the Java SE source. However this got snarled up for some method doc as we couldn't agree about how to reword cases such as Object.wait's "interrupted the current thread before or while the current thread was waiting for a notification." And there was concern that related method doc (e.g. Thread.isInterrupted) might need changing too. The discussion turned metaphysical and it was decided to narrow the scope back down and just correct the offending word despite the mild awkwardness this creates. Universal adoption of the simple wording above for all usage of InterruptedException should be attempted later in Mustang or for Dolphin.
23-09-2005

EVALUATION The simple but clear "if the current thread is interrupted" wording from java.util.concurrent seems best.
19-08-2005

SUGGESTED FIX Change @throws and @exception lines like this: "if another thread has interrupted the current thread." to this: "if the current thread is interrupted"
15-08-2005