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

Further clarify InputStream#available()

    Details

    • Subcomponent:
    • Resolved In Build:
      b05

      Description

      A DESCRIPTION OF THE REQUEST :
      InputStream#available() is documented as follows:

      "Returns an estimate of the number of bytes that can be read (or skipped over) from this input stream without blocking or {@code 0} when it reaches the end of the input stream."

      This should be changed to one of the following:

      (a) "Returns an estimate of the number of bytes that can be read (or skipped over) from this input stream without blocking, which may be 0, or 0 when it reaches the end of the input stream."

      (b) "Returns an estimate of the number of bytes that can be read (or skipped over) from this input stream without blocking, which will always be greater than 0, or 0 when it reaches the end of the input stream."



      JUSTIFICATION :
      Unclear documentation creates bugs.

      I have been assuming interpretation (a) is correct my entire life, but multiple during code review, another developer has used (b) as part of an argument for why they should be allowed to call it. It seems like this problem would be avoided if the method would explicitly document whether 0 is a possible return value in the first case.



        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                bpb Brian Burkhalter
                Reporter:
                webbuggrp Webbug Group
              • Votes:
                0 Vote for this issue
                Watchers:
                3 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: