Heap dump script API

Content of the MCP resource jprofiler://api/heap-scripts of the JProfiler MCP server, see the tool and resource reference for the full list of tools and resources.

Reference for the Java scripts of the query tool heap datasets: filterScript on heap.instances and heap.sizes keeps the objects for which the script returns true, groupScript of the custom_grouping inspection on heap.inspectionResult assigns each object to the group whose name it returns.

Scripts are compiled when the query runs and executed in the jpmcp server process over the dumped heap data, with the permissions of the server process. They never run in the profiled JVM.

Script form

A script is either a single expression without return or a statement sequence ending in return. Bodies containing semicolons or ending in } are always treated as statements. Prefer the return form for anything beyond a simple predicate.

Signatures

Filter scripts return boolean (true keeps the object in the set), group scripts return String (the group key, null skips the object). Both take the same parameters:

(scriptContext, heapObject)

• scriptContext: a ScriptContext for state across the evaluations of one query, see the recipes below.
• the heap object: named after its type. When the query selects a single class (class parameter and no filterPath), the parameter is typed as the most specific sub-interface, otherwise as HeapObject: instance (Instance), stringInstance (StringInstance), primitiveArray (PrimitiveArray), classObject (ClassObject) or heapObject (HeapObject). filterPath navigates a field path first and the script is evaluated on the objects the path points to, typed as HeapObject.

The package com.jprofiler.api.agent.heap is imported automatically. The types below are the complete API.

Errors

Compile errors report all problems of the script at once, with line numbers relative to the script text. At runtime the first exception aborts the query: the stack trace is cut at the script's evaluate frame with script-relative line numbers. Field access on the wrong object shape (null fields, missing primitive data) is the usual cause - write null-safe scripts and check classDescriptor() when the object shape varies.

Recipes

Null-safe field filter (filter script):

var desc = instance.fieldValue("desc");
return desc instanceof StringInstance s && s.value() != null && s.value().contains("Gradient");

Group by a computed bucket (group script), here the size of a byte[] field:

var payload = (HeapObject) instance.fieldValue("payload");
long size = payload == null ? 0 : payload.size();
return size < 20480 ? "small" : size < 61440 ? "medium" : "large";

Extract each distinct value of a string field as its own group with one representative object, using scriptContext to skip duplicates (the same instance is reused for all evaluations of one query):

var value = instance.fieldValue("name") instanceof StringInstance s ? s.value() : null;
if (value == null || scriptContext.getObject("seen:" + value) != null) {
    return null;
}
scriptContext.putObject("seen:" + value, value);
return value;

Limitations

• PHD dumps expose no field values: Instance.fieldValue returns null, references are still available.
• In dumps without primitive data, StringInstance.value() and PrimitiveArray.readData() return null.
• PrimitiveArray.readData() covers at most the first 10000 elements.

Types

Flat alphabetical index of every type in the API. Use this when you know the qualified name and want to skip package navigation.

Package com.jprofiler.agent.scripts

HeapObjectFilterScript

Import: import com.jprofiler.agent.scripts.HeapObjectFilterScript;

interface HeapObjectFilterScript

Methods

##### evaluate(ScriptContext, HeapObject)

boolean evaluate(ScriptContext scriptContext, HeapObject object) throws Exception

HeapObjectGroupScript

Import: import com.jprofiler.agent.scripts.HeapObjectGroupScript;

interface HeapObjectGroupScript

Methods

##### evaluate(ScriptContext, HeapObject)

String evaluate(ScriptContext scriptContext, HeapObject object) throws Exception

Package com.jprofiler.api.agent

ScriptContext

Import: import com.jprofiler.api.agent.ScriptContext;

interface ScriptContext

Context object that is passed to all scripts and provides ways to store key-value pairs for all subsequent invocations of any custom script.

For example, if you need to calculate the change of an observed numeric value between script invocations, you can use the context as follows:

    long previousValue = scriptContext.getLong("myValue");
    long currentValue = ...;
    long delta = currentValue - previousValue;
    // Use delta
    scriptContext.putLong("myValue", currentValue); // for the next invocation of the script

Methods

##### getObject(Object)

Object getObject(Object key)

Returns the value for the specified key in the script context.

Parameters:

• key — the key

Returns: the value, or null if there was no mapping for the key.

##### putObject(Object, Object)

Object putObject(Object key, Object value)

Store a key-value pair in the script context. An existing mapping is overwritten.

Parameters:

• key — the key
• value — the value

