Package org.terracotta.utilities.io.buffer

Class DumpUtility

  • public final class DumpUtility
extends java.lang.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 Summary

      Fields 
      Modifier and Type Field Description
      private static java.nio.charset.CharsetEncoder ASCII_ENCODER
      CharsetEncoder used to test bytes for printability.
      private java.util.Set<java.lang.Object> dumpedSet
      Tracks objects already dumped.
      private java.lang.CharSequence linePrefix
      The prefix to prepend to each emitted line.
      private java.io.PrintStream printStream
      The PrintStream to which the dump is written.

    • Constructor Summary

      Constructors 
      Constructor Description
      DumpUtility​(java.io.PrintStream printStream)
      Constructs a new DumpUtility using the PrintStream provided.
      DumpUtility​(java.io.PrintStream printStream, java.lang.CharSequence linePrefix)
      Constructs a new DumpUtility using the PrintStream and line prefix provided.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private static void addGroupSpace​(int i, java.lang.StringBuilder dumpBuilder, java.lang.StringBuilder charBuilder)  
      void dump​(byte[] bytes)
      Writes the contents of byte[] to the PrintStream provided.
      void dumpBuffer​(java.nio.ByteBuffer buffer)
      Writes the contents of ByteBuffer to the PrintStream provided.
      static void dumpBuffer​(java.nio.ByteBuffer buffer, java.io.PrintStream printStream)
      A convenience method that allocates a DumpUtility instance, dumps a buffer, and discards the DumpUtility instance.
      void dumpBuffer​(java.nio.IntBuffer buffer)
      Attempts to dump a IntBuffer.
      static void dumpBuffer​(java.nio.IntBuffer buffer, java.io.PrintStream printStream)
      A convenience method that allocates a DumpUtility instance, dumps a buffer, and discards the DumpUtility instance.
      void dumpBuffer​(java.nio.LongBuffer buffer)
      Attempts to dump a LongBuffer.
      static void dumpBuffer​(java.nio.LongBuffer buffer, java.io.PrintStream printStream)
      A convenience method that allocates a DumpUtility instance, dumps a buffer, and discards the DumpUtility instance.
      private void dumpBufferInternal​(java.nio.ByteBuffer view)  
      private void flushDumpLine​(java.io.PrintStream out, java.lang.StringBuilder dumpBuilder, java.lang.StringBuilder charBuilder)
      Emit a dump line and prepare the buffers for the next.
      private <V,​T>
      V      		 getFieldValue​(java.lang.Class<V> expectedType, T instance, java.lang.String fieldName)
      Gets the value of the designated field from the object instance provided.
      private <V,​T>
      V      		 getFieldValue​(java.lang.Class<V> expectedType, T instance, java.lang.String fieldName, boolean quiet)
      Gets the value of the designated field from the object instance provided.
      private static java.lang.String getObjectId​(java.lang.Object o)
      Gets an object identifier similar to the one produced by Object.toString.
      private boolean wasDumped​(java.lang.Object o)
      Tracks objects dumped by this DumpUtility instance to permit avoidance of duplicate dumps of data structures.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • printStream

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

      • linePrefix

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

      • dumpedSet

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

      • ASCII_ENCODER

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

    • Constructor Detail

      • DumpUtility

        public DumpUtility​(java.io.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​(java.io.PrintStream printStream,
                   java.lang.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 Detail

      • wasDumped

        private boolean wasDumped​(java.lang.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​(java.nio.IntBuffer buffer,
                              java.io.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:
        java.lang.UnsupportedOperationException - if the buffer is not a supported type or reflective access to a required field fails

      • dumpBuffer

        public static void dumpBuffer​(java.nio.LongBuffer buffer,
                              java.io.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:
        java.lang.UnsupportedOperationException - if the buffer is not a supported type or reflective access to a required field fails

      • dumpBuffer

        public static void dumpBuffer​(java.nio.ByteBuffer buffer,
                              java.io.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​(java.nio.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:
        java.lang.UnsupportedOperationException - if the buffer is not a supported type or reflective access to a required field fails

      • dumpBuffer

        public void dumpBuffer​(java.nio.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:
        java.lang.UnsupportedOperationException - if the buffer is not a supported type or reflective access to a required field fails

      • dumpBuffer

        public void dumpBuffer​(java.nio.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​(java.nio.ByteBuffer view)

      • addGroupSpace

        private static void addGroupSpace​(int i,
                                  java.lang.StringBuilder dumpBuilder,
                                  java.lang.StringBuilder charBuilder)

      • flushDumpLine

        private void flushDumpLine​(java.io.PrintStream out,
                           java.lang.StringBuilder dumpBuilder,
                           java.lang.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​(java.lang.Class<V> expectedType,
                                    T instance,
                                    java.lang.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
        java.lang.AssertionError - if the field fieldName contains null

      • getFieldValue

        private <V,​T> V getFieldValue​(java.lang.Class<V> expectedType,
                                    T instance,
                                    java.lang.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
        java.lang.AssertionError - if the field fieldName contains null

      • getObjectId

        private static java.lang.String getObjectId​(java.lang.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