On Fri, 29 Oct 2021 10:07:45 GMT, Michael McMahon <micha...@openjdk.org> wrote:
>> src/jdk.httpserver/share/classes/com/sun/net/httpserver/BasicAuthenticator.java
>> line 77:
>>
>>> 75: * <p>Where a backslash ("\") is used as quoting mechanism within
>>> the realm
>>> 76: * string, it must be escaped by two preceding backslashes, for
>>> example
>>> 77: * {@code "foo\\\"bar\\\""} will be embedded as {@code
>>> "foo\"bar\""}.
>>
>> I would drop this sentence as I find it confusing - even though I understand
>> what you are trying to say.
>>
>> I would replace it with something like:
>>
>>
>> The value of the {@code realm} parameter will be embedded in a quoted
>> string. Any quote it contains must be escaped by the caller.
>
> I still think it is too much of a corner case to impose on the API doc so
> much. How about changing the @throws to
>
>
> * @throws IllegalArgumentException if realm is an empty string or is
> not correctly
> * escaped, as specified in <a
> href="https://tools.ietf.org/html/rfc7230#section-3.2";>
> * RFC 7230 section-3.2</a>.
> ```
OK - but then I'd still say: `The value of the {@code realm} parameter will be
embedded in a quoted string.`
Otherwise the caller might think they need to provide a quoted string such as:
"\\"realm\\"" which would end up as realm=""realm"" over the wire, with double
double quotes.
-------------
PR: https://git.openjdk.java.net/jdk/pull/6117