Returns: the value that was previously associated with the specified key, or null if there was no mapping for the key.

##### getLong(Object)

long getLong(Object key)

Returns the long value for the specified key in the script context.

Parameters:

• key — the key

Returns: the long value, or 0 if there was no mapping

##### putLong(Object, long)

long putLong(Object key, long value)

Store a key-value pair of value type long in the script context. An existing mapping is overwritten.

Parameters:

• key — the key
• value — the long value

Returns: the value that was previously associated with the specified key, or 0 if there was no mapping for the key.

Package com.jprofiler.api.agent.heap

Contains the classes for analyzing dumped heap data.

The HeapObject interface is the root of the heap object hierarchy.

ClassDescriptor

Import: import com.jprofiler.api.agent.heap.ClassDescriptor;

interface ClassDescriptor

A descriptor for a class, interface, array, or primitive type.

Methods

##### id()

long id()

Retrieves a unique identifier of the class.

Returns: a long value representing the unique identifier

##### displayName()

String displayName()

Retrieves the display name as shown in JProfiler of the type represented by this descriptor.

Returns: a non-null string representing the display name of the type.

##### descriptor()

String descriptor()

Returns the field descriptor for a class, interface, array, or primitive type according to the Java Virtual Machine Specification. A field type descriptor string for a non-array type is either a one-letter code corresponding to a primitive type ("J", "I", "C", "S", "B", "D", "F", "Z"), or the letter "L", followed by the fully qualified binary name of a class, followed by ";". A field type descriptor for an array type is the character "[" followed by the field descriptor for the component type. Examples of valid type descriptor strings include "Ljava/lang/String;", "I", "[I", "[Ljava/lang/String;", etc.

Returns: a non-null string representing the field descriptor of the type.

##### isObjectArray()

boolean isObjectArray()

Determines if the type represented by this descriptor is an array of objects.

Returns: true if the type is an array of objects, false otherwise.

##### isPrimitiveArray()

boolean isPrimitiveArray()

Determines if the type represented by this descriptor is an array of a primitive type.

Returns: true if the type is an array of a primitive type, false otherwise.

##### isString()

boolean isString()

Determines if this descriptor represents java.lang.String.

Returns: true if the type is java.lang.String, false otherwise.

##### isClassObject()

boolean isClassObject()

Determines if this descriptor represents a java.lang.Class object in the heap dump.

Returns: true if the descriptor represents a class object, false otherwise.

##### isInstance()

boolean isInstance()

Determines if this descriptor represents an instance of a class in the heap dump.

Returns: true if the descriptor represents a class instance, false otherwise.

##### superClass()

@Nullable ClassDescriptor superClass()

Retrieves the descriptor representing the superclass of the class described by this descriptor.

Returns: the ClassDescriptor of the superclass, or null if no superclass exists.

##### declaredInstanceFields()

List<String> declaredInstanceFields()

Retrieves a list of declared instance fields for the class described by this descriptor. Declared instance fields are the fields directly defined in this class, excluding those inherited from superclasses or static fields.

If field information is unavailable, the list is empty.

Returns: a non-null list of strings where each string represents the name of an instance field declared in this class.

##### allInstanceFields()

List<String> allInstanceFields()

Retrieves a list of all instance fields present in the class described by this descriptor. This list includes both declared fields and inherited instance fields from superclasses. Static fields are excluded.

If field information is unavailable, the list is empty.

Returns: a non-null list of strings where each string represents the name of an instance field available in this class and its superclasses.

##### staticFields()

List<String> staticFields()

Retrieves a list of static field names for the class described by this descriptor.

If field information is unavailable, the list is empty.

Returns: a non-null list of strings where each string represents the name of a static field declared in this class.

ClassObject

Import: import com.jprofiler.api.agent.heap.ClassObject;

interface ClassObject extends HeapObject

Represents a java.lang.Class object in a heap dump. Provides access to static field values of the class it represents.

Inherited from

• HeapObject — 5 methods

Methods

##### representedClass()

ClassDescriptor representedClass()

Retrieves the ClassDescriptor that this ClassObject represents. The descriptor provides detailed metadata about the class, including its name, fields, and hierarchy.

Returns: a ClassDescriptor instance representing the class described by this object, never null.

##### staticFieldValue(int)

@Nullable Object staticFieldValue(int fieldIndex)

Retrieves the value of a static field for this class object based on its index. The static field can hold either a primitive value, a HeapObject, or one of its subinterfaces.

