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

PrintStream and PrintWriter platform encoding mention is incorrect

    XMLWordPrintable

    Details

    • Type: Bug
    • Status: Open
    • Priority: P4
    • Resolution: Unresolved
    • Affects Version/s: 15
    • Fix Version/s: None
    • Component/s: core-libs
    • Subcomponent:
    • CPU:
      generic
    • OS:
      generic

      Description

      A DESCRIPTION OF THE PROBLEM :
      Follow-up for https://bugs.openjdk.java.net/browse/JDK-8131664
      Related to:
      - https://bugs.openjdk.java.net/browse/JDK-4833833
      - https://bugs.openjdk.java.net/browse/JDK-4916565
      - https://bugs.openjdk.java.net/browse/JDK-5068812

      PrintStream and PrintWriter both support specifying a custom character encoding (Charset), or in the case of PrintWriter even support specifying a Writer and therefore the PrintWriter does not perform any encoding at all.

      Yet some methods only mention that characters will be encoded using the "platform encoding", which is incorrect:
      - PrintStream:
        - write​(int)
        - write​(byte[], int, int)
          Note: This method should probably also refer to `print(char[])` (taking an array parameter) instead of the overloads with a single `char` parameter, similar to `write(byte[])` which also refers to `print(char[])`
        - write(byte[])
        - writeBytes​(byte[])
        - print(boolean)
        - print(int)
        - print(long)
        - print(float)
        - print(double)
        - print(Object)
      - PrintWriter
        - print(boolean)
        - print(char)
        - print(int)
        - print(long)
        - print(float)
        - print(double)
        - print(char[])
        - print(String)
          Note: The javadoc also refers to `write(int)` for writing bytes; this appears to be copied from PrintStream but is incorrect here because PrintWriter.write(int) writes **chars** not bytes.
        - print(Object)
          Note: The javadoc also refers to `write(int)` for writing bytes; this appears to be copied from PrintStream but is incorrect here because PrintWriter.write(int) writes **chars** not bytes.

      It might be best to just completely omit these notes about encoding in the methods and mention it **once** in the class documentation. Currently it just causes a lot of redundance.

      Also some side notes which should ideally be fixed as well (feel free to create separate Jira issues):
      1. The PrintStream class javadoc should use a link instead of only {@code ...} for the reference to `checkError`.
      2. It also might be good to update the javadoc of `PrintStream​(OutputStream, boolean, String)`: All other constructors (even PrintWriter ones) which take a String charset use the parameter name `csn` and link to Charset, yet that constructor calls it `encoding` and links to the package doc.
      3. `PrintWriter.write(char[], int, int)` unnecessarily has "A" and "Portion" capitalized in the javadoc:
      > Writes A Portion of ...
      4. `PrintWriter.write​(char[])` and `write(String)` javadoc contains implementation details which are irrelevant for the user:
      > This method cannot be inherited from the Writer class because it must suppress I/O exceptions.
      5. PrintStream.append(CharSequence) and PrintWriter.append(CharSequence) should link to java.nio.CharBuffer instead of only using the term "character buffer" because not every user might understand which class is meant by this.
      6. `PrintStream.write​(byte[])` `@throws` javadoc is incorrect, it should say
      > @throws IOException Never
      7. PrintWriter.write(int) should explain as detailed as Write.write(int) that the high order 16-bits are ignored. This is currently not clear.


        Attachments

          Issue Links

            Activity

              People

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

                Dates

                Created:
                Updated: