# Property Accessors

Copyright (c) 2008, 2023 SAP AG and others. All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which accompanies this distribution, and is available at https://www.eclipse.org/legal/epl-2.0/

# Accessing fields of the heap object

Properties of heap objects are accessed using a simple dot notation:

[ <alias>. ] <field> . <field>. <field>

An alias can be defined in the FROM Clause to identify the current object, i.e. row in the SQL analogy, on which the OQL statement operates. Without alias, the field is assumed to be one of the fields of the current object. Fields are attributes of the Java objects in the heap dump. Use OQL autocompletion or the Object Inspector to find out about the available fields of an object.

# Accessing Java Bean properties

[ <alias>. ] @<attribute> ...

Using the @ symbol, OQL accesses attributes of the underlying Java objects used by Memory Analyzer to represent objects in the heap dump. The attributes are resolved via Bean Introspection. Use OQL autocompletion to find the common beans names. The following table lists some commonly used Java attributes.

Any heap object
IObject
objectId
id of snapshot object
objectAddress
address of snapshot object
class
Java class of this object as a Memory Analyzer object
clazz
IClass of this object. See also classof(object).
outboundReferences
The outbound references as a list of NamedReference objects from this object: the type as IClass of this object; the fields; the array entries. This is retrieved from the heap dump, not an index, so could contain references to unindexed objects.
usedHeapSize
shallow heap size
retainedHeapSize
retained heap size
technicalName
the technical name (a combination of the class name and the object address)
classSpecificName
the value from a name resolver, if available, for example a readable value of a String
displayName
display name, a combination of the technical name and the class specific name
snapshot
the snapshot containing this object. An alternative to ${snapshot}
Class object
IClass
classLoaderId
id of the class loader
Any array
IArray
length
length of the array
Primitive array
IPrimitiveArray
valueArray
the values in the array
Reference array
IObjectArray
referenceArray
the objects in the array (as long values, the addresses of the objects) Access a particular element using get() and convert to an object using OBJECTS.
Class loader object
IClassLoader
definedClasses
the classes defined by the class loader
Object Reference
ObjectReference
object
The IObject which the reference points to
objectId
The id of the IObject which the reference points to. This will fail for unindexed objects.
objectAddress
The address of the IObject which the reference points to. This works for unindexed objects.
Named Reference extends ObjectReference
NamedReference
name
The field name or array index in the form [12357] which describes the reference.

# Calling Java methods

[ <alias> . ] @<method>( [ <expression>, <expression> ] ) ...

Adding ( ) forces OQL to interpret this as a Java method call. The call is executed via reflection. The code is executed inside Memory Analyzer on the objects in the snapshot representing the heap dump. Code from the Java program which generated the dump is not available and is not executed. The following table lists some common Java methods on the underlying Java objects used by Memory Analyzer to represent objects in the heap dump.

${snapshot}
ISnapshot
getClasses()
a collection of all classes
getClassesByName(String name, boolean includeSubClasses)
a collection of classes
Class object
IClass
hasSuperClass()
result is true if the class has a super class
isArrayType()
the result is true if the class is an array type
Any heap object
IObject
getObjectAddress()
The address of a snapshot object as a long integer
Primitive array
IPrimitiveArray
getValueAt(int index)
a value from the array
Java primitive array, Java object array or Java list (returned from reflection)
[] or List
get(int index)
a value from the array or list

# Array Access

Memory Analyzer 1.3 or later allows direct array style access of primitive arrays and objects arrays from the snapshot, and Java arrays and Java Lists obtained from reflective method calls. The notation is [index]. The index is a zero-based integer. If the array is null or the index is out of range then the result is null.

Memory Analyzer 1.4 or later allows array range access as well using the notation [index1:index2] where index1 and index2 are inclusive. If the values are negative then they are treated as indexing from the end of the array, so -1 means the last entry. This means the whole array can be accessed as a list as [0:-1].

# Reading values from primitive arrays (from the heap dump)

SELECT s[2] FROM int[] s WHERE (s.@length > 2)

This method is for Memory Analyzer 1.3 or later.

SELECT s.getValueAt(2) FROM int[] s WHERE (s.@length > 2)

