RFR 8251989: Hex encoder and decoder utility

[Roger Riggs]

Hi Tagir,

On 8/21/20 6:15 AM, Tagir Valeev wrote:
> Hello!
>
> Great and long-awaited API, thanks!
>
> How about wither-style construction? Like
> Hex.encoder().upperCase().withDelimiter(":").wrappedIn("{", "}"). This
> allows modifying existing encoder (e.g. adding prefix and suffix,
> preserving delimiter and case). Also, you can specify only necessary
> parameters and in any order you like.
That fluent design style reduces the number of factory methods and adds 
a few instance methods.
That form was used consistently in the java.time APIs.  As en/decoders 
are immutable
it would return a new/differ en/decoder with the desired behavior. The 
naming of the factory
methods as you show makes reading the construction easier and more fluid.

The instance methods would fall into two categories, those that act as 
factories
for new en/decoders and those that perform the function.

>
> encode() method implementation has duplicate requireNonNull checks:
>
> 286         public StringBuilder encode(StringBuilder sb, byte[]
> bytes, int index, int length) {
> 287             Objects.requireNonNull(sb, "sb");
> 288             Objects.requireNonNull(bytes, "bytes");
> 289             sb.append(prefix);
> 290             Objects.requireNonNull(sb, "sb");
> 291             Objects.requireNonNull(bytes, "bytes");

Thanks, fixed in the next webrev.

Roger

>
> With best regards,
> Tagir Valeev.
>
> On Thu, Aug 20, 2020 at 4:15 AM 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
>>