RFR: 8316734: URLEncoder should specify that replacement bytes will be used in case of coding error

[Daniel Fuchs]

On Sun, 19 Nov 2023 14:38:32 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>> Currently the descriptions of `URLEncoder.encode` and `URLDecoder.decode` don't specify their use of replacement bytes or replacement character when they cannot handle a character or sequence of bytes. This is longstanding behavior but needs to be documented.
>> 
>> **Solution**
>> - Added a new line to `URLEncoder.encode` API documentation to document that the charset's replacement bytes are used.
>> 
>> - Also changed `URLDecoder.decode` API documentation to document its use of the charset's replacement character, also changed some wording.
>
> src/java.base/share/classes/java/net/URLDecoder.java line 168:
> 
>> 166:      * @throws NullPointerException if {@code s} or {@code charset} is {@code null}
>> 167:      * @throws IllegalArgumentException if the implementation encounters malformed
>> 168:      * escape sequences
> 
> The method specifies that it throws IAE, the implNote seems to be saying the same thing, do I read this correctly? I'm wondering if the implNote can be removed.

That's a good point. I see that there's another `decode(String, String)` method above in this file that has the same old `@implNote` but not `@throws`. Maybe the implNote should be removed there too and the `@throws` added. 
Not sure it's worth touching the first `@Deprecated decode(String)` method though. Opinions?

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/16709#discussion_r1399150483