# heap-script-api

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

# Heap dump script API

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):

```java
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:

```java
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):

```java
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.

| Qualified name | Kind | File |
|---|---|---|
| `com.jprofiler.agent.scripts.HeapObjectFilterScript` | interface | [HeapObjectFilterScript](#com-jprofiler-agent-scripts-heapobjectfilterscript) |
| `com.jprofiler.agent.scripts.HeapObjectGroupScript` | interface | [HeapObjectGroupScript](#com-jprofiler-agent-scripts-heapobjectgroupscript) |
| `com.jprofiler.api.agent.ScriptContext` | interface | [ScriptContext](#com-jprofiler-api-agent-scriptcontext) |
| `com.jprofiler.api.agent.heap.ClassDescriptor` | interface | [ClassDescriptor](#com-jprofiler-api-agent-heap-classdescriptor) |
| `com.jprofiler.api.agent.heap.ClassObject` | interface | [ClassObject](#com-jprofiler-api-agent-heap-classobject) |
| `com.jprofiler.api.agent.heap.HeapObject` | interface | [HeapObject](#com-jprofiler-api-agent-heap-heapobject) |
| `com.jprofiler.api.agent.heap.Instance` | interface | [Instance](#com-jprofiler-api-agent-heap-instance) |
| `com.jprofiler.api.agent.heap.PrimitiveArray` | interface | [PrimitiveArray](#com-jprofiler-api-agent-heap-primitivearray) |
| `com.jprofiler.api.agent.heap.StringInstance` | interface | [StringInstance](#com-jprofiler-api-agent-heap-stringinstance) |

## <a id="package-com-jprofiler-agent-scripts"></a>Package `com.jprofiler.agent.scripts`

### <a id="com-jprofiler-agent-scripts-heapobjectfilterscript"></a>HeapObjectFilterScript

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

```java
interface HeapObjectFilterScript
```

#### Methods

| Signature | Returns | Description |
|---|---|---|
| [`evaluate(ScriptContext, HeapObject)`](#com-jprofiler-agent-scripts-heapobjectfilterscript-evaluate-scriptcontext-heapobject) | `boolean` |  |

<a id="com-jprofiler-agent-scripts-heapobjectfilterscript-evaluate-scriptcontext-heapobject"></a>##### evaluate(ScriptContext, HeapObject)

```java
boolean evaluate(ScriptContext scriptContext, HeapObject object) throws Exception
```

### <a id="com-jprofiler-agent-scripts-heapobjectgroupscript"></a>HeapObjectGroupScript

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

```java
interface HeapObjectGroupScript
```

#### Methods

| Signature | Returns | Description |
|---|---|---|
| [`evaluate(ScriptContext, HeapObject)`](#com-jprofiler-agent-scripts-heapobjectgroupscript-evaluate-scriptcontext-heapobject) | `String` |  |

<a id="com-jprofiler-agent-scripts-heapobjectgroupscript-evaluate-scriptcontext-heapobject"></a>##### evaluate(ScriptContext, HeapObject)

```java
String evaluate(ScriptContext scriptContext, HeapObject object) throws Exception
```

## <a id="package-com-jprofiler-api-agent"></a>Package `com.jprofiler.api.agent`

### <a id="com-jprofiler-api-agent-scriptcontext"></a>ScriptContext

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

```java
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

