[11] RFR: 8170769 Provide a simple hexdump facility for binary data

[Vincent Ryan]

Thanks Roger for your comments.

The main motivator for this class is to provide a basic hex. encoder/decoder for smaller amounts of binary data
and to provide a hexdump encoder for larger amounts of binary data, while recognising the need to cater for
custom formats too.

The class does not attempt to satisfy every custom format. Instead it provides some basic formatting methods
and functions from which a wide variety of custom formats can be constructed. Developers can also write their
own formatting functions to use with this class.

More comments in-line below.


> On 9 May 2018, at 16:20, Roger Riggs <Roger.Riggs at oracle.com> wrote:
> 
> Hi Vinnie,
> 
> On the API and spec, a few comments:
> 
>  - Expanding the printable string from ASCII to ISO-8859-1 would make it a bit more useful in more cases.
>    That might suggest using the Charset converter to do the work (less optimized but more functional).

Yes adding support for additional charsets could be useful but it is a tradeoff against cluttering the API.
I think ASCII is sufficient for the common case.


> 
> - There is no API support for ByteBuffers, another common source of bytes, that would make a good addition
>    for completeness.  John Rose suggested a ByteSequence interface in the context of file processing but
>    that hasn't settled down.

Support for byte buffers was requested before and I suggested wrapping in an I/O stream.
Is that acceptable?


> 
> - The class name "Hex" might be a bit more evocative as HexDump or HexConverter.

I tried to keep the class name short as many of its method names are long.


> 
> - Method names;  the "Hex" in method names might be unnecessary/redundant since, as static methods,
>   they would frequently appear in code as "Hex.fromHexString" and a simple "Hex.fromString" would be fine.
>   Ditto,  toHexString(bytes) -> toString(bytes)…

I agree the repetition is ugly. Shortening to fromString() and toString() is appealing except for the possible
confusion with Object.toString


> 
> - There are not many forms that allow the formatter to be supplied, for example, dump(in, out) might be
>   a case where a formatter would be desired.

The 3 dump methods are just convenience functions around the stream generators. The dumpAsStream
methods are the expected entry points for customizers.


> 
> - Hex.Formatter interface could have a default method that provides the default formatting or as
>   a static method so it can be used with a method reference.

Sure. What do you suggest?


> 
> - On the example in the class javadoc, I would use the implementation of the default formatter with both hex and ascii
>   to show how that works.

Can you give me an example?


> 
>  - As Max observes, being able to supply the delimiters might be a good addition.  (I'm thinking IP addresses too).

Sure. Add another toHexString method that takes a delimiter character?


> 
> It looks quite good and very useful.
> 
> Thanks, Roger
> 
> On 5/8/2018 10:34 PM, Weijun Wang wrote:
>> Nice tool.
>> 
>> However, I am not sure how toFormattedHexString() and toPrintableString() are useful, seems only for providing a customizable dump format which is, actually, not very customizable.
>> 
>> For me, toHexString and fromHexString are of course the most useful methods. As for dump, I can only think of
>> 
>> 1. The existing sun.security.HexDumpEncoder format, when I want to dump a lot of bytes as a block
>> 2. "00:11:22:33:AA:BB:CC" which fits in one line and also easy to read, when I want inline debugging output
>> 
>> If the customizable dump method is both powerful and simple enough to create 2) above, I'll be happy. Otherwise, I can live with toHexString().replaceAll("(..)(?=.)", "$1:”).
>> 
>> Thanks
>> Max
>> 
>>> On May 4, 2018, at 4:22 AM, Vincent Ryan <Vincent.X.Ryan at oracle.com> wrote:
>>> 
>>> Hello,
>>> 
>>> Please review this proposal for a new API to conveniently generate and display binary data using hex string representation.
>>> It supports both bulk and stream operations and it can also generate the well-known hexdump format [1].
>>> 
>>> Thanks
>>> 
>>> 
>>> Bug: https://bugs.openjdk.java.net/browse/JDK-8170769
>>> API: http://cr.openjdk.java.net/~vinnie/8170769/javadoc.05/api/java.base/java/util/Hex.html
>>> Webrev: http://cr.openjdk.java.net/~vinnie/8170769/webrev.05/
>>> 
>>> ____
>>> [1] https://docs.oracle.com/cd/E86824_01/html/E54763/hexdump-1.html
>