JVM OQL查询语言

OQL查询语言

SELECT Clause

The SELECT clause determines what to extract from the heap dump. To display objects and be able to browse the outgoing references, use the * symbol:

SELECT * FROM java.lang.String

Select specific columns

Alternatively, one can select the fields to be displayed:

SELECT toString(s), s.count, s.value FROM java.lang.String s

The resulting table knows about the underlying object. So you can use the context menu to open further views on the object at hand. Use the @ symbol to access Java attributes and methods of the objects. There are also a number of built-in functions available to extract common information:

SELECT toString(s), s.@usedHeapSize,

s.@retainedHeapSize FROM java.lang.String s

The section on Property Accessorscontains details on the commonly available attributes.

Provide column names

Use the AS keyword to name the columns:

SELECT toString(s) AS Value,

s.@usedHeapSize AS "Shallow Size",

s.@retainedHeapSize AS "Retained Size"

FROM java.lang.String s

Use the AS RETAINED SET keyword to get the set of objects retained by your selection:

SELECT AS RETAINED SET * FROM java.lang.String

Flatten select items into an object list

Use the OBJECTS to interpret the items in the SELECT clause as objects:

SELECT OBJECTS dominators(s) FROM java.lang.String s

The function dominators() returns an array of objects. Therefore the query returns a list of object lists, i.e. arrays. By using the keyword OBJECTS , we force the OQL to reduce this into a single list of objects.

Select unique objects

Use the DISTINCT keyword to only select unique objects:

SELECT DISTINCT * FROM OBJECTS 0,1,1,2

Use the DISTINCT OBJECTS keyword to only select unique objects from the result of the selected clause:

SELECT DISTINCT OBJECTS classof(s) FROM java.lang.String s

The function classof returns the class object. Of course, all Strings have the same class. The OBJECTS converts the underlying row with a String object and a displayed value of the class object to the object represented by the result of the classof function. Without the DISTINCT OBJECTS keywords, the query would result in a list with as many rows with the same class as there are Strings.

Expressions (experimental, Memory Analyzer 1.4)

Use the expressions for the select item, including string concatenation:

SELECT s.@objectId, s.@objectId * 2, "The object ID is "+@objectId FROM OBJECTS 0,1,1,2 s

With Memory Analyzer 1.4 expressions and sub-selects are allowed for select items. More complex expressions may need to be parenthesized. This is currently in the test phase.

FROM Clause

Specify the class

The FROM clause defines the classes on which to operate. Specify the class by one of the following means:

by class name:

SELECT * FROM java.lang.String

by a regular expression matching the class name:

SELECT * FROM "java\.lang\..*"

by the object address of the class:

SELECT * FROM 0x2b7468c8

by the object addresses of more than one class:

SELECT * FROM 0x2b7468c8,0x2b74aee0

by the object id of the class:

SELECT * FROM 20815

by the object ids of more than one class:

SELECT * FROM 20815,20975

by a sub select:

SELECT * FROM ( SELECT *

                FROM java.lang.Class c

                WHERE c implements org.eclipse.mat.snapshot.model.IClass )

The statement returns all objects in the heap. The implements check is necessary, as the heap dump can contain java.lang.Class instances caused by proxy classes or classes representing primitive types such as int.class or Integer.TYPE. The following query has the same effect, which calls a method directly on the ISnapshot object:

SELECT * FROM ${snapshot}.getClasses()

Include sub classes

Use the INSTANCEOF keyword to include objects of sub-classes into the query:

SELECT * FROM INSTANCEOF java.lang.ref.Reference

The resulting table contains, amongst others, WeakReference and SoftReference objects because both classes extend from java.lang.ref.Reference . By the way, the same result has the following query

SELECT * FROM ${snapshot}.getClassesByName("java.lang.ref.Reference", true)

Prevent interpretation of the from term as classes

Use the OBJECTS keyword if you do not want to process the term as classes. Specify the object or objects by one of the following means:

by class name:

SELECT * FROM OBJECTS java.lang.String

The result is just one object, the java.lang.String class object.

by the object address of the particular object:

SELECT * FROM OBJECTS 0x2b7468c8

by the object addresses of particular objects:

SELECT * FROM OBJECTS 0x2b7468c8,0x2b746868

by the object id of the particular object:

SELECT * FROM OBJECTS 20815

by the object ids of particular objects:

SELECT * FROM OBJECTS 20815,20814

by a sub expression (Memory Analyzer 1.4 only):

SELECT * FROM OBJECTS (1 + ${snapshot}.GCRoots.length)

Note: Please note, that currently the FROM OBJECTS term is in the test phase!

Autocompletion

The OQL pane now has autocompletion for class names, class name regular expressions, field names, attributes and methods. See OQL autocompletion.

WHERE Clause

>=, <=, >, <, [ NOT ] LIKE, [ NOT ] IN, IMPLEMENTS (relational operations)

The WHERE clause specifies search conditions, that remove unwanted data from the query result. The following operators, are in order of precedence. The operators are evaluated in the specified order:

SELECT * FROM java.lang.String s WHERE s.count >= 100

