A. Sundararajan's Weblog

What's in my Java heap?

As I mentioned earlier, Mustang (Java SE 6) comes with jhat - Java Heap Analysis Tool. We have added more features to jhat as of build 53 (released on Sep, 22, 2005). jhat now comes with mechanism to query the heap. jhat supports OQL - Object Query Language -- a SQL-like language to query your Java heap! HAT always supported simple queries such as "show all instances of class X" (include subclasses or not), "show all referrers to a specific object", "show all objects reachable from a specific object" etc. But, these pre-defined queries (supported by hyperlinks) may always be sufficient to a specific problem in your hand. That is where OQL helps.

OQL query is of the form

select <expression>
[ from [instanceof] <class name> <identifier>
[ where <filter-expression> ] ]

where select, from, where, instanceof are keywords. expression, filter-expression are JavaScript expressions. class name is fully qualified Java class name (example: java.net.URL) or array class name. [C is char array name, [Ljava.io.File; is name of java.io.File[] and so on. If instanceof keyword is used, subtype objects are selected. If this keyword is not specified, only the instances of exact class specified are selected. Both from and where clauses are optional.

In select and (optional) where clauses, the expression used in JavaScript expression. Java heap objects are wrapped as convenient script objects so that fields may be accessed in natural syntax. For example, Java fields can be accessed with obj.field_name syntax and array elements can be accessed with array[index] syntax. Each Java object selected is bound to a JavaScript variable of the identifier name specified in from clause.

identifier is a name bound for each Java heap object that is matching from and where clause. Note that both from and where clauses are optional. Few simple examples, would help in understanding basic OQL.

OQL Examples

    select s from java.lang.String s
    where s.count > 100

will select and show all String instances that have length more than 100. Note that we use the 'count' field of java.lang.String class. If you treat your Java heap as "database", then "classes" are "tables", "objects" are "rows" and "fields" are "columns". How do you "schema" of the "database"? You can use "javap -p" option and get all fields of a specific class.

     select a from [I a where a.length >= 256

will show all int arrays that have 256 or more elements.

    select classof(cl).name 
    from instanceof java.lang.ClassLoader cl

show names of all ClassLoader classes. Note that classof is a OQL built-in function that returns Class object of a given Java object (similar to Object.getClass() method). We will see more OQL examples, built-in functions in future blogs. But, if you are in hurry and want to learn things as soon as possible, then download Mustang binary and run jhat! You may want to refer to Alan's blog on heap dumps to know more about how to get heap dump of your Java application ...

---