DumpUtility (terracotta-utilities-tools 0.0.19 API)

java.lang.Object
- org.terracotta.utilities.io.buffer.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:
Under Java 17+, the --add-opens java.base/java.nio=ALL-UNNAMED option must be added to the JVM options in order to dump LongBuffer and IntBuffer instances.
Examples
To dump to an Slf4J log, DumpUtility can be combined with LoggingOutputStream as in the following:
```
     try (LoggingOutputStream loggingStream = new LoggingOutputStream(LoggerFactory.getLogger("dump"), Level.INFO);
          PrintStream printStream = new PrintStream(loggingStream, false, StandardCharsets.UTF_8.name())) {
       DumpUtility.dumpBuffer(buffer, printStream);
     }
```

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class DumpUtility.FieldInaccessibleException
Thrown if reflective access to a required internal field fails.

Nested Classes
Modifier and Type	Class and Description
`static class`	`DumpUtility.FieldInaccessibleException` Thrown if reflective access to a required internal field fails.

Constructor Summary

Constructors
Constructor and 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 and Description
`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.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- 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; no space is added between linePrefix and the dump line
- Method Detail
  - 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

Class DumpUtility

Use of Reflection

Examples

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

DumpUtility

DumpUtility

Method Detail

dumpBuffer

dumpBuffer

dumpBuffer

dumpBuffer

dumpBuffer

dumpBuffer

dump