Parameters:

• fieldIndex — the zero-based index of the static field in the class descriptor. The index must be within the bounds of the static fields defined for the class.

Returns: the value of the static field at the specified index, or null if the static fields are unavailable, or if the field value itself is null.

##### staticFieldValue(String)

@Nullable Object staticFieldValue(String fieldName)

Retrieves the value of a static field for this class object based on its field name. The static field can hold either a primitive value, a HeapObject, or one of its subinterfaces.

Parameters:

• fieldName — the name of the static field to be retrieved. Must not be null or empty.

Returns: the value of the static field with the specified name, or null if no field exists with the specified name, if the static fields are unavailable, or if the field value itself is null.

HeapObject

Import: import com.jprofiler.api.agent.heap.HeapObject;

interface HeapObject

Represents an object from a heap dump. Provides information regarding the object's identity, size, associated class description, and its relationship with other objects in the heap.

You can cast this object to its subinterfaces Instance, StringInstance, PrimitiveArray and ClassObject to get further specific data. You can determine the object kind with the ClassDescriptor provided by the HeapObject.classDescriptor method. For PHD snapshots, only HeapObject and ClassObject are available.

Methods

##### id()

long id()

Retrieves a unique identifier of the object.

Returns: a long value representing the unique identifier

##### size()

long size()

Retrieves the shallow size of the object.

Returns: the size as a long value.

##### classDescriptor()

ClassDescriptor classDescriptor()

Retrieves the class descriptor associated with this heap object. The class descriptor contains metadata about the object's type, including its name, hierarchy, and fields.

Returns: the ClassDescriptor instance representing the class of this heap object, never null.

##### referencedObjects()

Collection<HeapObject> referencedObjects()

Retrieves all objects referenced directly by this heap object. The references include field values, array values or other class specific referenced objects for a ClassObject.

Returns: a collection of HeapObject instances that are directly referenced by this object. The collection is never null but may be empty if no objects are referenced.

##### referencingObjects()

Collection<HeapObject> referencingObjects()

Retrieves all objects that directly reference this heap object.

Returns: a collection of HeapObject instances that reference this object. The collection is never null but may be empty if no objects reference this heap object.

Instance

Import: import com.jprofiler.api.agent.heap.Instance;

interface Instance extends HeapObject

Represents an object instance from a heap dump. Instances provide access to the values of their fields.

Inherited from

• HeapObject — 5 methods

Methods

##### fieldValue(int)

@Nullable Object fieldValue(int fieldIndex)

Retrieves the value of an instance field for this object based on its index in ClassDescriptor.allInstanceFields. The field can hold either a primitive value, a HeapObject, or one of its subinterfaces.

Parameters:

• fieldIndex — the zero-based index of the instance field. The index must be within the bounds of the fields defined for the object.

Returns: the value of the instance field at the specified index, or null if the field is unavailable, or if the field value itself is null.

##### fieldValue(String)

@Nullable Object fieldValue(String fieldName)

Retrieves the value of an instance field for this object based on its name. The field can hold either a primitive value, a HeapObject, or one of its subinterfaces.

Parameters:

• fieldName — the name of the instance field to be retrieved. Must not be null.

Returns: the value of the instance field with the specified name, or null if no field exists with the specified name, if the field is unavailable, or if the field value itself is null.

PrimitiveArray

Import: import com.jprofiler.api.agent.heap.PrimitiveArray;

interface PrimitiveArray extends HeapObject

Represents a primitive array from a heap dump. Provides access to the data stored in the array.

Inherited from

• HeapObject — 5 methods

Methods

##### readData()

@Nullable ByteBuffer readData()

Reads the data stored in this primitive array as a ByteBuffer. You can use ByteBuffer#asIntBuffer() etc. to access the values of the array. For JProfiler heap dumps, the data will be limited to the first 10,000 elements.

Returns: A ByteBuffer representation of the data in this primitive array, or null if the data is not available.

StringInstance

Import: import com.jprofiler.api.agent.heap.StringInstance;

interface StringInstance extends Instance

Represents a java.lang.String instance in a heap dump. Provides a method to retrieve the string value of this instance.

Inherited from

• Instance — 2 methods
• HeapObject — 5 methods

Methods

##### value()

@Nullable String value()

Retrieves the value of this StringInstance. The value corresponds to the represented java.lang.String content, or null if the string value is unavailable because the heap dump doesn't contain primitive data.

Returns: the string value of this instance, or null if unavailable.