This method is for all versions of Memory Analyzer. This reads the value of the element at index 2 from all int[] arrays which have at least 3 elements.

# Reading objects from object arrays (from the heap dump)

SELECT s[2] FROM java.lang.Object[] s WHERE (s.@length > 2)

This method is for Memory Analyzer 1.3 or later. s[2]is an IObject so fields and Java bean properties can be accessed

SELECT OBJECTS s[2] FROM java.lang.Object[] s

This method is for Memory Analyzer 1.3 or later. The OBJECTS converts the object to give a tree view rather than table result. We do not need the WHERE clause as out of range accesses return null and the OBJECTS skips nulls.

SELECT OBJECTS s.@referenceArray.get(2) FROM java.lang.Object[] s WHERE (s.@length > 2)

This method is for Memory Analyzer 1.1 or later. This reads as a long address the element at index 2 from all Object[] arrays which have at least 3 elements and converts them into objects.

SELECT OBJECTS s.getReferenceArray(2,1) FROM java.lang.Object[] s WHERE (s.@length > 2)

This method is for Memory Analyzer 1.1 or later. This reads as an array of long[] 1 element starting at index 2 from all Object[] arrays which have at least 3 elements and converts the contents of those arrays into objects.

# Reading from Java arrays (Memory Analyzer internal objects)

SELECT s.@GCRoots[2] FROM OBJECTS ${snapshot} s

This method is for Memory Analyzer 1.3 or later.

SELECT s.get(2) FROM OBJECTS ${snapshot} s WHERE s.@GCRoots.@length > 2

This method is for all versions of Memory Analyzer.

# Reading from Java Lists (Memory Analyzer internal objects)

SELECT s.@GCRoots.subList(1,3)[1] FROM OBJECTS ${snapshot} s

This method is for Memory Analyzer 1.3 or later.

SELECT s.@GCRoots.subList(1,3).get(1) FROM OBJECTS ${snapshot} s

This method is for all versions of Memory Analyzer.

# Reading subarrays

SELECT s, s.count, s.offset, s.value[s.offset], s.value[s.offset:((s.offset + s.count) - 1)], s.value[s.offset:((s.offset + 0) - 1)], s.value[0:-1].subList(s.offset,(s.offset + 0)), s.value[s.offset:-1].subList(0,s.count) FROM java.lang.String s

This method is for Memory Analyzer 1.4 or later.

This shows how the whole array can be converted to a list using [0:-1] and that how using array range [offset:offset+count-1] gives perhaps unexpected results when offset=0 and count=0 as instead of an empty list it gives the whole array. Using subList(offset,offet+count) once the whole array has been converted to a list gives the expected result.

# Collection access

SELECT a[0] FROM java.util.ArrayList a

Many of the standard collections classes are well known by Memory Analyzer. The collection queries allow analysis of lists, sets, queues, deques and maps. This access is extended to OQL so if the collection queries work with a particular collection or map then so does OQL.

Collection and map access is still experimental and subject to change.

SELECT a[0:-1] FROM java.util.ArrayList a

If the array access syntax is used on a collection (list,set, queue, deque) object then particular elements of the collection can be extracted. If subarray syntax is used then that part of collection is converted to a list ready for further processing

SELECT h[0].@key, h[0].@value FROM java.util.HashMap h

If the array access syntax is used on a map then the map is converted to a list of map entries. These can then be examined using the bean access syntax to retrieve the key h[0].@key or value h[0].@value. See Wiki OQL Map processing for more details of OQL with maps and collections.

# Built-in OQL functions

<function>( <parameter> )

Built-in functions.

toHex( number )
Print the number as hexadecimal
toString( object )
Returns the value of an object, e.g. the content of a String etc.
dominators( object )
The objects immediately dominated by the object
outbounds( object )
outbound referrer
inbounds( object )
inbound referrer
classof( object )
the class of the current object
dominatorof( object )
the immediate dominator, -1 if none
eval( expression )
(Experimental in Memory Analyzer 1.4 or later) evaluates the argument and returns it. Could be useful to allow array/method access to the result of a sub-select or expression.