| Signature | Returns | Description |
|---|---|---|
| [`getObject(Object)`](#com-jprofiler-api-agent-scriptcontext-getobject-object) | `Object` | Returns the value for the specified key in the script context. |
| [`putObject(Object, Object)`](#com-jprofiler-api-agent-scriptcontext-putobject-object-object) | `Object` | Store a key-value pair in the script context. |
| [`getLong(Object)`](#com-jprofiler-api-agent-scriptcontext-getlong-object) | `long` | Returns the long value for the specified key in the script context. |
| [`putLong(Object, long)`](#com-jprofiler-api-agent-scriptcontext-putlong-object-long) | `long` | Store a key-value pair of value type long in the script context. |

<a id="com-jprofiler-api-agent-scriptcontext-getobject-object"></a>##### getObject(Object)

```java
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.

<a id="com-jprofiler-api-agent-scriptcontext-putobject-object-object"></a>##### putObject(Object, Object)

```java
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.

<a id="com-jprofiler-api-agent-scriptcontext-getlong-object"></a>##### getLong(Object)

```java
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

<a id="com-jprofiler-api-agent-scriptcontext-putlong-object-long"></a>##### putLong(Object, long)

```java
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.

## <a id="package-com-jprofiler-api-agent-heap"></a>Package `com.jprofiler.api.agent.heap`

Contains the classes for analyzing dumped heap data.

The [`HeapObject`](#com-jprofiler-api-agent-heap-heapobject) interface is the root of the heap object hierarchy.

### <a id="com-jprofiler-api-agent-heap-classdescriptor"></a>ClassDescriptor

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

```java
interface ClassDescriptor
```

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

#### Methods

| Signature | Returns | Description |
|---|---|---|
| [`id()`](#com-jprofiler-api-agent-heap-classdescriptor-id) | `long` | Retrieves a unique identifier of the class. |
| [`displayName()`](#com-jprofiler-api-agent-heap-classdescriptor-displayname) | `String` | Retrieves the display name as shown in JProfiler of the type represented by this descriptor. |
| [`descriptor()`](#com-jprofiler-api-agent-heap-classdescriptor-descriptor) | `String` | Returns the field descriptor for a class, interface, array, or primitive type according to the Java Virtual Machine Specification. |
| [`isObjectArray()`](#com-jprofiler-api-agent-heap-classdescriptor-isobjectarray) | `boolean` | Determines if the type represented by this descriptor is an array of objects. |
| [`isPrimitiveArray()`](#com-jprofiler-api-agent-heap-classdescriptor-isprimitivearray) | `boolean` | Determines if the type represented by this descriptor is an array of a primitive type. |
| [`isString()`](#com-jprofiler-api-agent-heap-classdescriptor-isstring) | `boolean` | Determines if this descriptor represents `java.lang.String`. |
| [`isClassObject()`](#com-jprofiler-api-agent-heap-classdescriptor-isclassobject) | `boolean` | Determines if this descriptor represents a `java.lang.Class` object in the heap dump. |
| [`isInstance()`](#com-jprofiler-api-agent-heap-classdescriptor-isinstance) | `boolean` | Determines if this descriptor represents an instance of a class in the heap dump. |
| [`superClass()`](#com-jprofiler-api-agent-heap-classdescriptor-superclass) | `ClassDescriptor` | Retrieves the descriptor representing the superclass of the class described by this descriptor. |
| [`declaredInstanceFields()`](#com-jprofiler-api-agent-heap-classdescriptor-declaredinstancefields) | `List<String>` | Retrieves a list of declared instance fields for the class described by this descriptor. |
| [`allInstanceFields()`](#com-jprofiler-api-agent-heap-classdescriptor-allinstancefields) | `List<String>` | Retrieves a list of all instance fields present in the class described by this descriptor. |
| [`staticFields()`](#com-jprofiler-api-agent-heap-classdescriptor-staticfields) | `List<String>` | Retrieves a list of static field names for the class described by this descriptor. |

<a id="com-jprofiler-api-agent-heap-classdescriptor-id"></a>##### id()

```java
long id()
```

Retrieves a unique identifier of the class.


**Returns:** a long value representing the unique identifier

<a id="com-jprofiler-api-agent-heap-classdescriptor-displayname"></a>##### displayName()

```java
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.

<a id="com-jprofiler-api-agent-heap-classdescriptor-descriptor"></a>##### descriptor()

```java
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.

<a id="com-jprofiler-api-agent-heap-classdescriptor-isobjectarray"></a>##### isObjectArray()

```java
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.

<a id="com-jprofiler-api-agent-heap-classdescriptor-isprimitivearray"></a>##### isPrimitiveArray()

```java
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.

<a id="com-jprofiler-api-agent-heap-classdescriptor-isstring"></a>##### isString()

```java
boolean isString()
```

Determines if this descriptor represents `java.lang.String`.


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

<a id="com-jprofiler-api-agent-heap-classdescriptor-isclassobject"></a>##### isClassObject()

```java
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.

<a id="com-jprofiler-api-agent-heap-classdescriptor-isinstance"></a>##### isInstance()

```java
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.

<a id="com-jprofiler-api-agent-heap-classdescriptor-superclass"></a>##### superClass()

```java
@Nullable ClassDescriptor superClass()
```

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


**Returns:** the [`ClassDescriptor`](#com-jprofiler-api-agent-heap-classdescriptor) of the superclass, or `null` if no
superclass exists.

<a id="com-jprofiler-api-agent-heap-classdescriptor-declaredinstancefields"></a>##### declaredInstanceFields()

```java
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.

<a id="com-jprofiler-api-agent-heap-classdescriptor-allinstancefields"></a>##### allInstanceFields()

```java
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.

<a id="com-jprofiler-api-agent-heap-classdescriptor-staticfields"></a>##### staticFields()

```java
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.

### <a id="com-jprofiler-api-agent-heap-classobject"></a>ClassObject

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

```java
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](#com-jprofiler-api-agent-heap-heapobject) — 5 methods

#### Methods

| Signature | Returns | Description |
|---|---|---|
| [`representedClass()`](#com-jprofiler-api-agent-heap-classobject-representedclass) | `ClassDescriptor` | Retrieves the [`ClassDescriptor`](#com-jprofiler-api-agent-heap-classdescriptor) that this [`ClassObject`](#com-jprofiler-api-agent-heap-classobject) represents. |
| [`staticFieldValue(int)`](#com-jprofiler-api-agent-heap-classobject-staticfieldvalue-int) | `Object` | Retrieves the value of a static field for this class object based on its index. |
| [`staticFieldValue(String)`](#com-jprofiler-api-agent-heap-classobject-staticfieldvalue-string) | `Object` | Retrieves the value of a static field for this class object based on its field name. |

<a id="com-jprofiler-api-agent-heap-classobject-representedclass"></a>##### representedClass()

```java
ClassDescriptor representedClass()
```

Retrieves the [`ClassDescriptor`](#com-jprofiler-api-agent-heap-classdescriptor) that this [`ClassObject`](#com-jprofiler-api-agent-heap-classobject) represents.
The descriptor provides detailed metadata about the class, including its name,
fields, and hierarchy.


**Returns:** a [`ClassDescriptor`](#com-jprofiler-api-agent-heap-classdescriptor) instance representing the class described by this object, never null.

<a id="com-jprofiler-api-agent-heap-classobject-staticfieldvalue-int"></a>##### staticFieldValue(int)

```java
@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`](#com-jprofiler-api-agent-heap-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`.

<a id="com-jprofiler-api-agent-heap-classobject-staticfieldvalue-string"></a>##### staticFieldValue(String)

```java
@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`](#com-jprofiler-api-agent-heap-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`.

### <a id="com-jprofiler-api-agent-heap-heapobject"></a>HeapObject

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

```java
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`](#com-jprofiler-api-agent-heap-instance), [`StringInstance`](#com-jprofiler-api-agent-heap-stringinstance), [`PrimitiveArray`](#com-jprofiler-api-agent-heap-primitivearray)
and [`ClassObject`](#com-jprofiler-api-agent-heap-classobject) to get further specific data. You can determine the object kind with the [`ClassDescriptor`](#com-jprofiler-api-agent-heap-classdescriptor)
provided by the [`HeapObject.classDescriptor`](#com-jprofiler-api-agent-heap-heapobject-classdescriptor) method. For PHD snapshots, only [`HeapObject`](#com-jprofiler-api-agent-heap-heapobject) and [`ClassObject`](#com-jprofiler-api-agent-heap-classobject) are available.

#### Methods

| Signature | Returns | Description |
|---|---|---|
| [`id()`](#com-jprofiler-api-agent-heap-heapobject-id) | `long` | Retrieves a unique identifier of the object. |
| [`size()`](#com-jprofiler-api-agent-heap-heapobject-size) | `long` | Retrieves the shallow size of the object. |
| [`classDescriptor()`](#com-jprofiler-api-agent-heap-heapobject-classdescriptor) | `ClassDescriptor` | Retrieves the class descriptor associated with this heap object. |
| [`referencedObjects()`](#com-jprofiler-api-agent-heap-heapobject-referencedobjects) | `Collection<HeapObject>` | Retrieves all objects referenced directly by this heap object. |
| [`referencingObjects()`](#com-jprofiler-api-agent-heap-heapobject-referencingobjects) | `Collection<HeapObject>` | Retrieves all objects that directly reference this heap object. |

<a id="com-jprofiler-api-agent-heap-heapobject-id"></a>##### id()

```java
long id()
```

Retrieves a unique identifier of the object.


**Returns:** a long value representing the unique identifier

<a id="com-jprofiler-api-agent-heap-heapobject-size"></a>##### size()

```java
long size()
```

Retrieves the shallow size of the object.


**Returns:** the size as a long value.

<a id="com-jprofiler-api-agent-heap-heapobject-classdescriptor"></a>##### classDescriptor()

```java
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`](#com-jprofiler-api-agent-heap-classdescriptor) instance representing the class of this heap object,
never null.

<a id="com-jprofiler-api-agent-heap-heapobject-referencedobjects"></a>##### referencedObjects()

```java
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`](#com-jprofiler-api-agent-heap-classobject).


**Returns:** a collection of [`HeapObject`](#com-jprofiler-api-agent-heap-heapobject) instances that are directly referenced by this object.
The collection is never null but may be empty if no objects are referenced.

<a id="com-jprofiler-api-agent-heap-heapobject-referencingobjects"></a>##### referencingObjects()

```java
Collection<HeapObject> referencingObjects()
```

Retrieves all objects that directly reference this heap object.


**Returns:** a collection of [`HeapObject`](#com-jprofiler-api-agent-heap-heapobject) instances that reference this object.
The collection is never null but may be empty if no objects reference this heap object.

### <a id="com-jprofiler-api-agent-heap-instance"></a>Instance

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

```java
interface Instance extends HeapObject
```

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

#### Inherited from

- [HeapObject](#com-jprofiler-api-agent-heap-heapobject) — 5 methods

#### Methods

| Signature | Returns | Description |
|---|---|---|
| [`fieldValue(int)`](#com-jprofiler-api-agent-heap-instance-fieldvalue-int) | `Object` | Retrieves the value of an instance field for this object based on its index in [`ClassDescriptor.allInstanceFields`](#com-jprofiler-api-agent-heap-classdescriptor-allinstancefields). |
| [`fieldValue(String)`](#com-jprofiler-api-agent-heap-instance-fieldvalue-string) | `Object` | Retrieves the value of an instance field for this object based on its name. |

<a id="com-jprofiler-api-agent-heap-instance-fieldvalue-int"></a>##### fieldValue(int)

```java
@Nullable Object fieldValue(int fieldIndex)
```

Retrieves the value of an instance field for this object based on its index in [`ClassDescriptor.allInstanceFields`](#com-jprofiler-api-agent-heap-classdescriptor-allinstancefields).
The field can hold either a primitive value, a [`HeapObject`](#com-jprofiler-api-agent-heap-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`.

<a id="com-jprofiler-api-agent-heap-instance-fieldvalue-string"></a>##### fieldValue(String)

```java
@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`](#com-jprofiler-api-agent-heap-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`.

### <a id="com-jprofiler-api-agent-heap-primitivearray"></a>PrimitiveArray

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

```java
interface PrimitiveArray extends HeapObject
```

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

#### Inherited from

- [HeapObject](#com-jprofiler-api-agent-heap-heapobject) — 5 methods

#### Methods

| Signature | Returns | Description |
|---|---|---|
| [`readData()`](#com-jprofiler-api-agent-heap-primitivearray-readdata) | `ByteBuffer` | Reads the data stored in this primitive array as a `ByteBuffer`. |

<a id="com-jprofiler-api-agent-heap-primitivearray-readdata"></a>##### readData()

```java
@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.

### <a id="com-jprofiler-api-agent-heap-stringinstance"></a>StringInstance

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

```java
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](#com-jprofiler-api-agent-heap-instance) — 2 methods
- [HeapObject](#com-jprofiler-api-agent-heap-heapobject) — 5 methods

#### Methods

| Signature | Returns | Description |
|---|---|---|
| [`value()`](#com-jprofiler-api-agent-heap-stringinstance-value) | `String` | Retrieves the value of this `StringInstance`. |

<a id="com-jprofiler-api-agent-heap-stringinstance-value"></a>##### value()

```java
@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.