RFR: 8349121: SSLParameters.setApplicationProtocols() ALPN example could be clarified [v3]

[Bradford Wetmore]

On Thu, 6 Feb 2025 19:10:04 GMT, Artur Barashev <abarashev at openjdk.org> wrote:

>> Bradford Wetmore has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Codereview Comments
>
> src/java.base/share/classes/javax/net/ssl/SSLParameters.java line 666:
> 
>> 664:      *     byte[] bytes = HUK_UN_I.getBytes(StandardCharsets.UTF_8);
>> 665:      *
>> 666:      *     // Preserve network byte order by using ISO_8859_1 encoding
> 
> I find `network byte order` wording rather confusing, everything here is big-endian, but I guess that's not what we really mean by that, we really care about encoding. I would just put `Convert to the default ALPN encoding` comment here.

RFC 7301 says:

    o  Identification Sequence: The precise set of octet values that
      identifies the protocol.  This could be the UTF-8 encoding
      [[RFC3629](https://datatracker.ietf.org/doc/html/rfc3629)] of the protocol name.

I'll change to `octet byte ordering`.

> src/java.base/share/classes/javax/net/ssl/SSLParameters.java line 668:
> 
>> 666:      *     // Preserve network byte order by using ISO_8859_1 encoding
>> 667:      *     String encodedHukUnI =
>> 668:      *         new String(bytes, StandardCharsets.ISO_8859_1);
> 
> `ISO_8859_1` is the default ALPN encoding but it can be modified by setting `jdk.tls.alpnCharset` system property. We don't mention it.

We usually don't mention the various properties in the javadoc specifications, but [we do in the documentation](https://docs.oracle.com/en/java/javase/23/security/java-secure-socket-extension-jsse-reference-guide.html#GUID-05DB7FDA-2FAE-457D-AF7A-6B22E2A6402E).

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

PR Review Comment: https://git.openjdk.org/jdk/pull/23379#discussion_r1945298176
PR Review Comment: https://git.openjdk.org/jdk/pull/23379#discussion_r1945295071