Class HexDumper

  • All Implemented Interfaces:
    java.io.Closeable, java.io.Flushable, java.lang.AutoCloseable

    @NotThreadSafe
    public final class HexDumper
    extends java.io.OutputStream
    Hex Dump Utility.

    This class takes binary data and prints it out in a way that humans can read. It's just like the hex dump programs you remembered as a kid. There a column on the left for the address (or offset) in decimal, the middle columns are each digit in hexadecimal, and the column on the right is the ASCII representation where non-printable characters are represented by '.'.

    It's easiest to generate a simple String by calling dumpHex(byte[]), or you can stream data with HexDumper(Writer, int, int).

    Example output:

       
       [222 bytes total]
       00000000  90 0d 03 00  08 03 35 58  61 46 fd f3  f3 73 01 88  ......5XaF...s..
       00000016  cd 04 00 03  08 00 37 05  02 52 09 3f  8d 30 1c 45  ......7..R.?.0.E
       00000032  72 69 63 20  45 63 68 69  64 6e 61 20  28 74 65 73  ric Echidna (tes
       00000048  74 20 6b 65  79 29 20 3c  65 72 69 63  40 62 6f 75  t key) <eric@bou
       00000064  6e 63 79 63  61 73 74 6c  65 2e 6f 72  67 3e 00 0a  ncycastle.org>..
       00000080  09 10 35 58  61 46 fd f3  f3 73 4b 5b  03 fe 2e 53  ..5XaF...sK[...S
       00000096  04 28 ab cb  35 3b e2 1b  63 91 65 3a  86 b9 fb 47  .(..5;..c.e:...G
       00000112  d5 4c 6a 21  50 f5 2e 39  76 aa d5 86  d7 96 3b 9a  .Lj!P..9v.....;.
       00000128  1a c3 6d c0  50 7f c6 25  9a 04 de 0f  1f 20 ae 70  ..m.P..%..... .p
       00000144  f9 77 c4 8b  bf ec 3c 2f  59 58 b8 47  81 6a 59 25  .w....</YX.G.jY%
       00000160  82 b0 ba e2  a9 43 94 aa  fc 92 2b b3  76 77 f5 ba  .....C....+.vw..
       00000176  5b 59 9a de  22 1c 79 06  88 d2 ba 97  51 e3 11 2e  [Y..".y.....Q...
       00000192  5b c0 c6 8c  34 4d a7 28  77 bf 11 27  e7 6c 8e 1c  [...4M.(w..'.l..
       00000208  b4 a6 66 18  8e 69 3c 18  b7 97 d5 34  9a bb        ..f..i<....4..
       
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void close()
      Writes out the final line (if incomplete) and invalidates this object.
      static java.lang.String dumpHex​(byte[] data)
      Calls dumpHex(byte[], int, int) with perLine set to 16 and perGroup set to 4.
      static java.lang.String dumpHex​(byte[] data, int perLine, int perGroup)
      Convenience static method for generating a hex dump as a String.
      void flush()
      Writes partial line buffer (if any) to upstream Writer.
      void write​(int b)
      Writes a single byte to the current line buffer, flushing if end of line.
      • Methods inherited from class java.io.OutputStream

        nullOutputStream, write, write
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • HexDumper

        public HexDumper​(@WillNotClose
                         java.io.Writer writer)
        Calls HexDumper(Writer, int, int) with perLine set to 16 and perGroup set to 4.
      • HexDumper

        public HexDumper​(@WillNotClose
                         java.io.Writer out,
                         @Nonnegative
                         int perLine,
                         @Nonnegative
                         int perGroup)
        Construct a new streaming HexDumper object.

        The output is line-buffered so a single write call is made to out for each line. This is done to avoid system call overhead out is a resource, and reduces the chance of lines being broken by other threads writing to out (or its underlying resource) at the same time.

        This object will not close out. You must close both this object and out, and this object must be closed first.

        Parameters:
        out - is the stream to which the hex dump text is written. It is not closed.
        perLine - determines how many hex characters to show on each line.
        perGroup - how many columns of hex digits should be grouped together. If this value is > 0, an extra space will be inserted after each Nth column for readability. Grouping can be disabled by setting this to 0.
        See Also:
        dumpHex(byte[])
    • Method Detail

      • dumpHex

        public static java.lang.String dumpHex​(byte[] data)
        Calls dumpHex(byte[], int, int) with perLine set to 16 and perGroup set to 4.
      • dumpHex

        public static java.lang.String dumpHex​(byte[] data,
                                               @Nonnegative
                                               int perLine,
                                               @Nonnegative
                                               int perGroup)
        Convenience static method for generating a hex dump as a String.

        This method adds an additional line to the beginning with the total number of bytes.

        See Also:
        HexDumper(Writer, int, int)
      • write

        public void write​(int b)
                   throws java.io.IOException
        Writes a single byte to the current line buffer, flushing if end of line.
        Specified by:
        write in class java.io.OutputStream
        Throws:
        java.io.IOException - upon failure to write to upstream writer.
        java.lang.IllegalStateException - if this object has been closed.
      • flush

        public void flush()
                   throws java.io.IOException
        Writes partial line buffer (if any) to upstream Writer.
        Specified by:
        flush in interface java.io.Flushable
        Overrides:
        flush in class java.io.OutputStream
        Throws:
        java.io.IOException - upon failure to write to upstream writer.
        java.lang.IllegalStateException - if this object has been closed.
      • close

        public void close()
                   throws java.io.IOException
        Writes out the final line (if incomplete) and invalidates this object.

        This object must be closed before you close the upstream writer. Please note that this method does not close upstream writer for you.

        If you attempt to write to this object after calling this method, IllegalStateException will be thrown. However, it's safe to call close multiple times, as subsequent calls will be treated as a no-op.

        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Overrides:
        close in class java.io.OutputStream
        Throws:
        java.io.IOException - upon failure to write to upstream writer.