[IO-318] Add Charset sister APIs to method that take a String charset name.

• Type: New Feature
• Status: Closed
• Priority: Major
• Resolution: Fixed
• Fix Version/s: 2.3

Environment

Apache Maven 3.0.4 (r1232337; 2012-01-17 03:44:56-0500)
Maven home: C:\Java\apache-maven-3.0.4\bin\..
Java version: 1.7.0_03, vendor: Oracle Corporation
Java home: C:\Program Files\Java\jdk1.7.0_03\jre
Default locale: en_US, platform encoding: Cp1252
OS name: "windows 7", version: "6.1", arch: "amd64", family: "windows"

• Assignee: Unassigned
• Reporter: Gary D. Gregory
• Created: 30/Mar/12 12:58
• Updated: 08/Nov/16 18:00
• Resolved: 30/Mar/12 15:22

Description

Add Charset sister APIs to method that take a String charset name (aka encoding).
For example: foo(..., String charsetName) -> foo(..., Charset charset).
Refactor such that we do not have code duplication of the algorithms.

Known issue: Source compatibility.

Now there are APIs that change only with the last type, String vs. Charset, you will get a compile error if you pass null to the old String API because the target method will be ambiguous: do you want to call the String or Charset version? You must type-cast to one type or the other.

Known issue: checked java.io.UnsupportedEncodingException vs. unchecked java.nio.charset.UnsupportedCharsetException

The JRE API Charset.forName throws the unchecked UnsupportedCharsetException.
The Commons IO 2.2 String APIs throw the checked UnsupportedEncodingException, a subclass of IOException, when a charset is not available.
The refactored String APIs throw UnsupportedCharsetException from Charset.forName, an unchecked IllegalArgumentException. The String APIs throw IOException, so there is no source compatibility issue.

If you somehow relied on catching the checked UnsupportedEncodingException instead of IOException, its superclass, you should catch the unchecked java.nio.charset.UnsupportedCharsetException to act on the fact that the charset is not available.