United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: JDK-4885372 Order of method descriptions can change from one run to the next
JDK-4885372 : Order of method descriptions can change from one run to the next

Details
Type:
Bug
Submit Date:
2003-06-28
Status:
Resolved
Updated Date:
2003-09-29
Project Name:
JDK
Resolved Date:
2003-09-29
Component:
docs
OS:
other
Sub-Component:
doclet
CPU:
generic
Priority:
P3
Resolution:
Fixed
Affected Versions:
1.4.2
Fixed Versions:
5.0 (tiger)

Related Reports

Sub Tasks

Description
The order of method descriptions can change from one javadoc run to the next
using the same version of javadoc, the same source files, and the same javadoc
call.  I used Java 2 SDK 1.4.2 build 26 for these tests.  Alan Sommerer 
has observed the same phenomenon in earlier versions.

I rely on the order being the same when running diffs between versions
for JCP reviews of the J2SE API spec.  

To re-state, I notice that when I run a full build of Java 2 SDK including 
docs, save those docs,then do another build, the method descriptions can
be in a different order.

For example,in the "Uses of java.awt.Color"page, here are two 
different orders of methods in the table.  Notice "getBorderColor()"
is the fourth method in the first list but the second method in the
second list.

-----------------------------------------------------
http://javapubs.sfbay/ws/mantis-docs-GA/build/solaris-sparc/doc/api/java/awt/class-use/Color.html

Methods in javax.swing.plaf.basic that return Color

  protected Color BasicTreeUI.getHashColor()

            Color BasicToolBarUI.getDockingColor()
            Gets the color displayed when over a docking area

            Color BasicToolBarUI.getFloatingColor()
            Gets the color displayed when over a floating area

            Color BasicToolBarUI.DragWindow.getBorderColor()

-----------------------------------------------------
http://swpubs.sfbay/javadoc/ws-mantis-promoted/doc/api/java/awt/class-use/Color.html

Methods in javax.swing.plaf.basic that return Color

  protected Color BasicTreeUI.getHashColor()

            Color BasicToolBarUI.DragWindow.getBorderColor()

            Color BasicToolBarUI.getDockingColor()
            Gets the color displayed when over a docking area

            Color BasicToolBarUI.getFloatingColor()
            Gets the color displayed when over a floating area
-----------------------------------------------------

The above is one example discovered by doing these diffs:

#!/bin/ksh -x
diff -r /java/re/jdk/1.4.2/promoted/rc/b26/doc/api /java/pubs/ws/mantis-docs-GA/build/solaris-sparc/doc/api > diff-keywords.log

The diffs from that file were distilled and then attached as 
diff-keywords-ESSENTIAL.log
I have deleted non-essential parts of the diffs from this file to show
only which files were being diffed and their differences.  In nearly all
cases, the only diffs are due to the order of members being different.

                                    

Comments
PUBLIC COMMENTS

The wrong data structure is being used to store the methods that use a given class.  We should be using HashSets, not ArrayLists.  That way, the methods are always sorted and we don't get this random ordering.  I will fix this within the next couple of days.
###@###.### 2003-06-30

This bug fix is pending review and will be putback as soon as possible.

###@###.### 2003-07-12

This bug has been fixed.
###@###.### 2003-09-28
                                     
2003-06-30
EVALUATION

This is an easy fix.  Simply use HashSets to store the documented methods instead of ArrayLists.  I believe the main cause of this randomness is method RootDoc.classes().  That method seems to return the list of classes in random order.
###@###.### 2003-06-30

This bug has been fixed.  I ended up using a TreeMap because methods can't be inserted into HashSets.  Javadoc incorrectly uses the name of the method as the comparable value.  This doesn't work because there are lots of overloaded methods that have equal names, but not equal signatures.  Instead, I store the members in a TreeMap with the signature as the key.  That way, the order of these methods in the class-use page is always the same, even though the order of classes returned by RootDoc.classes() is not always the same.  We should fix that because it is definitely unexpected behaviour.

This bug fix is pending review and will be putback as soon as possible.

###@###.### 2003-07-12

This bug was fixed after refactoring.  It is no longer reproducible.  In the class use documentation, the members always appear in the same order that they appear int he source.
                                     
2003-07-12
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
tiger

FIXED IN:
tiger

INTEGRATED IN:
tiger


                                     
2004-06-14



Hardware and Software, Engineered to Work Together