JDK-8183743 : Umbrella: add overloads that take a Charset parameter
  • Type: Enhancement
  • Component: core-libs
  • Sub-Component: java.io
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • Submitted: 2017-07-05
  • Updated: 2017-12-15
  • Resolved: 2017-12-12
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 10
10 b36Fixed
Related Reports
CSR :  
Duplicate :  
Duplicate :  
Duplicate :  
Relates :  
Relates :  
Relates :  
Relates :  
Relates :  
Description
There are a variety of APIs in the libraries that convert byte[] to String and vice-versa, thus requiring use of a charset. Some APIs don't take any charset-related parameters at all, relying on the platform default charset or on a specified default (UTF-8). Some APIs take a charset name parameter (a String) which is inconvenient for a variety of reasons. All of these cases should have overloads added that take a Charset object as a parameter.

For example, these APIs take a charset name:

    ByteArrayOutputStream.toString(csname)
    PrintStream(File, csname)
    PrintStream(filename, csname)
    PrintWriter(File, csname)
    PrintWriter(filename, csname)

and are declared to throw UnsupportedEncodingException, which is checked, making them inconvenient to use. (Although UEE is a subtype of IOException, and calls to these often, but not always, occur in contexts where IOException is caught or declared.) Other APIs throw IllegalArgumentException if the charset name is invalid:

    Scanner(File, csname)
    ... other Scanner constructor overloads ...

This is less inconvenient, however, for programmability, one always has to look up or remember the right name. (Is it "UTF_8" to be consistent with StandardCharsets.UTF_8? No, it's "UTF-8".)

Still other APIs don't have any charset-related parameters at all:

    FileReader(File)
    FileReader(FileDescriptor)
    FileReader(filename)
    FileWriter(File)
    FileWriter(File, append)
    FileWriter(FileDescriptor)
    FileWriter(filename)
    FileWriter(filename, append)

In all these cases an overload taking a Charset parameter should be added.

This isn't an exhaustive list. The APIs should be audited for additional occurrences of APIs that have similar issues.

Comments
A list of candidate classes in the java.base module java.io src/java.base/share/classes/java/io/ByteArrayOutputStream.java src/java.base/share/classes/java/io/PrintStream.java src/java.base/share/classes/java/io/PrintWriter.java java.net src/java.base/share/classes/java/net/URLDecoder.java src/java.base/share/classes/java/net/URLEncoder.java java.nio src/java.base/share/classes/java/nio/channels/Channels.java java.util src/java.base/share/classes/java/util/Formatter.java src/java.base/share/classes/java/util/Properties.java src/java.base/share/classes/java/util/Scanner.java
02-11-2017

I put this in the java.io subcomponent because most of the affected APIs are here. However, some affected APIs might not be in java.io (e.g., Scanner). I've also linked several related issues to this one. This issue might be turned into an umbrella issue, and those issues be turned into subtasks of this one.
05-07-2017