com.ccg.util
Class HexDump

java.lang.Object
  com.ccg.util.HexDump

public class HexDump
extends Object

Do a "hexdump" of binary data. Seems like there always comes a time when one needs to dump the contents of some binary data. This class allows one to do that, it dumps output in the following form (up to 16 bytes per line by default):

 oooooooo:xx xx xx xx xx xx xx xx xx xx xx xx xx xx xx xx  ................
 

Where:

oooooooo

Is the current offset of the bytes being dumped.

xx

The hex representation of each byte being displayed (like: 0x1e)

................

The ASCII representation of each byte (or '.' if the ASCII representation would result in a unprintable character

To use this class, you keep invoking the formatBytes(java.io.PrintWriter, byte[], int, int) method until you no longer have more bytes to dump. Once you are done dumping all of your bytes (or whenever you want to force the output of what's been formatted so far), you invoke the flush(java.io.PrintWriter) method.

By default, this class sets the initial offset to 0 and the initial number of bytes per line to 16.

Since:

1.0

Version:

$Revision: 1.1.1.1 $

Author:

$Author: pkb $

See Also:

PrintWriterString, com.ccg.app.convert.HexDump

Constructor Summary

HexDump()
Default object constructor.

Method Summary

static String	bytesToHexString(byte[] bytes, int ofs, int len)
void	clearLine() Cancel the output of the remaining bytes in the current line.
void	flush(PrintWriter pw) Flush out any "lingering" data.
void	formatBytes(PrintWriter pw, byte[] bytes, int ofs, int len) Add the values of a set of bytes to the hex dump output.
long	getOffset() Get the current offset position.
static void	print(PrintWriter pw, byte b) Print a single byte in the default hex form.
void	setBytesPerLine(int len) Set the number of bytes to display on each line of output.
void	setOffset(long ofs) Set the offset position.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HexDump

public HexDump()

Default object constructor. This method prepares the object for formatting hex bytes. It defaults the bytes per line to 16 and initializes the starting offset to 0.

Since:

1.0

See Also:

formatBytes(java.io.PrintWriter, byte[], int, int)

Method Detail

setBytesPerLine

public void setBytesPerLine(int len)

Set the number of bytes to display on each line of output.

Parameters:

arg1 - Number of bytes to display per line. If set to a value less than 1, it will be forced to the default value of 16.

Since:

1.0

See Also:

setOffset(long), clearLine()

print

public static void print(PrintWriter pw,
                         byte b)

Print a single byte in the default hex form. This simple static member function allows one to display the hex value for any byte using the default character set.

Parameters:

pw - Where to display hex value

b - Byte to display

Since:

1.0

formatBytes

public void formatBytes(PrintWriter pw,
                        byte[] bytes,
                        int ofs,
                        int len)

Add the values of a set of bytes to the hex dump output. This method allows one to output a set of bytes such that they will be formatted properly. Each byte added is formatted in the current output line contained by the object. Once the output line reaches the maximum length (16 by default), the current output line will then be flushed and remaining bytes will start on the next line.

This method allows one to specify what portion of the byte array is to be dumped, to dump the entire array, set the 'ofs' to 0 and the 'len' to -1 like:

 hd.formatBytes(pw,bytes,0,-1);
 

Parameters:

pw - Where to dump output as each line is completed.

bytes - Array containing bytes to dump. The bytes actually dumped will depend upon the setting of the 'ofs' and 'len' parameters.

ofs - Offset in byte array to start dumping from (must be 0 or higher - if its greater than or equal to the length of the array, then nothing will be done).

len - How many bytes to display. Set to a negitive value (like -1) and all of the bytes to the end of the array will be displayed.

Since:

1.0

See Also:

flush(java.io.PrintWriter)

bytesToHexString

public static String bytesToHexString(byte[] bytes,
                                      int ofs,
                                      int len)

flush

public void flush(PrintWriter pw)

Flush out any "lingering" data. Each time the formatBytes(java.io.PrintWriter, byte[], int, int) method is invoked, one or more bytes are added to the next line to be dumped by this object. Since it is possible (even likely) that a call to formatBytes(java.io.PrintWriter, byte[], int, int) won't come out to exactly one lines worth of output, it is likely that a portion of a line will "linger" inside this object. Typically, this is fine and one doesn't want to worry about this "lingering" affect. There are two exceptions, however, when one will want to use this method to force the "lingering" output out:

1. Your done dumping your hex data and you want to force the end of the data out.
2. You are done formatting a block of data and want to force the last partial bytes to be displayed.

Parameters:

pw - Where to dump any "lingering" output.

Since:

1.0

See Also:

formatBytes(java.io.PrintWriter, byte[], int, int)

getOffset

public long getOffset()

Get the current offset position. Returns the number of bytes which have been formatted by formatBytes(java.io.PrintWriter, byte[], int, int). This value is affected by the setOffset(long) method.

Returns:

Number of bytes formatted

Since:

1.0

See Also:

setOffset(long)

setOffset

public void setOffset(long ofs)

Set the offset position. This class keeps track of the number of bytes which it formats. It displays this value as the "offset" value at the start of each line of output. This is really handy if you are going through a file and want to know the position in the file corresponding to your output.

Typically, you can let this class keep track of things automatically for you - however, there may be times when you don't do a hex dump of ALL of your bytes (in which case your offset will be out of sync). You can use this method to specify the current offset (position) to bring this object back into sync with your application.

Parameters:

ofs - New offset position in output.

Since:

1.0

See Also:

getOffset()

clearLine

public void clearLine()

Cancel the output of the remaining bytes in the current line. Each time the formatBytes(java.io.PrintWriter, byte[], int, int) method is invoked, it is possible that ASCII output will "linger". Typically one will invoke the flush(java.io.PrintWriter) method to force this data out, however, this method can be used instead if one wants to cancel the "lingering" output (this would be fairly unusual).

This method is always invoked when the setBytesPerLine(int) method is invoked.

Since:

1.0

See Also:

setBytesPerLine(int), flush(java.io.PrintWriter)