SELECT * FROM java.lang.String s WHERE toString(s) LIKE ".*day"

SELECT * FROM java.lang.String s WHERE s.value NOT IN dominators(s)

SELECT * FROM java.lang.Class c WHERE c IMPLEMENTS org.eclipse.mat.snapshot.model.IClass

=, != (equality operations)

SELECT * FROM java.lang.String s WHERE toString(s) = "monday"

AND (conditional AND operation)

SELECT * FROM java.lang.String s WHERE s.count > 100 AND s.@retainedHeapSize > s.@usedHeapSize

OR (conditional OR operation)

SELECT * FROM java.lang.String s WHERE s.count > 1000 OR s.value.@length > 1000

Operators can be applied to expressions, constant literals and sub queries. Valid expressions are explained in the next sections.

Literal Expression

Boolean, String, Integer, Long, Character and null literals:

SELECT * FROM java.lang.String s

         WHERE ( s.count > 1000 ) = true

         WHERE toString(s) = "monday"

         WHERE dominators(s).size() = 0

         WHERE s.@retainedHeapSize > 1024L

         WHERE s.value != null AND s.value.@valueArray.@length >= 1 AND s.value.@valueArray.get(0) = 'j'

         WHERE s.@GCRootInfo != null

Property Accessors

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
		clazz	IClass of this object. See also classof(object).
		usedHeapSize	shallow heap size
		retainedHeapSize	retained heap size
		displayName	display name
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.

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

Reading values from primitive arrays

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

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

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

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.

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) evaluates the argument and returns it. Could be useful to allow array/method access to the result of a sub-select or expression.

BNF for the Object Query Language

SelectStatement	::=	"SELECT" SelectList FromClause ( WhereClause )? ( UnionClause )?
SelectList	::=	(( "DISTINCT" | "AS RETAINED SET" )? ( "*" | "OBJECTS" SelectItem | SelectItem ( "," SelectItem )* ))
SelectItem	::=	( PathExpression | EnvVarPathExpression ) ( "AS" ( <STRING_LITERAL> | <IDENTIFIER> ) )?
PathExpression	::=	( ObjectFacet | BuiltInFunction ) ( "." ObjectFacet | "[" SimpleExpression ( ":" SimpleExpression)? "]" )*
EnvVarPathExpression	::=	( "$" "{" <IDENTIFIER> "}" ) ( "." ObjectFacet | "[" SimpleExpression ( ":" SimpleExpression)? "]" )*
ObjectFacet	::=	( ( "@" )? <IDENTIFIER> ( ParameterList )? )
ParameterList	::=	"(" ( ( SimpleExpression ( "," SimpleExpression )* ) )? ")"
FromClause	::=	"FROM" ( "OBJECTS" )? ( "INSTANCEOF" )? ( FromItem | "(" SelectStatement ")" ) ( <IDENTIFIER> )?
FromItem	::=	( ClassName | <STRING_LITERAL> | ObjectAddress ( "," ObjectAddress )* | ObjectId ( "," ObjectId )* | EnvVarPathExpression )
ClassName	::=	( <IDENTIFIER> ( "." <IDENTIFIER> )* ( "[]" )* )
ObjectAddress	::=	<HEX_LITERAL>
ObjectId	::=	<INTEGER_LITERAL>
WhereClause	::=	"WHERE" ConditionalOrExpression
ConditionalOrExpression	::=	ConditionalAndExpression ( "or" ConditionalAndExpression )*
ConditionalAndExpression	::=	EqualityExpression ( "and" EqualityExpression )*
EqualityExpression	::=	RelationalExpression ( ( "=" RelationalExpression | "!=" RelationalExpression ) )*
RelationalExpression	::=	( SimpleExpression ( ( "<" SimpleExpression | ">" SimpleExpression | "<=" SimpleExpression | ">=" SimpleExpression | ( LikeClause | InClause ) | "implements" ClassName ) )? )
LikeClause	::=	( "NOT" )? "LIKE" <STRING_LITERAL>
InClause	::=	( "NOT" )? "IN" SimpleExpression
SimpleExpression	::=	MultiplicativeExpression ( "+" MultiplicativeExpression | "-" MultiplicativeExpression )*
MultiplicativeExpression	::=	PrimaryExpression ( "*" PrimaryExpression | "/" PrimaryExpression )*
PrimaryExpression	::=	Literal
	|	"(" ( ConditionalOrExpression | SubQuery ) ")
	|	PathExpression
	|	EnvVarPathExpression
SubQuery	::=	SelectStatement
Function	::=	( ( "toHex" | "toString" | "dominators" | "outbounds" | "inbounds" | "classof" | "dominatorof" ) "(" ConditionalOrExpression ")" )
Literal	::=	( <INTEGER_LITERAL> | <LONG_LITERAL> | <FLOATING_POINT_LITERAL> | <CHARACTER_LITERAL> | <STRING_LITERAL> | BooleanLiteral | NullLiteral )
BooleanLiteral	::=	"true"
	|	"false"
NullLiteral	::=	<NULL>
UnionClause	::=	( "UNION" "(" SelectStatement ")" )+