Class HeapDump

java.lang.Object

org.graalvm.tools.insight.heap.HeapDump

public final class HeapDump
extends Object

Support for generating .hprof files in Java Profiler Heap Dump Format.

Builder builder = HeapDump.newHeapBuilder(new FileOutputStream(hprof));
builder.dumpHeap((heap) -> {
    final ClassInstance classActor = heap.newClass("cartoons.Actor").
        field("name", String.class).
        field("friend", Object.class).
        field("age", int.class).
        dumpClass();
    final ObjectInstance jerry = heap.newInstance(classActor).
        put("name", heap.dumpString("Jerry")).
        putInt("age", 47).
        // field 'friend' remains null
        dumpInstance();
    final ObjectInstance tom = heap.newInstance(classActor).
        put("name", heap.dumpString("Tom")).
        put("friend", jerry).
        putInt("age", 32).
        dumpInstance();
    final ClassInstance classMain = heap.newClass("cartoons.Main").
        field("tom", classActor).
        field("jerry", classActor).
        field("thread", java.lang.Thread.class).
        dumpClass();

    HeapDump.InstanceBuilder mainBuilder = heap.newInstance(classMain);
    final ObjectInstance main = mainBuilder.id();
    mainBuilder.put("tom", tom).put("jerry", jerry);

    ObjectInstance cathingThread = heap.newThread("Catching Jerry").
        addStackFrame(classActor, "tom", "Actor.java", -1, jerry, tom, main).
        addStackFrame(classMain, "main", "Main.java", -1, main).
        dumpThread();

    mainBuilder.put("thread", cathingThread).dumpInstance();
});

Since:

21.1

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
final class	HeapDump.ArrayBuilder	Fills data for new array to put into the HeapDump.
final class	HeapDump.Builder	Builder to construct content of the heap dump file.
final class	HeapDump.ClassBuilder	Builds structure of a new class for the HeapDump.
final class	HeapDump.ClassInstance	Represents a class in the HeapDump.
final class	HeapDump.InstanceBuilder	Fills data for new object instance to put into the HeapDump.
final class	HeapDump.ObjectInstance	Represents an object instance in the HeapDump.
final class	HeapDump.ThreadBuilder	Allows one to describe a state of a thread with local variables and record it in the generated HeapDump.

Method Summary

Modifier and Type	Method	Description
HeapDump.ObjectInstance	dumpPrimitive(Object obj)	Dumps a primitive value (int, long, float, byte, char & other) into the HeapDump.
HeapDump.ObjectInstance	dumpString(String text)	Builds new string instance in the HeapDump.
HeapDump.ArrayBuilder	newArray(int len)	Starts building an object array.
HeapDump.ClassBuilder	newClass(String name)	Starts building new class for the HeapDump.
static HeapDump.Builder	newHeapBuilder(OutputStream os)	Starts generating new .hprof file.
HeapDump.InstanceBuilder	newInstance(HeapDump.ClassInstance clazz)	Starts building an instance of given class.
HeapDump.ThreadBuilder	newThread(String name)	Starts building new thread/event with a stacktrace and local variables.

Methods inherited from class Object

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

Method Details

newHeapBuilder

public static HeapDump.Builder newHeapBuilder(OutputStream os)

Starts generating new .hprof file. Follow with HeapDump.Builder.dumpHeap(Consumer) call.

Builder builder = HeapDump.newHeapBuilder(new FileOutputStream(hprof));
builder.dumpHeap((heap) -> {
    final ClassInstance classActor = heap.newClass("cartoons.Actor").
        field("name", String.class).
        field("friend", Object.class).
        field("age", int.class).
        dumpClass();
    final ObjectInstance jerry = heap.newInstance(classActor).
        put("name", heap.dumpString("Jerry")).
        putInt("age", 47).
        // field 'friend' remains null
        dumpInstance();
    final ObjectInstance tom = heap.newInstance(classActor).
        put("name", heap.dumpString("Tom")).
        put("friend", jerry).
        putInt("age", 32).
        dumpInstance();
    final ClassInstance classMain = heap.newClass("cartoons.Main").
        field("tom", classActor).
        field("jerry", classActor).
        field("thread", java.lang.Thread.class).
        dumpClass();

    HeapDump.InstanceBuilder mainBuilder = heap.newInstance(classMain);
    final ObjectInstance main = mainBuilder.id();
    mainBuilder.put("tom", tom).put("jerry", jerry);

    ObjectInstance cathingThread = heap.newThread("Catching Jerry").
        addStackFrame(classActor, "tom", "Actor.java", -1, jerry, tom, main).
        addStackFrame(classMain, "main", "Main.java", -1, main).
        dumpThread();

    mainBuilder.put("thread", cathingThread).dumpInstance();
});

Parameters:

os - output stream to write data to

Returns:

new builder

newClass

public HeapDump.ClassBuilder newClass(String name)
                               throws UncheckedIOException

Starts building new class for the HeapDump.

Parameters:

name - the name of the class

Returns:

builder to specify field names and types

Throws:

UncheckedIOException - when an I/O error occurs

Since:

21.1

newThread

public HeapDump.ThreadBuilder newThread(String name)

Starts building new thread/event with a stacktrace and local variables.

Parameters:

name - name of the thread

Returns:

new thread builder

Since:

21.1

See Also:

• HeapDump.ThreadBuilder

newInstance

public HeapDump.InstanceBuilder newInstance(HeapDump.ClassInstance clazz)

Starts building an instance of given class.

Parameters:

clazz - class with defined fields and their types

Returns:

new instance builder

Since:

21.1

newArray

public HeapDump.ArrayBuilder newArray(int len)

Starts building an object array.

Parameters:

len - the size of the array

Returns:

new array builder

Since:

21.3.2

dumpString

public HeapDump.ObjectInstance dumpString(String text)
                                   throws UncheckedIOException

Builds new string instance in the HeapDump. Encodes the value as an instance of java.lang.String with value field holding the char[] of the provided text.

Parameters:

text - the text of the string

Returns:

instance representing the string in the heap.

Throws:

UncheckedIOException - when an I/O error occurs

Since:

21.1

dumpPrimitive

public HeapDump.ObjectInstance dumpPrimitive(Object obj)
                                      throws UncheckedIOException

Dumps a primitive value (int, long, float, byte, char & other) into the HeapDump. Encodes the value as appropriate boxed object ( Integer, Long, Float, Byte, Character & co.).

Parameters:

obj - primitive value

Returns:

object instance representing the value in the heap

Throws:

UncheckedIOException - when an I/O error occurs

Since:

21.1