United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
JDK-5108057 : Small Error in JavaDoc for method isEmpty of ConcurrentLinkedQueue

Details
Type:
Bug
Submit Date:
2004-09-28
Status:
Resolved
Updated Date:
2005-09-04
Project Name:
JDK
Resolved Date:
2005-09-04
Component:
core-libs
OS:
windows_xp
Sub-Component:
java.util.concurrent
CPU:
x86
Priority:
P4
Resolution:
Fixed
Affected Versions:
6
Fixed Versions:

Related Reports

Sub Tasks

Description
Name: rmT116609			Date: 09/28/2004


A DESCRIPTION OF THE PROBLEM :

There is an error in your documentation of the isEmpty() method of the newly introduced class ConcurrentLinkedQueue.According to the documentation: "This implementation returns size() == 0." Actually isEmpty() checks whether the first element in the queue is non-null. This is important because it's a constant time operation, unlike size() which is not.

I assume the JavaDoc was copied from another Collection, where the implementation was as described (and size() was a constant time op).

I assume this report might apply to other new classes n the Collections Framework.

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
This implementation returns first() == null.
ACTUAL -
This implementation returns size() == 0.

URL OF FAULTY DOCUMENTATION :
http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/ConcurrentLinkedQueue.html#isEmpty()
(Incident Review ID: 315692) 
======================================================================

                                    

Comments
SUGGESTED FIX

--- /u/martin/ws/mustang/src/share/classes/java/util/concurrent/ConcurrentLinkedQueue.java	2004-08-27 15:54:57.385609000 -0700
+++ /u/martin/ws/jsr166/src/share/classes/java/util/concurrent/ConcurrentLinkedQueue.java	2005-07-17 20:57:21.583998000 -0700
@@ -268,6 +264,11 @@
     }
 
 
+    /**
+     * Returns <tt>true</tt> if this queue contains no elements.
+     *
+     * @return <tt>true</tt> if this queue contains no elements
+     */
     public boolean isEmpty() {
         return first() == null;
     }
                                     
2005-08-14
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
mustang


                                     
2004-09-29
EVALUATION

The statement referring to "this implementation" should simply be removed.

The javadoc is being inherited from AbstractQueue.  It's the usual problem
with javadoc inheritance, that it's convenient, but also error-prone.
###@###.### 2004-09-28
                                     
2004-09-28



Hardware and Software, Engineered to Work Together