RFR 8251989: Hex encoder and decoder utility

[Roger Riggs]

Paul,

Thanks for the review, there are a number of updates pending.

On 8/24/20 4:55 PM, Paul Sandoz wrote:
> Hi Roger,
>
> A nice minimal addition. I agree with Mark’s naming suggestion.
>
> - Use appropriate code convention for static field names.
>
> - The encoder comes with two encoding production signatures, that returning a String and that for encoding into a StringBuilder.
> The decoder comes with just one such production signature, returning byte[]. I imagine one might need a decode into a byte[] from a given offset.
> Something to consider later if need be?
The initial step covers the existing cases in the JDK and tests.
The API and error handling get more complex when trying to decode into a 
buffer that's been allocated already.
>
> - More generally if there is pressure to add ByteBuffer accepting signatures we can punt and if necessary use MemorySegment once it exits incubating.
Easy enough to add when conditions are suitable.
>
>>   36  * Utilities to encode bytes to hex strings and decode hex strings to bytes.
>
> I recommend using “hexadecimal (hex)” for the first use, and “hex” thereafter.
ok
>
>
>>   48  * For example, for a comma (",") separated format with a prefix and suffix
>
> Use an @apiNote
>
ok
>>   63  *     Hex.Encoder encodeFingerprint = Hex.encoder(":", "", "",true);
>
> Missing space after last comma.
fixed
>
>
>>   60  * RFC 4752 defines a fingerprint of byte values that uses the delimiter colon {@code ':'}.
>>   61  * The encoder and decoder for RFC 2752 are:
>
> s/2752/4752 ?
typo fixed
>
>
>> 254         public StringBuilder encodeHexPair(StringBuilder sb, int value) {
>
> This can be specified as behaving as if sb.append(toHexPair(value)), and also say @see #toHexPair.
ok

Thanks, Roger

>
> Paul.
>
>> On Aug 19, 2020, at 2:14 PM, Roger Riggs <Roger.Riggs at oracle.com> wrote:
>>
>> Please review a java.util.Hex API to encode and decode hexadecimal strings to and from byte arrays.
>>
>> Within the JDK and JDK tests there are multiple implementations to encode and decode
>> hexadecimal strings to byte arrays. Hex encoders and decoders support
>> upper or lower case hexadecimal characters, delimiters, prefix, and suffix.
>> The API is modeled after the java.util.Base64 API providing static factories,
>> immutable threadsafe instances with methods to encode to and decode from
>> string and StringBuilder.
>>
>> JavaDoc:
>> http://cr.openjdk.java.net/~rriggs/hex-javadoc/java.base/java/util/Hex.html
>>
>> Webrev for Hex encoder and decoder:
>>     http://cr.openjdk.java.net/~rriggs/webrev-hex-encoder-8251989
>>
>> Webrev for applying to java.security:
>>     http://cr.openjdk.java.net/~rriggs/webrev-hex-security-8252055
>>
>> CSR:
>>     https://bugs.openjdk.java.net/browse/JDK-8251991
>>
>> Issue for API and a few uses:
>>     https://bugs.openjdk.java.net/browse/JDK-8251989
>>
>> Issue for Use in java.security and tests:
>>     https://bugs.openjdk.java.net/browse/JDK-8252055
>>