Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8175371

java.util.RandomAccess API documentation incorrect

    XMLWordPrintable

Details

    Description

      A DESCRIPTION OF THE PROBLEM :
      The following description in the API documentation of java.util.RandomAccess is incorrect since Iterator implementation internally is optimized based on actual type of the collection implementation :

      As a rule of thumb, a List implementation should implement this interface if, for typical instances of the class, this loop:
           for (int i=0, n=list.size(); i < n; i++)
               list.get(i);
       
      runs faster than this loop:
           for (Iterator i=list.iterator(); i.hasNext(); )
               i.next();
       

      EXPECTED VERSUS ACTUAL BEHAVIOR :
      EXPECTED -
      The above documentation is misleading and should be removed since Iterator.next() should be optimized based on the type of implementation. i.e. the Iterator implementation for a list whose type is LinkedList is different that the one whose type is ArrayList and in both cases they are optimized to return sequentially in case of LinkedList and indexed in case of ArrayList.
      ACTUAL -
      As a rule of thumb, a List implementation should implement this interface if, for typical instances of the class, this loop:
           for (int i=0, n=list.size(); i < n; i++)
               list.get(i);
       
      runs faster than this loop:
           for (Iterator i=list.iterator(); i.hasNext(); )
               i.next();


      URL OF FAULTY DOCUMENTATION :
      https://docs.oracle.com/javase/8/docs/api/java/util/RandomAccess.html

      Attachments

        Activity

          People

            smarks Stuart Marks
            webbuggrp Webbug Group
            Votes:
            0 Vote for this issue
            Watchers:
            4 Start watching this issue

            Dates

              Created:
              Updated:
              Resolved: