RFR 8251989: Hex formatter and parser utility

[Roger Riggs]

Hi Chris,

On 8/27/20 9:20 AM, Chris Hegarty wrote:
> Roger,
>
>> On 27 Aug 2020, at 02:34, Roger Riggs <Roger.Riggs at oracle.com> wrote:
>>
>> Please review updates to the formatting and parsing API based on the last round of comments.
>> There are many changes, so it may be useful to read it as a fresh draft.
>>
>>   - Rename classes: Encoder -> Formatter; Decoder -> Parser
>>   - Rename methods: encode -> format; decode -> parse, etc.
>>   - Rename factory methods to match
>>   - Added a factory method and re-arrange arguments to make it more convenient
>>     to create uppercase formatters based on the existing uses.
>>   - The implementation has been updated based on the suggestions and API changes
>>
>> The webrev for applying the API to the security classes will be updated when the API settles down.
>>
>> JavaDoc:
>> http://cr.openjdk.java.net/~rriggs/hex-formatter/java.base/java/util/Hex.html
> 1. "Hex.Formatter formats bytes to a hex string or appends to
>      StringBuilder.”
>
> I wonder if this could be a bit more descriptive. What about something
> like:
>
> “Hex.Formatter transforms sequences of bytes into a formatted
> hexadecimal string.”  What is a formatted hexadecimal string?  “A
> formatted hexadecimal string consists solely of; an optional prefix, a
> pair of hexadecimal characters ( THESE ARE ALREADY DEFINED ELSEWHERE),
> an optional delimiter, and an optional suffix.”  Or some such wording.
Thanks for the suggestion.

I was expecting that the brief description in the Hex class would lead
to the more complete desriptions in the Formatter and Parser classes
and avoid duplication.

* {@link Formatter} Hex.Formatter transforms sequences of bytes into a 
formatted * hexadecimal string. * A formatted hexadecimal string 
consists solely of an optional prefix, * a sequence of pairs of 
hexadecimal characters, an optional delimiter between each pair of * 
hexadecimal characters, and an optional suffix. * The {@link 
#formatter() canonical formatter} with an empty prefix, suffix, * and 
delimiter, provides unformatted (plain) encoder functionality.



>
> 2. I like the move to formatter/parser, but I now find myself looking
> for an encoder/decoder ;-) It might be obvious, but could be worth
> calling out explicitly, e.g. “A formatter with an empty prefix, suffix,
> and delimiter, provides unformatted (plain) encoder functionality".
> Similar for parser.   Maybe this is what “canonical” is referring to?
> If so, I think it would be best to define it somewhere.
Yes, that's the canonical formatter.
>
> 3. "The Hex class consists solely of factory methods for hexadecimal
> (hex) formatters and parsers.”
>
> It could be worth generalising the class-level description now, so as
> to allow space for additional convenience methods in the future. ( A
> while back I suggested not adding convenience methods yet, but I see
> that Mark has suggested a couple of key conveniences )
Fair enough.

Another thought though,  both the Formatter and Parser classes contain
only the parameter (and they the same parameters). With as few format 
methods
and parse methods, it could collapse down to just the Hex instances with 
the parameters
and having both the format and parse methods.  All of the behavior is in 
the methods,
not the class.  Though it does collapse the name space.

Thanks, Roger

>
> -Chris.
>