Package org.terracotta.utilities.io.buffer

Class DumpUtility

java.lang.Object
org.terracotta.utilities.io.buffer.DumpUtility
public final class DumpUtility extends Object
Provides methods to dump Buffer instances.

Each instance of this class tracks the buffers it dumps and does not dump the same buffer more than once. Because of this, an instance of this class should not be retained beyond actual need to avoid interfering with garbage collection of the dumped buffers.

Use of Reflection

This class uses reflection to access fields internal to Buffer implementations. Operation of the following methods requires this access:

  • Field Details

    • printStream

      private final PrintStream printStream
      The PrintStream to which the dump is written.

    • linePrefix

      private final CharSequence linePrefix
      The prefix to prepend to each emitted line.

    • dumpedSet

      private final Set<Object> dumpedSet
      Tracks objects already dumped.

    • ASCII_ENCODER

      private static final CharsetEncoder ASCII_ENCODER
      CharsetEncoder used to test bytes for printability.

  • Constructor Details

    • DumpUtility

      public DumpUtility(PrintStream printStream)
      Constructs a new DumpUtility using the PrintStream provided. This constructor is equivalent to new DumpUtility(printStream, "").
      Parameters:
      printStream - the PrintStream to which the dump is written

    • DumpUtility

      public DumpUtility(PrintStream printStream, CharSequence linePrefix)
      Constructs a new DumpUtility using the PrintStream and line prefix provided.
      Parameters:
      printStream - the PrintStream to which the dump is written
      linePrefix - the value to prepend to each dump line written

  • Method Details

    • wasDumped

      private boolean wasDumped(Object o)
      Tracks objects dumped by this DumpUtility instance to permit avoidance of duplicate dumps of data structures. This method write a line to printStream: if the object not been dumped, the line is suitable to identify the object being dumped; if the object has been dumped, the line is a reference to the identity previously displayed.
      Parameters:
      o - the object to track
      Returns:
      true if o was previously dumped

    • dumpBuffer

      public static void dumpBuffer(IntBuffer buffer, PrintStream printStream)
      A convenience method that allocates a DumpUtility instance, dumps a buffer, and discards the DumpUtility instance.
      Parameters:
      buffer - the IntBuffer to dump
      printStream - the PrintStream to which the dump is written
      Throws:
      UnsupportedOperationException - if the buffer is not a supported type or reflective access to a required field fails

    • dumpBuffer

      public static void dumpBuffer(LongBuffer buffer, PrintStream printStream)
      A convenience method that allocates a DumpUtility instance, dumps a buffer, and discards the DumpUtility instance.
      Parameters:
      buffer - the LongBuffer to dump
      printStream - the PrintStream to which the dump is written
      Throws:
      UnsupportedOperationException - if the buffer is not a supported type or reflective access to a required field fails

    • dumpBuffer

      public static void dumpBuffer(ByteBuffer buffer, PrintStream printStream)
      A convenience method that allocates a DumpUtility instance, dumps a buffer, and discards the DumpUtility instance.
      Parameters:
      buffer - the ByteBuffer to dump
      printStream - the PrintStream to which the dump is written

    • dumpBuffer

      public void dumpBuffer(IntBuffer buffer)
      Attempts to dump a IntBuffer. The present implementation of this method depends the use of ByteBuffer.asIntBuffer in creation of buffer and on the internal implementation of ByteBuffer.
      Parameters:
      buffer - the IntBuffer instance to dump
      Throws:
      UnsupportedOperationException - if the buffer is not a supported type or reflective access to a required field fails

    • dumpBuffer

      public void dumpBuffer(LongBuffer buffer)
      Attempts to dump a LongBuffer. The present implementation of this method depends the use of ByteBuffer.asLongBuffer in creation of buffer and on the internal implementation of ByteBuffer.
      Parameters:
      buffer - the LongBuffer instance to dump
      Throws:
      UnsupportedOperationException - if the buffer is not a supported type or reflective access to a required field fails

    • dumpBuffer

      public void dumpBuffer(ByteBuffer buffer)
      Writes the contents of ByteBuffer to the PrintStream provided. The dump consists of a sequence of lines where each line is the dump of a 32-byte segment from the buffer and includes data in hexadecimal and in printable ASCII. A sample dump is shown: 
      
 00000000  00000000 00000000 00000000 00000023  A5000000 00000000 00000000 00000000  *...............# ................*
 00000020  00000000 00000020 00000000 00000023  A5000000 00000000 00000000 00000000  *....... .......# ................*
 00000040-00000C7F  duplicates above                                                 *                                 *
 00000C80  00000000 00000020 00000000 00000351  00000000 00000000 00000000 00000000  *....... .......Q ................*
 00000CA0  00000000 00000000 00000000 00000000  00000000 00000000 00000000 00000000  *................ ................*
 00000CC0-00FFFFDF  duplicates above                                                 *                                 *
 00FFFFE0  00000000 00000000 00000000 00000000  00000000 00000000 00000000 00000000  *................ ................*

      For a direct ByteBuffer, this method attempts to access the value of an internal field. Failure to access this field does not prevent this method from dumping the ByteBuffer.

      Parameters:
      buffer - the ByteBuffer to dump; the buffer is printed from position zero (0) through the buffer limit using a view over the buffer

    • dump

      public void dump(byte[] bytes)
      Writes the contents of byte[] to the PrintStream provided. The dump consists of a sequence of lines where each line is the dump of a 32-byte segment from the array and includes data in hexadecimal and in printable ASCII. A sample dump is shown: 
      
 00000000  00000000 00000000 00000000 00000023  A5000000 00000000 00000000 00000000  *...............# ................*
 00000020  00000000 00000020 00000000 00000023  A5000000 00000000 00000000 00000000  *....... .......# ................*
 00000040-00000C7F  duplicates above                                                 *                                 *
 00000C80  00000000 00000020 00000000 00000351  00000000 00000000 00000000 00000000  *....... .......Q ................*
 00000CA0  00000000 00000000 00000000 00000000  00000000 00000000 00000000 00000000  *................ ................*
 00000CC0-00FFFFDF  duplicates above                                                 *                                 *
 00FFFFE0  00000000 00000000 00000000 00000000  00000000 00000000 00000000 00000000  *................ ................*
      Parameters:
      bytes - the byte array to dump

    • dumpBufferInternal

      private void dumpBufferInternal(ByteBuffer view)

    • addGroupSpace

      private static void addGroupSpace(int i, StringBuilder dumpBuilder, StringBuilder charBuilder)

    • flushDumpLine

      private void flushDumpLine(PrintStream out, StringBuilder dumpBuilder, StringBuilder charBuilder)
      Emit a dump line and prepare the buffers for the next.
      Parameters:
      out - the PrintStream to which the dump line is written
      dumpBuilder - the StringBuilder into which the hex portion of the dump line, including the displacement, are recorded
      charBuilder - the StringBuilder into which the ASCII portion of the dump line is recorded

    • getFieldValue

      private <V, T> V getFieldValue(Class<V> expectedType, T instance, String fieldName)
      Gets the value of the designated field from the object instance provided. This method expects a non-null value in the field.
      Type Parameters:
      V - the declared type of the returned value
      T - the declared type of the object from which the value is obtained
      Parameters:
      expectedType - the type to which the fetched value is cast
      instance - the instance from which the value is fetched
      fieldName - the name of the field in instance holding the value
      Returns:
      the value of the named field
      Throws:
      DumpUtility.FieldInaccessibleException - if an error occurs while attempting to access the field
      AssertionError - if the field fieldName contains null

    • getFieldValue

      private <V, T> V getFieldValue(Class<V> expectedType, T instance, String fieldName, boolean quiet)
      Gets the value of the designated field from the object instance provided. This method expects a non-null value in the field.
      Type Parameters:
      V - the declared type of the returned value
      T - the declared type of the object from which the value is obtained
      Parameters:
      expectedType - the type to which the fetched value is cast
      instance - the instance from which the value is fetched
      fieldName - the name of the field in instance holding the value
      quiet - if true, suppress the informational message related to the value fetch and permit the return of a null value
      Returns:
      the value of the named field; may be null if, and only if, quiet is true
      Throws:
      DumpUtility.FieldInaccessibleException - if an error occurs while attempting to access the field
      AssertionError - if the field fieldName contains null

    • getObjectId

      private static String getObjectId(Object o)
      Gets an object identifier similar to the one produced by Object.toString.
      Parameters:
      o - the object for which the identifier is generated
      Returns:
      the object identifier