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

[Alan Bateman]

On Fri, 17 Nov 2023 16:15:46 GMT, Darragh Clarke <dclarke 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 158:

> 156:      * If any consecutive well-formed escape sequences cannot
> 157:      * be decoded as a sequence of characters in the supplied {@code Charset}
> 158:      * {@linkplain java.nio.charset.CharsetDecoder##cae the replacement character} will be used.

I think it would be a bit clearer to say that erroneous bytes are replaced with the Charset's replacement value.

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.

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

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